Gantt Chart

Demo & usage

More examples

When to use

• Planning and tracking project schedules with dependencies and resourcing.
• You need critical path, baselines, or resource leveling on a roadmap.
• For a simple status board without dates, use the Kanban Board.

Async states

• loading
• empty
• error
• retry

Item identity & owned state

Restorable state

• collapsedTaskIds
• pendingTaskIds
• resourceViewCollapsedIds

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Saved state

Stored kinds

• sv-gantt-chart/hierarchy
• sv-gantt-chart/project
• sv-gantt-chart/split-view

What you will find under your own storage key. You choose the key; the blob names its own kind and schema version, so a component never reads state another one wrote.

Reading it back

Restore through the component's own restore… helper rather than casting the parsed JSON. A blob from an older release is migrated where it can be and refused with a reason where it cannot — so an upgrade never silently applies last month's shape to this month's fields.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `tasks`, `loading` and `error`.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Configurable columns, holidays and work week.
• **The scheduling invariants, as guarantees rather than current behaviour.** Links: `fs` starts the successor no earlier than the predecessor finishes, `ss` no earlier than it starts, `ff` finishes no earlier than it finishes, `sf` finishes no earlier than it starts — each plus `lag`, in whole days, negative for a lead, defaulting to `fs` when no type is given. Every one is a floor and never a ceiling: a task is never pulled earlier than the date you gave it, so hand-typed dates survive. `sf` is the one that surprises — "may not finish before the other starts" is satisfied by being early, so an `sf` successor can legitimately land entirely before its predecessor.
• **Pinned, unschedulable and derived.** A `scheduleMode: 'manual'` task keeps its dates whatever its predecessors require, and still constrains its own successors. A task in a cycle keeps the dates it was given, is named in `scheduleCycles()`, and is never critical — a plan that cannot be executed has no critical path. A dependency naming an absent task is ignored and reported. `projectFinish` is the latest early finish; `totalFloat` is late start minus early start in whole days; a task is critical exactly when its float is zero and it is not in a cycle. Spans are whole calendar days, so a DST transition inside one changes nothing.
• **Resource leveling.** Only ever moves a task later, never earlier; preserves every duration in calendar days; leaves no two tasks of one assignee sharing a day, including the handover day; is idempotent, so a second pass moves nothing; touches only leaf tasks that have an assignee; and costs one undoable command however many tasks move.
• **MS Project XML fidelity, field by field.** Carried unchanged: title, start, end, progress, `scheduleMode`, `baselineStart` / `baselineEnd`, assignee, group, lane, priority, status, tags, summary, colour, WBS, split `segments`, and all four `constraints` bounds. Carried in meaning but re-keyed: `id`, `parentId`, `children` (flattened to `parentId`) and `dependencies[].taskId`, because MSPDI identifies tasks by integer `UID`. Not carried, deliberately: `ownerId` (re-derived from the file's assignments, so writing it too would give one fact two sources of truth), `reallocated` (computed by the levelling pass, never authored) and `milestone: false` (absent and false say the same thing).
• **Where the fidelity comes from, and what MS Project itself will honour.** Link `lag` is written as MSPDI `LinkLag` in days, and baselines and `scheduleMode` as `<Baseline>` and `<Manual>` — all native fields, so MS Project schedules against them. The fields MS Project has no column for — group, colour, lane, status, tags, `segments` and `constraints` — travel in `<Notes>` as bracketed markers, so this kit round-trips them while MS Project shows them as text. `constraints` is the one place its model is genuinely narrower: it holds one constraint per task where this kit holds up to four bounds, so its own scheduler will not enforce them on a file it opens.
• An imported colour is validated before it is used: `color` reaches the DOM as a class list, so a file may only name colour utilities (`bg-`, `text-`, `border-`, `ring-`, `from-`, `via-`, `to-`, optionally `dark:`-qualified) and only a few of them. A file that tries to hand a bar layout classes gets the default colour instead of painting over your page. One consequence for your own data: an arbitrary-value class such as `bg-[#ff0000]` does not survive a round trip — brackets are what delimits a marker — so use palette utilities on `color` if the plan will be exported.
• `maxTimelineColumns` (default 480) caps the time axis. Rows are virtualized on height; columns are bounded by coarsening the scale, so a plan whose span grows over time cannot silently turn into thousands of columns. Raise it when rendering to paper or a very wide screen, lower it for embedded and mobile hosts.
• Scheduling modes, baselines and dependency links, each with optional `lag` in days (negative for a lead).
• A real critical path method: forward and backward pass, `taskFloat()` in whole days, `scheduleCycles()` for unschedulable data, and all four link types honoured in both directions. Manually scheduled tasks stay put and still constrain what follows them.
• `tasksChangeRequest` (with `rollback()`), `rangeChange`, `loading` / `error` / `retry` and `pendingTaskIds` make it wireable to a real planner API; `tasksChange` remains for hosts that only persist. `isLoading` is deprecated in favour of `loading`.

Best practices

• Do: Define `workWeek` and `holidays` so durations reflect real working time.
• Do: Persist edits by handling `tasksChangeRequest` — same payload as `tasksChange` plus a `rollback()` that undoes the optimistic edit when the write fails.
• Do: Pin `windowStart` / `windowEnd` to the span you fetched. Left unpinned, the timeline sizes itself to the data, so one task in 2027 stretches the chart across three years — and fetching by `rangeChange` then feeds itself.
• Do: Bind `pendingTaskIds` while a save is in flight: those bars dim and stop responding to drag, so a second edit cannot race the first.
• Tip: Turn on `highlightCritical` to make the schedule's risk path obvious — but read `taskFloat()` for the rest of the plan, because "not critical" spans everything from one spare day to three spare months.
• Do: Put the gap on the link as `lag`, never into the successor's dates. A hand-typed gap does not move when the predecessor slips, which is the one moment it needed to.
• Do: Check `scheduleCycles()` on data you did not author. A cycle is a plan that cannot be executed, and it is invisible on the chart.
• Don't: Don't expect working-day scheduling from the critical path: it counts calendar days, because the bars it is drawn over do. `workWeek` and `holidays` shade the timeline, they do not compress durations.
• Tip: Scale limits, measured rather than claimed. **Up to ~1,000 tasks** is comfortable at any span: ~8,500 DOM nodes, and a full recompute after an edit under 50ms. **1,000–5,000 tasks** still works but wants the advice below — 5,000 tasks is ~40,000 DOM nodes and a first render measured in seconds. **Past ~5,000 visible tasks, split the plan** into portfolio and project charts rather than tuning one. Dependencies are effectively free: the critical path is O(tasks + links), so a 5,000-link chain costs ~36ms.
• Do: Cut the number of *visible* rows, because that is the number the cost actually follows — not the number of tasks you own. Pinning `windowStart` / `windowEnd` and collapsing parents both work; a 5,000-task plan showing 300 rows behaves like a 300-task plan.
• Tip: Bars are row-virtualized automatically past `bodyScrollHeight`, so the timeline's cost is flat in the task count. What is not virtualized is the accessibility table — one row per visible row, 7 DOM nodes each, 86% of the DOM at 5,000 tasks. That is deliberate: it is the whole chart for anyone who cannot see the bars, and a windowed table would be a partial one.
• Do: Leave `maxTimelineColumns` (default 480) alone unless you know you want the columns. A ten-year plan left at `scale="day"` would be 3,661 columns and ~1.4s of render, so the scale coarsens a step at a time — day → week → month → quarter — until it fits, and says so in the notice strip if it clamps a zoom you asked for.
• Tip: Resource leveling moves an unbounded number of tasks but costs one command, one recompute and one undo entry: 400 tasks on one assignee levels in ~140ms, and a single Undo puts all 399 moved tasks back.
• Don't: Don't treat task ids as stable across an MS Project XML round trip. MSPDI identifies tasks by integer `UID`, so ids are re-minted on import — `parentId` and every `dependencies[].taskId` are rewritten to match, so the graph survives, but a `taskId` you stored elsewhere will not resolve.
• Tip: A plan can go out to MS Project and come back without losing a field, including the ones MS Project has no column for — see the fidelity contract below for the exact list. If you import files from elsewhere, note that a `lag` given in hours is rounded to the nearest day, and a segment or constraint with an unparseable date is dropped rather than drawn.

Accessibility

• A bar's position IS its dates, so the chart publishes a table alongside it — task, start, end, progress, status and assignee, one row per visible row and in the same order. Nothing else on the page carries those dates. It mirrors what is drawn: collapsed children are absent, a nested chart gains a Parent column so the hierarchy is not left to the indent, and a milestone reads "Milestone" rather than a second identical date.
• A one-line overview above the table gives the row count, the span the schedule covers and how many rows are critical or at risk — the shape of the picture, which the rows can only imply.
• A resource-view header names its own task count and reads its number as "% utilised", because that column means utilisation there and a listener has no indent to tell them the row is a grouping.
• The chart is a focusable region with a labelled toolbar; toolbar actions expose disabled state via `aria-disabled`.
• Keyboard task selection and movement; command notices use polite live regions and loading sets `aria-busy`.
• Row headers and dates are screen-reader friendly.