Skip to content
GitHub
API reference

Imperative API

Create, update, delete, undo, reveal tasks, and control zoom through a ref.

Usage

"use client";

import { useRef } from "react";
import { Gantt, type GanttHandle, type GanttTask } from "@art-tools/react-gantt";

export function Chart({ tasks }: { tasks: GanttTask[] }) {
  const apiRef = useRef<GanttHandle>(null);
  return (
    <>
      <button onClick={() => apiRef.current?.undo()}>Undo</button>
      <Gantt tasks={tasks} apiRef={apiRef} height={420} />
    </>
  );
}
  • Pass a React ref through apiRef on Gantt or GanttProvider. The handle becomes available after the chart mounts, so use optional chaining in event handlers.
  • updateTask changes only supplied fields: name, startDate, endDate, and progress. createTask appends when afterId is omitted or null. Each user action and its cascading reschedules form one undo transaction.
  • revealTask expands collapsed ancestors. It reveals vertically by default; pass horizontal: true to reveal the bar as well. Unknown IDs are ignored.
  • zoomIn moves one level finer, zoomOut one level coarser, and setZoom clamps the requested index to the available ladder. Imperative mutations remain available when readOnly is true.

Imperative API exposed via `<Gantt apiRef={ref} />` for create/update/delete/undo/redo.

GanttHandle documented properties
PropertyType & description
createTaskRequired(task: GanttTask, afterId?: Id | null) => void
updateTaskRequired(id: Id, patch: TaskPatch) => void
deleteTaskRequired(id: Id) => void
undoRequired() => void
redoRequired() => void
revealTaskRequired(id: Id, options?: RevealOptions) => void

Bring a task into view. Vertical by default; pass `{ horizontal: true }` to also scroll the grid to the task's bar. Expands any collapsed ancestors first, so a task nested under a collapsed parent is revealed rather than silently ignored. Still a no-op for an id that is not in the chart at all.

zoomInRequired() => void

Step the zoom ladder one level finer. No-op at the finest level.

zoomOutRequired() => void

Step the zoom ladder one level coarser. No-op at the coarsest level.

setZoomRequired(index: number) => void

Jump to a zoom-ladder index (clamped to the ladder bounds).

TypeScript declaration
/** Imperative API exposed via `<Gantt apiRef={ref} />` for create/update/delete/undo/redo. */
export declare interface GanttHandle {
    createTask: (task: GanttTask, afterId?: Id | null) => void;
    updateTask: (id: Id, patch: TaskPatch) => void;
    deleteTask: (id: Id) => void;
    undo: () => void;
    redo: () => void;
    /**
     * Bring a task into view. Vertical by default; pass `{ horizontal: true }` to
     * also scroll the grid to the task's bar.
     *
     * Expands any collapsed ancestors first, so a task nested under a collapsed
     * parent is revealed rather than silently ignored. Still a no-op for an id that
     * is not in the chart at all.
     */
    revealTask: (id: Id, options?: RevealOptions) => void;
    /** Step the zoom ladder one level finer. No-op at the finest level. */
    zoomIn: () => void;
    /** Step the zoom ladder one level coarser. No-op at the coarsest level. */
    zoomOut: () => void;
    /** Jump to a zoom-ladder index (clamped to the ladder bounds). */
    setZoom: (index: number) => void;
}

Patch passed to the imperative `updateTask`; only the provided fields change.

TaskPatch documented properties
PropertyType & description
nameOptionalstring
startDateOptionalDate
endDateOptionalDate
progressOptionalnumber
TypeScript declaration
/** Patch passed to the imperative `updateTask`; only the provided fields change. */
export declare interface TaskPatch {
    name?: string;
    startDate?: Date;
    endDate?: Date;
    progress?: number;
}

Which axes to reveal on. Defaults match the historical `scrollToTask(id)`.

RevealOptions documented properties
PropertyType & description
verticalOptionalboolean

Reveal the task's row vertically, in whichever pane is mounted. Default `true`.

horizontalOptionalboolean

Reveal the task's bar horizontally in the grid. Default `false`.

TypeScript declaration
/** Which axes to reveal on. Defaults match the historical `scrollToTask(id)`. */
export declare interface RevealOptions {
    /** Reveal the task's row vertically, in whichever pane is mounted. Default `true`. */
    vertical?: boolean;
    /** Reveal the task's bar horizontally in the grid. Default `false`. */
    horizontal?: boolean;
}

Related examples