Gantt
The complete chart: data, layout, callbacks, and accessible labels.
Usage
"use client";
import { Gantt, type GanttTask } from "@art-tools/react-gantt";
import "@art-tools/react-gantt/style.css";
const tasks: GanttTask[] = [
{ id: 1, name: "Design", startDate: new Date(2026, 0, 5), duration: 3 },
];
export function Chart() {
return <Gantt tasks={tasks} height={420} />;
}- Import @art-tools/react-gantt/style.css once at your application entry point. Render the chart inside a client boundary in Next.js.
- tasks is required. Keep the seed array stable and use apiRef for edits. onTasksChange reports the resolved task list; it is not a controlled-value setter to feed directly back into tasks.
- height is optional: set it to enable vertical scrolling with pinned headers, or omit it to grow with content. rowHeight defaults to 36px, defaultTaskListWidth to 280px, and the default month/day zoom level uses 40px columns.
- readOnly defaults to false. It removes built-in editing controls while selection, scrolling, zoom, and imperative edits remain available. showBaselines defaults to true; criticalPath defaults to false.
- Keep labels and slot configuration objects referentially stable to avoid unnecessary row and bar renders.
Gantt
Componentexport declare function Gantt(props: GanttProps): JSX.Element;GanttProps
TypeProps of the all-in-one `<Gantt>`: the engine plus layout and slots.
| Property | Type & description |
|---|---|
tasksRequired | GanttTask[] |
rowHeightOptional | numberLive-bar area height in px. Defaults to 36; baseline lanes add to it. |
timelineElementsOptional | readonly GanttTimelineElement[]Date-anchored overlays; do not expand the timeline. |
baselineLayoutOptional | {
/** Line thickness, including milestone marker size. Defaults to 4. */
height?: number;
/** Padding at each vertical edge of the baseline strip. Defaults to 1. */
padding?: number;
/** Gap between baseline lanes. Defaults to 2. */
gap?: number;
}Baseline dimensions in px; omitted fields use the existing defaults. |
colWidthOptional | number |
heightOptional | numberTotal component height in px. When set, rows scroll vertically within it (calendar/header stay pinned); omit to grow with content. |
scalesOptional | Scale[] |
padDaysOptional | number |
zoomLevelsOptional | ZoomLevel[]Custom zoom ladder (coarse → fine). Defaults to the built-in ladder; when omitted, `scales`/`colWidth` seed the default rung. |
defaultZoomIndexOptional | numberStarting rung of the zoom ladder (default: the month/day level). |
onZoomChangeOptional | (state: {
index: number;
count: number;
}) => voidFired when the zoom level changes (and once on mount). |
zoomWheelOptional | booleanEnable Ctrl/Cmd + mouse-wheel zoom over the grid (anchors on the cursor). |
zoomKeyboardOptional | booleanEnable +/- keyboard zoom when the grid is focused. |
onTaskClickOptional | (task: GanttTask) => void |
dependenciesOptional | TaskDependency[] |
onDependencyCreateOptional | (dep: TaskDependency) => void |
onDependencyDeleteOptional | (dep: TaskDependency) => void |
onTaskCreateOptional | (task: GanttTask, afterId?: Id | null) => void |
onTaskDeleteOptional | (id: Id) => void |
onTaskEditOptional | (task: GanttTask) => voidFired when a column's edit action is invoked (e.g. the actions-column pencil button). |
onTasksChangeOptional | (tasks: GanttTask[]) => voidFired with the resolved task list whenever it changes (after create/delete/edit/undo/redo). |
calendarOptional | GanttCalendarWorking-time calendar. Supplying it is the opt-in: with no `calendar` the chart schedules in plain linear time exactly as before. Safe to write inline — it is keyed by content, not identity. |
snapToWorkingOptional | booleanSnap library-authored dates (drag commits, cascade results) onto working time. Defaults to `true` when a `calendar` is supplied; `false` keeps the non-working shading but leaves dates untouched. |
durationUnitOptional | DurationUnitHow an input `duration` is interpreted and displayed. Defaults to `"day"`. |
readOnlyOptional | booleanRemove every editing affordance: bars stop moving/resizing, the progress handle and dependency connectors disappear, links can no longer be selected or deleted, and the built-in actions column is dropped. Viewing is untouched — selection, expand/collapse, scroll and zoom all still work — and so is `apiRef`: `readOnly` is about the pointer, not the data (see ADR-021). Custom `columns` are yours to gate; read `api.readOnly` in `render`. |
criticalPathOptional | booleanHighlight the critical path — the chain of tasks and dependency links that currently have zero working-time float before the chart's actual end date would move. Off by default; charts that do not set it render byte-identically to today (ADR-023). |
showBaselinesOptional | booleanShow baseline plans. Defaults to `true`. When false, baseline lines, accessible descriptions, row strips, and date-axis extent are omitted. Consumer baseline data and live edits are preserved (ADR-025). |
apiRefOptional | React.Ref<GanttHandle>Receives the imperative API: `apiRef.current.createTask(...)`, `.undo()`, etc. |
labelsOptional | GanttLabelsOverrides for the library's accessible strings (screen-reader names). Pass a referentially stable object — see `GanttLabels`. |
columnsOptional | ColumnDef[] |
defaultTaskListWidthOptional | number |
hideTaskListOptional | boolean |
taskListOptional | GanttTaskListSlotsSlot overrides for the task-list pane (`treeCell`, `header`). Prop-drilled. Pass a referentially stable object — rows are memoized, so a fresh object each render re-renders every row. |
barsOptional | GanttBarsSlotsSlot overrides for the timeline bars and their handles. |
dependencySlotsOptional | GanttDependenciesSlotsSlot overrides for dependency links (named `dependencySlots` to avoid colliding with the `dependencies` data prop above). |
timelineOptional | GanttTimelineSlotsSlot overrides for the calendar/grid timeline chrome. |
TypeScript declaration
/** Props of the all-in-one `<Gantt>`: the engine plus layout and slots. */
export declare interface GanttProps extends GanttEngineProps {
columns?: ColumnDef[];
defaultTaskListWidth?: number;
hideTaskList?: boolean;
/**
* Slot overrides for the task-list pane (`treeCell`, `header`). Prop-drilled.
* Pass a referentially stable object — rows are memoized, so a fresh object each
* render re-renders every row.
*/
taskList?: GanttTaskListSlots;
/** Slot overrides for the timeline bars and their handles. */
bars?: GanttBarsSlots;
/** Slot overrides for dependency links (named `dependencySlots` to avoid
* colliding with the `dependencies` data prop above). */
dependencySlots?: GanttDependenciesSlots;
/** Slot overrides for the calendar/grid timeline chrome. */
timeline?: GanttTimelineSlots;
}GanttEngineProps
TypeEverything the chart engine needs: data, callbacks, scheduling, zoom. Shared verbatim by `<Gantt>` and `<GanttProvider>` — `<Gantt>` destructures every one of these and forwards it untouched, then adds layout and slots of its own. Declared once so the two cannot drift apart, which they already had: `GanttProps.height` was required while the provider's was optional, with a doc on the required one saying "omit to grow with content".
| Property | Type & description |
|---|---|
tasksRequired | GanttTask[] |
rowHeightOptional | numberLive-bar area height in px. Defaults to 36; baseline lanes add to it. |
timelineElementsOptional | readonly GanttTimelineElement[]Date-anchored overlays; do not expand the timeline. |
baselineLayoutOptional | {
/** Line thickness, including milestone marker size. Defaults to 4. */
height?: number;
/** Padding at each vertical edge of the baseline strip. Defaults to 1. */
padding?: number;
/** Gap between baseline lanes. Defaults to 2. */
gap?: number;
}Baseline dimensions in px; omitted fields use the existing defaults. |
colWidthOptional | number |
heightOptional | numberTotal component height in px. When set, rows scroll vertically within it (calendar/header stay pinned); omit to grow with content. |
scalesOptional | Scale[] |
padDaysOptional | number |
zoomLevelsOptional | ZoomLevel[]Custom zoom ladder (coarse → fine). Defaults to the built-in ladder; when omitted, `scales`/`colWidth` seed the default rung. |
defaultZoomIndexOptional | numberStarting rung of the zoom ladder (default: the month/day level). |
onZoomChangeOptional | (state: {
index: number;
count: number;
}) => voidFired when the zoom level changes (and once on mount). |
zoomWheelOptional | booleanEnable Ctrl/Cmd + mouse-wheel zoom over the grid (anchors on the cursor). |
zoomKeyboardOptional | booleanEnable +/- keyboard zoom when the grid is focused. |
onTaskClickOptional | (task: GanttTask) => void |
dependenciesOptional | TaskDependency[] |
onDependencyCreateOptional | (dep: TaskDependency) => void |
onDependencyDeleteOptional | (dep: TaskDependency) => void |
onTaskCreateOptional | (task: GanttTask, afterId?: Id | null) => void |
onTaskDeleteOptional | (id: Id) => void |
onTaskEditOptional | (task: GanttTask) => voidFired when a column's edit action is invoked (e.g. the actions-column pencil button). |
onTasksChangeOptional | (tasks: GanttTask[]) => voidFired with the resolved task list whenever it changes (after create/delete/edit/undo/redo). |
calendarOptional | GanttCalendarWorking-time calendar. Supplying it is the opt-in: with no `calendar` the chart schedules in plain linear time exactly as before. Safe to write inline — it is keyed by content, not identity. |
snapToWorkingOptional | booleanSnap library-authored dates (drag commits, cascade results) onto working time. Defaults to `true` when a `calendar` is supplied; `false` keeps the non-working shading but leaves dates untouched. |
durationUnitOptional | DurationUnitHow an input `duration` is interpreted and displayed. Defaults to `"day"`. |
readOnlyOptional | booleanRemove every editing affordance: bars stop moving/resizing, the progress handle and dependency connectors disappear, links can no longer be selected or deleted, and the built-in actions column is dropped. Viewing is untouched — selection, expand/collapse, scroll and zoom all still work — and so is `apiRef`: `readOnly` is about the pointer, not the data (see ADR-021). Custom `columns` are yours to gate; read `api.readOnly` in `render`. |
criticalPathOptional | booleanHighlight the critical path — the chain of tasks and dependency links that currently have zero working-time float before the chart's actual end date would move. Off by default; charts that do not set it render byte-identically to today (ADR-023). |
showBaselinesOptional | booleanShow baseline plans. Defaults to `true`. When false, baseline lines, accessible descriptions, row strips, and date-axis extent are omitted. Consumer baseline data and live edits are preserved (ADR-025). |
apiRefOptional | React.Ref<GanttHandle>Receives the imperative API: `apiRef.current.createTask(...)`, `.undo()`, etc. |
labelsOptional | GanttLabelsOverrides for the library's accessible strings (screen-reader names). Pass a referentially stable object — see `GanttLabels`. |
TypeScript declaration
/**
* Everything the chart engine needs: data, callbacks, scheduling, zoom.
*
* Shared verbatim by `<Gantt>` and `<GanttProvider>` — `<Gantt>` destructures
* every one of these and forwards it untouched, then adds layout and slots of its
* own. Declared once so the two cannot drift apart, which they already had:
* `GanttProps.height` was required while the provider's was optional, with a doc
* on the required one saying "omit to grow with content".
*/
export declare interface GanttEngineProps {
tasks: GanttTask[];
/** Live-bar area height in px. Defaults to 36; baseline lanes add to it. */
rowHeight?: number;
/** Date-anchored overlays; do not expand the timeline. */
timelineElements?: readonly GanttTimelineElement[];
/** Baseline dimensions in px; omitted fields use the existing defaults. */
baselineLayout?: {
/** Line thickness, including milestone marker size. Defaults to 4. */
height?: number;
/** Padding at each vertical edge of the baseline strip. Defaults to 1. */
padding?: number;
/** Gap between baseline lanes. Defaults to 2. */
gap?: number;
};
colWidth?: number;
/** Total component height in px. When set, rows scroll vertically within it
* (calendar/header stay pinned); omit to grow with content. */
height?: number;
scales?: Scale[];
padDays?: number;
/** Custom zoom ladder (coarse → fine). Defaults to the built-in ladder; when
* omitted, `scales`/`colWidth` seed the default rung. */
zoomLevels?: ZoomLevel[];
/** Starting rung of the zoom ladder (default: the month/day level). */
defaultZoomIndex?: number;
/** Fired when the zoom level changes (and once on mount). */
onZoomChange?: (state: {
index: number;
count: number;
}) => void;
/** Enable Ctrl/Cmd + mouse-wheel zoom over the grid (anchors on the cursor). */
zoomWheel?: boolean;
/** Enable +/- keyboard zoom when the grid is focused. */
zoomKeyboard?: boolean;
onTaskClick?: (task: GanttTask) => void;
dependencies?: TaskDependency[];
onDependencyCreate?: (dep: TaskDependency) => void;
onDependencyDelete?: (dep: TaskDependency) => void;
onTaskCreate?: (task: GanttTask, afterId?: Id | null) => void;
onTaskDelete?: (id: Id) => void;
/** Fired when a column's edit action is invoked (e.g. the actions-column pencil button). */
onTaskEdit?: (task: GanttTask) => void;
/** Fired with the resolved task list whenever it changes (after create/delete/edit/undo/redo). */
onTasksChange?: (tasks: GanttTask[]) => void;
/**
* Working-time calendar. Supplying it is the opt-in: with no `calendar` the
* chart schedules in plain linear time exactly as before. Safe to write inline —
* it is keyed by content, not identity.
*/
calendar?: GanttCalendar;
/**
* Snap library-authored dates (drag commits, cascade results) onto working
* time. Defaults to `true` when a `calendar` is supplied; `false` keeps the
* non-working shading but leaves dates untouched.
*/
snapToWorking?: boolean;
/** How an input `duration` is interpreted and displayed. Defaults to `"day"`. */
durationUnit?: DurationUnit;
/**
* Remove every editing affordance: bars stop moving/resizing, the progress
* handle and dependency connectors disappear, links can no longer be selected
* or deleted, and the built-in actions column is dropped.
*
* Viewing is untouched — selection, expand/collapse, scroll and zoom all still
* work — and so is `apiRef`: `readOnly` is about the pointer, not the data (see
* ADR-021). Custom `columns` are yours to gate; read `api.readOnly` in `render`.
*/
readOnly?: boolean;
/**
* Highlight the critical path — the chain of tasks and dependency links that
* currently have zero working-time float before the chart's actual end date
* would move. Off by default; charts that do not set it render byte-identically
* to today (ADR-023).
*/
criticalPath?: boolean;
/**
* Show baseline plans. Defaults to `true`. When false, baseline lines,
* accessible descriptions, row strips, and date-axis extent are omitted.
* Consumer baseline data and live edits are preserved (ADR-025).
*/
showBaselines?: boolean;
/** Receives the imperative API: `apiRef.current.createTask(...)`, `.undo()`, etc. */
apiRef?: React.Ref<GanttHandle>;
/**
* Overrides for the library's accessible strings (screen-reader names).
* Pass a referentially stable object — see `GanttLabels`.
*/
labels?: GanttLabels;
}GanttLabels
TypeOverrides for every accessible string the library emits. Pass any subset via `<Gantt labels={...} />`; omitted keys keep their English defaults (see `DEFAULT_LABELS` in `core/labels.ts`). NOTE: pass a referentially stable / memoized object — a fresh object each render invalidates the labels context and re-renders every row and bar.
| Property | Type & description |
|---|---|
ganttOptional | stringAccessible name for the whole widget. Default: `"Gantt chart"`. |
taskListOptional | stringAccessible name for the task-list treegrid. Default: `"Task list"`. |
timelineOptional | stringAccessible name for the timeline grid. Default: `"Timeline"`. |
expandOptional | stringExpand toggle, collapsed state. Default: `"Expand"`. |
collapseOptional | stringExpand toggle, expanded state. Default: `"Collapse"`. |
resizeTaskListOptional | stringThe task-list / timeline splitter. Default: `"Resize task list"`. |
deleteDependencyOptional | stringThe dependency-link delete button. Default: `"Delete dependency"`. |
editTaskOptional | (task: GanttTask) => stringActions-column edit button. Default: `` `Edit ${task.name}` ``. |
addTaskAfterOptional | (task: GanttTask) => stringActions-column insert button. Default: `` `Add task after ${task.name}` ``. |
deleteTaskOptional | (task: GanttTask) => stringActions-column delete button. Default: `` `Delete ${task.name}` ``. |
barOptional | (task: GanttTask, state: {
progress: number;
}) => stringThe single announcement for a timeline bar. The bar's inner subtree is `aria-hidden`, so this must carry everything the bar shows visually. Default: `"{name}, {type}, {start} to {end}, {progress}% complete"`. |
TypeScript declaration
/**
* Overrides for every accessible string the library emits. Pass any subset via
* `<Gantt labels={...} />`; omitted keys keep their English defaults (see
* `DEFAULT_LABELS` in `core/labels.ts`).
*
* NOTE: pass a referentially stable / memoized object — a fresh object each render
* invalidates the labels context and re-renders every row and bar.
*/
export declare interface GanttLabels {
/** Accessible name for the whole widget. Default: `"Gantt chart"`. */
gantt?: string;
/** Accessible name for the task-list treegrid. Default: `"Task list"`. */
taskList?: string;
/** Accessible name for the timeline grid. Default: `"Timeline"`. */
timeline?: string;
/** Expand toggle, collapsed state. Default: `"Expand"`. */
expand?: string;
/** Expand toggle, expanded state. Default: `"Collapse"`. */
collapse?: string;
/** The task-list / timeline splitter. Default: `"Resize task list"`. */
resizeTaskList?: string;
/** The dependency-link delete button. Default: `"Delete dependency"`. */
deleteDependency?: string;
/** Actions-column edit button. Default: `` `Edit ${task.name}` ``. */
editTask?: (task: GanttTask) => string;
/** Actions-column insert button. Default: `` `Add task after ${task.name}` ``. */
addTaskAfter?: (task: GanttTask) => string;
/** Actions-column delete button. Default: `` `Delete ${task.name}` ``. */
deleteTask?: (task: GanttTask) => string;
/**
* The single announcement for a timeline bar. The bar's inner subtree is
* `aria-hidden`, so this must carry everything the bar shows visually.
* Default: `"{name}, {type}, {start} to {end}, {progress}% complete"`.
*/
bar?: (task: GanttTask, state: {
progress: number;
}) => string;
}`GanttLabels` with every key filled in from the defaults.
/** `GanttLabels` with every key filled in from the defaults. */
export declare type ResolvedGanttLabels = Required<GanttLabels>;