Gantt

The contract

Six rules. Everything else on this page follows from them, and most of the surprises come from forgetting one.

• Dates are strings. yyyy-MM-dd, never a Date, and end is the last day worked, not the day after: a one-day task has start === end. Inside, each date is a whole number of days since 1970-01-01 — no time, no time zone, no 23-hour day when the clocks change. A deadline of 13 November is the same column in Hà Nội and in San Francisco.
• Controlled. items and dependencies go in; onItemChange and onDependencyCreate come out. While a bar is being dragged it follows a draft inside the component, and you hear about it once, on drop — not sixty times a second. Each arrow-key press is one call; batch them yourself if each one is a request.
• A flat list, in display order. No sorting, no tree, no folding. You keep the tree, leave out the children of a folded row, and pass depth, hasChildren and expanded so the left column can draw it.
• The critical path is yours. It depends on working calendars, lags and each app’s rules, so the package does not compute it. Set critical on items and dependencies; the Gantt gives those bars a 2px --destructive-ink border and those arrows a solid 2px red line.
• A broken dependency is the package’s to find. Four relation types, checked on dates with both ends inclusive: finish-to-start wants the next task to start after the day the first one ends; start-to-start, not to start before it; finish-to-finish, not to end before it; start-to-finish, not to end before it starts. A broken one is a dashed red arrow — redrawn while you drag — and the later task gets the sentence “Starts before a task it depends on” for screen readers.
• Colour is a tone. Eleven names, each with a fill, a text colour on that fill and an ink for borders, so a bar follows dark mode and the high-contrast palette. No free colour: a hex code cannot be checked for contrast.

import { Gantt, type GanttDependency, type GanttItem } from '@comitor/ui'

const items: GanttItem[] = [
  // One row per entry, in display order. depth only indents and sets aria-level.
  { id: 'otc', title: 'Sign in with a one-time code', type: 'summary', start: '2026-10-26', end: '2026-11-13',
    hasChildren: true, expanded: true },
  { id: 'DS-406', title: 'Send the code by email', depth: 1, start: '2026-11-02', end: '2026-11-05',
    tone: 'teal', progress: 60, critical: true },          // end is INCLUSIVE: four days
  { id: 'DS-388', title: 'Rate-limit the one-time codes', depth: 1, start: '2026-11-05', end: '2026-11-10',
    tone: 'orange' },
  { id: 'DS-414', title: 'Load-test the code endpoint', depth: 1 },   // no dates: unscheduled, no bar
  { id: 'qa', title: 'Sign-in ready for QA', type: 'milestone', depth: 1, start: '2026-11-13' },
]

const dependencies: GanttDependency[] = [
  // finish-to-start by default. DS-388 starts the day DS-406 ends: the package
  // flags it — a dashed red arrow, and "Starts before a task it depends on".
  { id: 'l3', from: 'DS-406', to: 'DS-388' },
]

<Gantt className="h-[32rem]" items={items} dependencies={dependencies} onItemChange={save} />

A sprint

Two groups, seven tasks, two milestones. DS-406 → DS-407 → QA → Release is marked as the critical path; DS-388 starts the day DS-406 ends, which breaks its finish-to-start link, so its arrow is dashed. DS-414 has no dates yet — hover its row and click to give it some. DS-405 is done and read-only. Wednesday 11 November is the team’s day off, in nonWorkingDays. Everything that comes out of the Gantt is printed under it: that line is the whole API surface you save from.

• Drag a bar to move it, or one of its edges to resize it; the dates appear at both ends while you do, and the view scrolls when you reach its edge. Esc mid-drag puts the bar back.
• Link by hovering a bar and dragging the dot after its end onto another bar. A summary cannot be either end of a link, nor can a row with no dates.
• Click an arrow and onDependencyClick fires — the demo only reports it. Double-click a bar, or click a name, for onItemOpen.
• The critical path does not follow your drags. The page set those flags by hand; your app recomputes them after each save.
• A bar narrower than 56px writes its name beside it instead of inside. A bar scrolled out of view leaves a round chevron at the edge of the axis that scrolls back to it.

Folding is the app’s

The Gantt draws a chevron on any row with hasChildren and points it by expanded, and that is all. Clicking it — or Space — calls onExpandedChange; leaving the children out of items is your job. The same goes for summary bars: their dates are whatever you pass, so this demo spans each one over its children on every render. Drag the Tasks 2.0 ships diamond to the right and Launch and Comitor Tasks 2.0 stretch with it; drag it left of Beta’s end and its link breaks. Discovery starts folded, and its link into Gantt view is gone with it: a dependency whose end is not in items is skipped.

The records here have the same shape as Tree View’s — parentId plus array order, the way a SQL table with parent_id and position returns them — so one list can feed an outline on one side and the Gantt on the other. Reordering and re-parenting happen in the outline: a bar cannot be dragged to another row.

A roadmap

The same component at the far end of the zoom: projects instead of tasks, months and quarters instead of days, milestones where a project lands. range pins the axis to a fiscal year instead of padding it around the bars, and toolbar={false} swaps the built-in bar for the app’s own — three scale buttons built from GANTT_SCALES, because a roadmap has no use for days. The High-contrast audit is finished and read-only.

