Composition
Assemble the provider, task list, grid, and lower-level display components.
Usage
"use client";
import {
GanttProvider,
GanttGrid,
TaskList,
DEFAULT_COLUMNS,
type GanttTask,
} from "@art-tools/react-gantt";
export function Chart({ tasks }: { tasks: GanttTask[] }) {
return (
<GanttProvider tasks={tasks} height={420}>
<div style={{ display: "flex" }}>
<div style={{ width: 280, flexShrink: 0 }}>
<TaskList columns={DEFAULT_COLUMNS} />
</div>
<div style={{ minWidth: 0, flex: 1 }}><GanttGrid /></div>
</div>
</GanttProvider>
);
}- GanttProvider owns chart state and accepts the shared GanttEngineProps plus children. Gantt adds the standard two-pane layout and slot configuration on top of that engine.
- Mount TaskList and GanttGrid inside the same provider to share selection, scrolling, and edits. Supply columns explicitly to TaskList. GanttGrid includes its calendar and virtualized bars.
- Calendar and the individual bar components are lower-level building blocks. Their declarations include layout and interaction inputs normally supplied by the grid; use GanttGrid for the complete timeline.
- Use GanttSlotsProvider for grid-side customization on the composable path. Its value uses dependencies, whereas the all-in-one Gantt prop is named dependencySlots. Task-list slots are passed directly to TaskList.
GanttProvider
ComponentThe composition root: owns every piece of chart state and publishes it through the fourteen contexts defined in `contexts.ts`. The provider nesting at the bottom is ordered stable-outermost, hottest-inside, mirroring the cadence table in `contexts.ts`. That order is not load-bearing today — no layer derives its value from another, and React resolves `useContext` to the nearest provider at any depth — but it documents the architecture, and it *becomes* load-bearing the moment a layer starts reading another context. Keep it.
/**
* The composition root: owns every piece of chart state and publishes it through
* the fourteen contexts defined in `contexts.ts`.
*
* The provider nesting at the bottom is ordered stable-outermost, hottest-inside,
* mirroring the cadence table in `contexts.ts`. That order is not load-bearing
* today — no layer derives its value from another, and React resolves `useContext`
* to the nearest provider at any depth — but it documents the architecture, and it
* *becomes* load-bearing the moment a layer starts reading another context. Keep
* it.
*/
export declare function GanttProvider(props: GanttProviderProps): JSX.Element;Props of the composable `<GanttProvider>`: the engine plus its subtree.
| 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`. |
childrenRequired | React.ReactNode |
TypeScript declaration
/** Props of the composable `<GanttProvider>`: the engine plus its subtree. */
export declare interface GanttProviderProps extends GanttEngineProps {
children: React.ReactNode;
}GanttGrid
Componentexport declare function GanttGrid(props?: GanttGridProps): JSX.Element | null;Supporting types
These types appear in this signature but are not separate package exports.
declare interface GanttGridProps {
slots?: GridSlots;
slotProps?: GridSlotProps;
}TaskList
Componentexport declare function TaskList(props: TaskListProps): JSX.Element;Supporting types
These types appear in this signature but are not separate package exports.
declare interface TaskListProps {
columns?: ColumnDef[];
/** Slot overrides for the task-list pane (`treeCell`, `header`). Pass a stable object. */
taskList?: GanttTaskListSlots;
}Calendar
Componentexport declare function Calendar(props: CalendarProps): JSX.Element;CalendarProps
Type| Property | Type & description |
|---|---|
colWidthRequired | number |
rowHeightRequired | number |
scalesOptional | Scale[] |
datesRequired | Date[] |
colRangeRequired | IndexRangeHalf-open range of date indices in view (virtualization window). |
TypeScript declaration
export declare type CalendarProps = {
colWidth: number;
rowHeight: number;
scales?: Scale[];
dates: Date[];
/** Half-open range of date indices in view (virtualization window). */
colRange: IndexRange;
};IndexRange
Type| Property | Type & description |
|---|---|
startRequired | numberFirst visible item index (inclusive). |
endRequired | numberOne past the last visible item index (exclusive). |
TypeScript declaration
export declare interface IndexRange {
/** First visible item index (inclusive). */
start: number;
/** One past the last visible item index (exclusive). */
end: number;
}TaskBar
Componentexport declare function TaskBar(props: TaskBarProps): JSX.Element;Supporting types
These types appear in this signature but are not separate package exports.
declare interface TaskBarProps {
width: number;
height: number;
left: number;
top: number;
colWidth: number;
title: string;
a11y?: BarA11yProps;
progress: number;
/**
* Editing handlers. All optional: a read-only chart omits them, and each
* affordance is only rendered/wired when its handlers are present.
*/
onProgressChange?: (newProgress: number) => void;
onProgressEnd?: (newProgress: number) => void;
onResize?: (newWidth: number, newLeft: number) => void;
onResizeEnd?: (edge: "start" | "end", edgePx: number) => void;
onMove?: (newLeft: number) => void;
onMoveEnd?: (newLeft: number) => void;
/**
* Task data handed to the root so it can render the tooltip slot. Forwarded
* verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
*/
tooltip?: BarTooltipOwnerState;
/** Whether this bar is on the critical path (ADR-023). Defaults to `false`. */
isCritical?: boolean;
slots?: TaskBarSlots;
slotProps?: TaskBarSlotProps;
}
declare interface BarA11yProps {
role: string;
"aria-colindex": number;
"aria-colspan": number;
"aria-label": string;
"aria-description"?: string;
"aria-selected": boolean | undefined;
/**
* The native browser tooltip. Optional because a chart with a tooltip slot
* suppresses it — two tooltips would stack. `aria-label` is unaffected, so
* the accessible name survives either way.
*/
title?: string;
}ProjectBar
Componentexport declare function ProjectBar(props: ProjectBarProps): JSX.Element;Supporting types
These types appear in this signature but are not separate package exports.
declare interface ProjectBarProps {
width: number;
height: number;
left: number;
top: number;
colWidth: number;
title: string;
a11y?: BarA11yProps;
progress: number;
/** Editing handlers; omitted on a read-only chart (see `TaskBar`). */
onProgressChange?: (newProgress: number) => void;
onProgressEnd?: (newProgress: number) => void;
onMove?: (newLeft: number) => void;
onMoveEnd?: (newLeft: number) => void;
/**
* Task data handed to the root so it can render the tooltip slot. Forwarded
* verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
*/
tooltip?: BarTooltipOwnerState;
/** Whether this bar is on the critical path (ADR-023). Defaults to `false`. */
isCritical?: boolean;
slots?: ProjectBarSlots;
slotProps?: ProjectBarSlotProps;
}
declare interface BarA11yProps {
role: string;
"aria-colindex": number;
"aria-colspan": number;
"aria-label": string;
"aria-description"?: string;
"aria-selected": boolean | undefined;
/**
* The native browser tooltip. Optional because a chart with a tooltip slot
* suppresses it — two tooltips would stack. `aria-label` is unaffected, so
* the accessible name survives either way.
*/
title?: string;
}MilestoneBar
Componentexport declare function MilestoneBar(props: MilestoneBarProps): JSX.Element;Supporting types
These types appear in this signature but are not separate package exports.
declare interface MilestoneBarProps {
size: number;
centerLeft: number;
top: number;
colWidth: number;
title: string;
a11y?: BarA11yProps;
/** Editing handlers; omitted on a read-only chart (see `TaskBar`). */
onMove?: (newCenterLeft: number) => void;
onMoveEnd?: (newCenterLeft: number) => void;
/**
* Task data handed to the root so it can render the tooltip slot. Forwarded
* verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
*/
tooltip?: BarTooltipOwnerState;
/** Whether this bar is on the critical path (ADR-023). Defaults to `false`. */
isCritical?: boolean;
slots?: MilestoneBarSlots;
slotProps?: MilestoneBarSlotProps;
}
declare interface BarA11yProps {
role: string;
"aria-colindex": number;
"aria-colspan": number;
"aria-label": string;
"aria-description"?: string;
"aria-selected": boolean | undefined;
/**
* The native browser tooltip. Optional because a chart with a tooltip slot
* suppresses it — two tooltips would stack. `aria-label` is unaffected, so
* the accessible name survives either way.
*/
title?: string;
}useGanttReadOnly
Functionexport declare function useGanttReadOnly(): boolean;