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| Property | Type & description |
|---|---|
unitRequired | CalendarUnit |
stepRequired | number |
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;
};CalendarUnit
Typeexport declare type CalendarUnit = "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";ZoomLevel
TypeOne rung of the zoom ladder: the calendar `scales` to render and the pixel width of a single (finest-unit) column. Zooming steps between levels.
| Property | Type & description |
|---|---|
scalesRequired | Scale[] |
colWidthRequired | number |
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_LEVELS
ConstantDefault 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[];DEFAULT_ZOOM_INDEX
ConstantIndex 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;| Property | Type & description |
|---|---|
keyRequired | React.Key |
dateRequired | Date | "pointer"A fixed instant, or the date under the mouse while it is over the grid body. |
titleOptional | string |
overscanPxOptional | numberHorizontal 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;
}| Property | Type & description |
|---|---|
dateRequired | Date |
titleOptional | string |
xRequired | number |
bodyHeightRequired | number |
visibleTopRequired | number |
visibleHeightRequired | number |
TypeScript declaration
export declare interface TimelineElementRenderProps {
date: Date;
title?: string;
x: number;
bodyHeight: number;
visibleTop: number;
visibleHeight: number;
}Marker
ComponentA 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
Type| Property | Type & description |
|---|---|
dateRequired | Date |
visibleTopOptional | number |
xOptional | numberLayout values supplied by the timeline layer, consumed without forwarding to the DOM. |
bodyHeightOptional | number |
visibleHeightOptional | number |
titleOptional | string |
formatDateOptional | (date: Date) => string |
slotsOptional | MarkerSlots |
slotPropsOptional | MarkerSlotProps |
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;
}