Skip to content
GitHub
API reference

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

Component

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.

/**
 * 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.

GanttProviderProps documented properties
PropertyType & description
tasksRequiredGanttTask[]
rowHeightOptionalnumber

Live-bar area height in px. Defaults to 36; baseline lanes add to it.

timelineElementsOptionalreadonly 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.

colWidthOptionalnumber
heightOptionalnumber

Total component height in px. When set, rows scroll vertically within it (calendar/header stay pinned); omit to grow with content.

scalesOptionalScale[]
padDaysOptionalnumber
zoomLevelsOptionalZoomLevel[]

Custom zoom ladder (coarse → fine). Defaults to the built-in ladder; when omitted, `scales`/`colWidth` seed the default rung.

defaultZoomIndexOptionalnumber

Starting rung of the zoom ladder (default: the month/day level).

onZoomChangeOptional(state: { index: number; count: number; }) => void

Fired when the zoom level changes (and once on mount).

zoomWheelOptionalboolean

Enable Ctrl/Cmd + mouse-wheel zoom over the grid (anchors on the cursor).

zoomKeyboardOptionalboolean

Enable +/- keyboard zoom when the grid is focused.

onTaskClickOptional(task: GanttTask) => void
dependenciesOptionalTaskDependency[]
onDependencyCreateOptional(dep: TaskDependency) => void
onDependencyDeleteOptional(dep: TaskDependency) => void
onTaskCreateOptional(task: GanttTask, afterId?: Id | null) => void
onTaskDeleteOptional(id: Id) => void
onTaskEditOptional(task: GanttTask) => void

Fired when a column's edit action is invoked (e.g. the actions-column pencil button).

onTasksChangeOptional(tasks: GanttTask[]) => void

Fired with the resolved task list whenever it changes (after create/delete/edit/undo/redo).

calendarOptionalGanttCalendar

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.

snapToWorkingOptionalboolean

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.

durationUnitOptionalDurationUnit

How an input `duration` is interpreted and displayed. Defaults to `"day"`.

readOnlyOptionalboolean

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`.

criticalPathOptionalboolean

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).

showBaselinesOptionalboolean

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).

apiRefOptionalReact.Ref<GanttHandle>

Receives the imperative API: `apiRef.current.createTask(...)`, `.undo()`, etc.

labelsOptionalGanttLabels

Overrides for the library's accessible strings (screen-reader names). Pass a referentially stable object — see `GanttLabels`.

childrenRequiredReact.ReactNode
TypeScript declaration
/** Props of the composable `<GanttProvider>`: the engine plus its subtree. */
export declare interface GanttProviderProps extends GanttEngineProps {
    children: React.ReactNode;
}

GanttGrid

Component
export 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

Component
export 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

Component
export declare function Calendar(props: CalendarProps): JSX.Element;
CalendarProps documented properties
PropertyType & description
colWidthRequirednumber
rowHeightRequirednumber
scalesOptionalScale[]
datesRequiredDate[]
colRangeRequiredIndexRange

Half-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 documented properties
PropertyType & description
startRequirednumber

First visible item index (inclusive).

endRequirednumber

One 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

Component
export 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

Component
export 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

Component
export 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;
}
export declare function useGanttReadOnly(): boolean;

Related examples