Skip to content
GitHub
API reference

Columns

Define task-list cells and extend the built-in column catalogue.

Usage

import { DEFAULT_COLUMNS, type ColumnDef } from "@art-tools/react-gantt";

const columns: ColumnDef[] = [
  ...DEFAULT_COLUMNS,
  {
    key: "duration",
    header: "Duration",
    width: 100,
    render: (task, api) => api.format.duration(task),
  },
];
  • columns replaces the complete built-in set. Spread DEFAULT_COLUMNS to extend it, or READ_ONLY_COLUMNS to omit the actions column. Treat both exported arrays as immutable.
  • Set isTreeColumn on the column that should render hierarchy indentation and expand controls. width is measured in pixels.
  • render receives the task and ColumnApi. Use api.format.endDate and api.format.duration for values that respect exclusive end dates, the calendar, and durationUnit.
  • Custom editing controls must check api.readOnly. ColumnApi also exposes imperative methods, editTask, and resolved accessibility labels. render is a plain callback; put hooks in a child component.
ColumnDef documented properties
PropertyType & description
keyRequiredstring
headerRequiredstring
widthOptionalnumber
renderRequired(task: T, api: ColumnApi) => React.ReactNode
isTreeColumnOptionalboolean
TypeScript declaration
export declare interface ColumnDef<T extends GanttTask = GanttTask> {
    key: string;
    header: string;
    width?: number;
    render: (task: T, api: ColumnApi) => React.ReactNode;
    isTreeColumn?: boolean;
}

API passed as the 2nd arg to `ColumnDef.render`, for building actionable columns.

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

editTaskRequired(task: GanttTask) => void

Fires the consumer's `onTaskEdit` callback for this task.

readOnlyRequiredboolean

The chart's `readOnly` prop. The mutating members above still work (they are the imperative API — see ADR-021), so a column that renders edit/delete controls should check this and render nothing instead.

labelsRequiredResolvedGanttLabels

Resolved accessible strings, for labelling controls a column renders. `ColumnDef.render` is a plain function, not a component, so it can't call `useGanttLabels()` — this is its channel to the `labels` prop.

formatRequired{ /** The inclusive last-occupied day, or `undefined` for an instant. */ endDate: (task: GanttTask) => Date | undefined; /** Working time the task occupies, in the chart's `durationUnit`. */ duration: (task: GanttTask) => number; }

Display helpers that already know the chart's calendar and `durationUnit` — the same channel as `labels`, for the same reason. Stored dates are exclusive instants, which read wrong in a column: a task running Monday to Friday stores Saturday. Use these to show a user-facing end date or duration rather than formatting `task.endDate` directly.

TypeScript declaration
/** API passed as the 2nd arg to `ColumnDef.render`, for building actionable columns. */
export declare interface ColumnApi extends GanttHandle {
    /** Fires the consumer's `onTaskEdit` callback for this task. */
    editTask: (task: GanttTask) => void;
    /**
     * The chart's `readOnly` prop. The mutating members above still work (they are
     * the imperative API — see ADR-021), so a column that renders edit/delete
     * controls should check this and render nothing instead.
     */
    readOnly: boolean;
    /** Resolved accessible strings, for labelling controls a column renders.
     *  `ColumnDef.render` is a plain function, not a component, so it can't call
     *  `useGanttLabels()` — this is its channel to the `labels` prop. */
    labels: ResolvedGanttLabels;
    /**
     * Display helpers that already know the chart's calendar and `durationUnit` —
     * the same channel as `labels`, for the same reason.
     *
     * Stored dates are exclusive instants, which read wrong in a column: a task
     * running Monday to Friday stores Saturday. Use these to show a user-facing
     * end date or duration rather than formatting `task.endDate` directly.
     */
    format: {
        /** The inclusive last-occupied day, or `undefined` for an instant. */
        endDate: (task: GanttTask) => Date | undefined;
        /** Working time the task occupies, in the chart's `durationUnit`. */
        duration: (task: GanttTask) => number;
    };
}

The columns `<Gantt>` renders when no `columns` prop is given. Treat as immutable — it is module state shared by every chart on the page.

/**
 * The columns `<Gantt>` renders when no `columns` prop is given.
 *
 * Treat as immutable — it is module state shared by every chart on the page.
 */
export declare const DEFAULT_COLUMNS: ColumnDef[];

DEFAULT_COLUMNS without the actions column — the `readOnly` default.

/** {@link DEFAULT_COLUMNS} without the actions column — the `readOnly` default. */
export declare const READ_ONLY_COLUMNS: ColumnDef[];

Key of the built-in edit/add/delete column, dropped when `readOnly` is set. Exported so a consumer can extend the built-in set rather than replace it: `[...DEFAULT_COLUMNS.filter((c) => c.key !== ACTION_COLUMN_KEY), myColumn]`.

/**
 * Key of the built-in edit/add/delete column, dropped when `readOnly` is set.
 *
 * Exported so a consumer can extend the built-in set rather than replace it:
 * `[...DEFAULT_COLUMNS.filter((c) => c.key !== ACTION_COLUMN_KEY), myColumn]`.
 */
export declare const ACTION_COLUMN_KEY = "__action";

Related examples