---
id: "packages/active-charts/all-exports/timeline-chart"
title: "TimelineChart"
description: "TimelineChart, TimelineChartProps, TimelineEvent, TimelineTimeAxis and 1 more: generated from the source of active-charts."
url: "/packages/active-charts/all-exports/timeline-chart"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:timeline-chart"
---

# TimelineChart

Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports).

## `TimelineChart`

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `TimelineEvent[] \| (TimelineEvent & { time: TimelineTime; })[]` | yes | Array of events to display on the timeline. The events, each with its machine `time`. |
| `height` | `number` | yes | Container height in pixels. Width is always responsive. |
| `accessibility` | `StandaloneAccessibilityOptions` | no | Accessible name, description, data table and keyboard navigation. No `announcements`: it switches `<Chart>`'s interaction announcements, which this family does not make. |
| `alternateLabels` | `boolean` | no | Alternate labels above/below the axis. Default: true. |
| `animation` | `StandaloneAnimationOption<"type">` | no | The entrance: on, off, `duration`, `easing` and the entrance `type` (ADR-082, LAB-AT17). |
| `className` | `string` | no | Optional className applied to the outer container. |
| `colors` | `string[]` | no | Categorical palette for this chart only: replaces the host palette (`--chart-1` … `--chart-10`) in the chart's colour assignment, and nothing else. It is a data encoding, not a theme: surfaces, text, grid and semantic roles keep coming from the CSS token contract, and a series, datum or annotation that sets its own colour keeps it. Any CSS colour string (a public token reference such as `var(--chart-3)`, hex, oklch). |
| `contextMenu` | `FeatureOption<ChartContextMenuOptions<TimelineElement<TimelineEvent>, "copy" \| "export">>` | no | The context menu. Opened on an event, the host's builder receives a typed {@link TimelineElement} (the event and its index) as `context.target.element`. |
| `dir` | `"ltr" \| "rtl"` | no | The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under `<body>`.  Left out, the chart inherits the direction of the page around it (the nearest `dir` attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from `locale`, and it never reverses an axis or reorders data: `reversed` stays an explicit axis choice. Under `rtl` the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction. |
| `events` | `Omit<ChartEvents, "onLegendChange" \| "onZoomChange">` | no |  |
| `locale` | `ValuePresentation` | no | Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object (`{languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}`) carrying language and notation independently. `dateShape` is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central `@workspace/active-format`; the package never resolves tenant or application settings itself. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no `'en'` fallback, active-format D14). Object inputs must be referentially stable across renders. |
| `marker` | `MarkerShape` | no | The event markers' shape, from the one marker vocabulary of the package. Default: `'circle'`. Every shape has the area of the circle of `markerSize`. |
| `markerSize` | `number` | no | Marker radius in pixels. Default: 6. |
| `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished.  Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. |
| `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. |
| `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). |
| `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests.  Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness.  A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance).  **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. |
| `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). |
| `timeAxis` | `TimelineTimeAxis` | no | Without a time axis the events are placed in order, evenly. Place the events by time (T9): an event's x is its `time` on the events' extent, so a long gap is a long distance and equal times share one x; labels move to avoid each other, markers never. The keyboard, the data table and the announcement then read ascending time (equal times in the host's order); the CSV keeps the host's row order and adds the `time` column. An event without a readable `time` (an untyped call) puts the whole chart back on ordinal placement, with a development diagnostic. |
| `tooltip` | `StandaloneTooltipOption<"valueFormatter">` | no | Tooltip of the event under the pointer: `enabled`, `renderer` and `style`. The card shows text rows without a value, so no `valueFormatter` (ADR-082, LAB-AT17). |
| `width` | `number` | no | Optional fixed width in pixels. Default: fill container. |

## Types

**TimelineChartProps**

```ts
type TimelineChartProps = TimelineChartBaseProps &
  (
    | {
        timeAxis?: undefined;
        data: TimelineEvent[];
      }
    | {
        timeAxis: TimelineTimeAxis;
        data: (TimelineEvent & {time: TimelineTime})[];
      }
  );
```

Props for {@link TimelineChart}: ordinal placement (the default: events
evenly spaced in the host's order), or, with `timeAxis`, placement by each
event's `time` (T9), which every event then carries.

**TimelineEvent**

```ts
interface TimelineEvent {
  date: string;
  label: string;
  description?: string;
  category?: string;
  color?: string;
  time?: TimelineTime;
}
```

**TimelineTimeAxis**

```ts
interface TimelineTimeAxis {
  temporalSemantic: TemporalSemantic;
}
```

The time axis of a timeline (T9): with it, distance on the timeline is
elapsed time. It declares what the event times ARE: calendar
days or instants; the CSV writes `time` in that machine form.

**TimelineTime**

```ts
type TimelineTime = Date | number | IsoDateString;
```

A machine time, read as every temporal axis reads one.