Skip to content
GitHub
API reference

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

Component
export declare function Gantt(props: GanttProps): JSX.Element;

Props of the all-in-one `<Gantt>`: the engine plus layout and slots.

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

columnsOptionalColumnDef[]
defaultTaskListWidthOptionalnumber
hideTaskListOptionalboolean
taskListOptionalGanttTaskListSlots

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.

barsOptionalGanttBarsSlots

Slot overrides for the timeline bars and their handles.

dependencySlotsOptionalGanttDependenciesSlots

Slot overrides for dependency links (named `dependencySlots` to avoid colliding with the `dependencies` data prop above).

timelineOptionalGanttTimelineSlots

Slot 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;
}

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

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

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;
}

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.

GanttLabels documented properties
PropertyType & description
ganttOptionalstring

Accessible name for the whole widget. Default: `"Gantt chart"`.

taskListOptionalstring

Accessible name for the task-list treegrid. Default: `"Task list"`.

timelineOptionalstring

Accessible name for the timeline grid. Default: `"Timeline"`.

expandOptionalstring

Expand toggle, collapsed state. Default: `"Expand"`.

collapseOptionalstring

Expand toggle, expanded state. Default: `"Collapse"`.

resizeTaskListOptionalstring

The task-list / timeline splitter. Default: `"Resize task list"`.

deleteDependencyOptionalstring

The dependency-link delete button. Default: `"Delete dependency"`.

editTaskOptional(task: GanttTask) => string

Actions-column edit button. Default: `` `Edit ${task.name}` ``.

addTaskAfterOptional(task: GanttTask) => string

Actions-column insert button. Default: `` `Add task after ${task.name}` ``.

deleteTaskOptional(task: GanttTask) => string

Actions-column delete button. Default: `` `Delete ${task.name}` ``.

barOptional(task: GanttTask, state: { progress: number; }) => 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"`.

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>;

Related examples