Five scales

GANTT_SCALES lists them from near to far. Each one fixes how wide a day is, what the two header rows count, how far Shift + an arrow moves a bar, how much the axis is padded around the bars when there is no range, and how long a click makes an unscheduled task. At month and beyond a day is under 5px, so weekends and holidays are no longer shaded — they would only be noise.

On first render today stands a third of the way across the view — what is ahead usually matters more than what is behind. A bar is never narrower than 6px, so it can still be grabbed at year scale, where a day is half a pixel. Today is a gold chip in the header and a line down the rows; at day scale the chip is the day’s own number.

Tones and shapes

Every tone, read-only. A task bar uses the same soft tint as StatusPill and the letter avatar: --x at 15% over an opaque card fill, with its name and border in --x-ink. The border is what holds it apart from the page — the tint alone is too faint. primary takes the avatar's gold pair (gold-100 / gold-600) and neutral writes in --foreground. Marks with no text — the summary bar, the milestone diamond, the progress strip — use the -ink step alone, since they carry the information themselves; the default neutral tone draws them in --muted-foreground. red paints with --destructive, the one red meant to carry text. Switch the site to dark mode and every bar follows; the high-contrast palette (data-contrast="high") reaches them the same way.

Keyboard

Everything a drag does to dates, a key does too. The arrow keys move dates only on an editable task or milestone — not on a summary, a read-only row, a row without dates, or a Gantt without onItemChange. On a Mac, Alt is ⌥.

Two things have no key. Linking is a pointer gesture — and a mouse one at that, since the dot is hidden on touch screens — so an app needs another way to add a dependency: an Add dependency item in the task’s menu, which is why onDependencyCreate receives plain data. Removing one is the same story, since onDependencyClick lives on the arrow. Scheduling an unscheduled task is a click on its empty row; from the keyboard it takes a date field in the task’s detail view.

Language

The 24 strings of the gantt namespace follow the nearest ComitorLocaleProvider — English by default, Vietnamese built in (set the language once, at the root). So do the dates: every date in the header is written by Intl.DateTimeFormat in the provider’s locale. The task names stay as they are — they are the app’s data. The demo starts in Vietnamese: focus a row and press →, and the line under it prints what the live region says; then switch the language and do it again.

• labels is Partial<GanttLabels>, merged key by key: the component’s own prop wins, then the nearest provider, then English.
• Of those, 8 are functions, because a date, a number or a name sits inside the sentence and word order differs by language. Dates arrive already formatted in the provider’s locale — the function only builds the sentence. Functions cannot cross from a Server Component into a client one, so set them in a client component.
• The provider chooses the strings; it does not set lang. Keep <html lang> in step, as the demo does for its own region.

Read live from comitorMessagesEn.gantt and comitorMessagesVi.gantt, with dates as each locale formats them.

Props

Exported beside the component: GANTT_SCALES and the types GanttItem, GanttDependency, GanttDependencyType, GanttItemChange, GanttDependencyDraft, GanttScale, GanttTone and GanttLabels.

Gantt

GanttItem

GanttDependency

GanttItemChange and GanttDependencyDraft

Known limitations

• Give it a height. The frame is a flex column and the rows scroll inside it. Without a height the Gantt grows to fit every row, its header scrolls away with the page, and the virtualiser has nothing to save.
• Rows do not move. A bar drags along its own row only; reordering and changing parent belong to Tree View beside it.
• The calendar is linear. Weekends and nonWorkingDays are shaded, not skipped: a task is as long as its calendar days, and a drag can land it on a Sunday.
• Linking and scheduling have no keyboard path, and linking none on touch (see Keyboard). New links are always finish-to-start, and the package checks neither for duplicates nor for cycles.
• No baselines, no Ctrl + wheel zoom, and no way to scroll to a date from outside — the Today button lives in the built-in toolbar.
• Pointer changes are not announced. Only key presses reach the live region; a drag reports to onItemChange silently.

Accessibility

• A treegrid of two columns: a rowheader with the name, and a gridcell for the axis that holds a visually hidden sentence — the dates and the number of days, the progress, “On the critical path”, “Starts before a task it depends on”. Rows carry aria-level, aria-expanded when they have children, and aria-selected on the current one; the grid carries aria-rowcount, aria-colcount and, when nothing can be edited, aria-readonly.
• Bars, milestones and arrows are pictures, hidden from assistive technology; what they do is on the row. The keyboard instructions are a hidden paragraph wired with aria-describedby, and each change made from the keyboard is spoken through a polite live region.
• Colour is never alone. A bar stands off the page by its -ink border, at least 3:1 (WCAG 1.4.11); the critical path is also thicker; a broken link is also dashed.
• On touch screens (pointer: coarse) rows are 44px and bars 32px; resize handles are 44px wide and straddle the bar’s edge, and a bar under 96px keeps only its end handle, outside it, so the body is still there to hold. Bars set touch-action: none; empty parts of the axis still scroll.
• What the app still has to do. Offer a keyboard way to add and remove a dependency and to give an unscheduled task its dates. Name the grid with aria-label when a page has more than one. Keep lang in step with the provider. And mark the critical path for real — a flag left stale after a drag is a wrong sentence read aloud.

Related