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.
GanttHandle
TypeImperative API exposed via `<Gantt apiRef={ref} />` for create/update/delete/undo/redo.
| Property | Type & 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) => voidBring 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 | () => voidStep the zoom ladder one level finer. No-op at the finest level. |
zoomOutRequired | () => voidStep the zoom ladder one level coarser. No-op at the coarsest level. |
setZoomRequired | (index: number) => voidJump 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;
}TaskPatch
TypePatch passed to the imperative `updateTask`; only the provided fields change.
| Property | Type & description |
|---|---|
nameOptional | string |
startDateOptional | Date |
endDateOptional | Date |
progressOptional | number |
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;
}RevealOptions
TypeWhich axes to reveal on. Defaults match the historical `scrollToTask(id)`.
| Property | Type & description |
|---|---|
verticalOptional | booleanReveal the task's row vertically, in whichever pane is mounted. Default `true`. |
horizontalOptional | booleanReveal 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;
}