Skip to content
GitHub
API reference

Timeline & zoom

Scales, zoom levels, date-anchored overlays, and the Marker component.

Usage

import { Marker, type GanttTimelineElement } from "@art-tools/react-gantt";

const timelineElements: GanttTimelineElement[] = [
  {
    key: "deadline",
    date: new Date(2026, 0, 16),
    title: "Deadline",
    render: (props) => <Marker {...props} />,
  },
];

// <Gantt tasks={tasks} timelineElements={timelineElements} zoomWheel />
  • A scale specifies unit, step, and a date formatter; ariaFormat optionally supplies an accessible label. The finest scale determines the column unit. padDays defaults to 1 and is measured in stepped column units, so at hour zoom it pads hours.
  • zoomLevels is ordered coarse to fine. The default ladder has five levels, with month/day at index 3. scales and colWidth customize that default rung when a custom ladder is not supplied.
  • zoomWheel and zoomKeyboard both default to false. Enable them for Ctrl/Cmd + wheel and focused-grid +/- shortcuts. onZoomChange reports index and count on mount and after changes.
  • timelineElements requires a unique key, a Date or pointer date, and a render callback. Overlays do not expand the timeline and are horizontally virtualized with 256px overscan by default.
  • A pointer element follows the mouse over the grid body and is noninteractive. Render props resolve its date to a Date. Marker is an explicit opt-in renderer; customize it directly inside render or through timeline.marker slots.

Scale

Type
Scale documented properties
PropertyType & description
unitRequiredCalendarUnit
stepRequirednumber
formatRequired(date: Date) => string
ariaFormatOptional(date: Date) => string
TypeScript declaration
export declare type Scale = {
    unit: CalendarUnit;
    step: number;
    format: (date: Date) => string;
    ariaFormat?: (date: Date) => string;
};
export declare type CalendarUnit = "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";

One rung of the zoom ladder: the calendar `scales` to render and the pixel width of a single (finest-unit) column. Zooming steps between levels.

ZoomLevel documented properties
PropertyType & description
scalesRequiredScale[]
colWidthRequirednumber
TypeScript declaration
/**
 * One rung of the zoom ladder: the calendar `scales` to render and the pixel
 * width of a single (finest-unit) column. Zooming steps between levels.
 */
export declare interface ZoomLevel {
    scales: Scale[];
    colWidth: number;
}

Default zoom ladder, ordered coarse → fine. Zooming in moves toward finer (higher-index) levels; each rung pairs a coarse header row with a finer bottom row whose unit is the column unit.

/**
 * Default zoom ladder, ordered coarse → fine. Zooming in moves toward finer
 * (higher-index) levels; each rung pairs a coarse header row with a finer
 * bottom row whose unit is the column unit.
 */
export declare const DEFAULT_ZOOM_LEVELS: ZoomLevel[];

Index of the default (month / day) rung in DEFAULT_ZOOM_LEVELS.

/** Index of the default (month / day) rung in {@link DEFAULT_ZOOM_LEVELS}. */
export declare const DEFAULT_ZOOM_INDEX = 3;
GanttTimelineElement documented properties
PropertyType & description
keyRequiredReact.Key
dateRequiredDate | "pointer"

A fixed instant, or the date under the mouse while it is over the grid body.

titleOptionalstring
overscanPxOptionalnumber

Horizontal mounting allowance in px on either side of the viewport. Default: 256.

renderRequired(props: TimelineElementRenderProps) => React.ReactNode
TypeScript declaration
export declare interface GanttTimelineElement {
    key: React.Key;
    /** A fixed instant, or the date under the mouse while it is over the grid body. */
    date: Date | "pointer";
    title?: string;
    /** Horizontal mounting allowance in px on either side of the viewport. Default: 256. */
    overscanPx?: number;
    render: (props: TimelineElementRenderProps) => React.ReactNode;
}
TimelineElementRenderProps documented properties
PropertyType & description
dateRequiredDate
titleOptionalstring
xRequirednumber
bodyHeightRequirednumber
visibleTopRequirednumber
visibleHeightRequirednumber
TypeScript declaration
export declare interface TimelineElementRenderProps {
    date: Date;
    title?: string;
    x: number;
    bodyHeight: number;
    visibleTop: number;
    visibleHeight: number;
}

Marker

Component

A display-only date line; only its label participates in pointer hit testing.

/** A display-only date line; only its label participates in pointer hit testing. */
export declare function Marker(props: MarkerProps): JSX.Element;
MarkerProps documented properties
PropertyType & description
dateRequiredDate
visibleTopOptionalnumber
xOptionalnumber

Layout values supplied by the timeline layer, consumed without forwarding to the DOM.

bodyHeightOptionalnumber
visibleHeightOptionalnumber
titleOptionalstring
formatDateOptional(date: Date) => string
slotsOptionalMarkerSlots
slotPropsOptionalMarkerSlotProps
TypeScript declaration
export declare interface MarkerProps extends Omit<ComponentProps<"div">, "title" | "children"> {
    date: Date;
    visibleTop?: number;
    /** Layout values supplied by the timeline layer, consumed without forwarding to the DOM. */
    x?: number;
    bodyHeight?: number;
    visibleHeight?: number;
    title?: string;
    formatDate?: (date: Date) => string;
    slots?: MarkerSlots;
    slotProps?: MarkerSlotProps;
}

Related examples