Overview
Reference usage
Timestamp-first event rail for workflow events, audit logs, run histories, and grouped temporal sequences. Timeline is not a live region; use Feed for streaming activity that should be announced to assistive technology.
See the chronological display boundary decision for the distinction between Timeline, RunStepTimeline, and Feed.
Usage
Upcoming and past runs, around Now
variant="list" draws the same entries as compact rows: no connector, a hairline between rows, the time first. variant="rows" keeps the rail's marker column and connector but draws nothing else of an entry: no timestamp, no title and no body wrapper, only the marker and whatever the children snippet draws, for a sequence with nothing to date (the tool calls of one chat turn, which ToolCallRail draws this way). Its datetime and timestamp are not read and may be empty. A row is about 1.625rem tall; taller rows move the marker with --cinder-timeline-row-marker-offset and the entries with --cinder-timeline-row-gap, and the connector follows both. The pending tone is a hollow neutral ring for something that has not happened yet. kind: 'now' is the marker for the current moment (an accent pill from title, a rule, and timestamp at the right), and kind: 'separator' is a quiet labelled rule, such as the day daylight saving time ended. Neither draws a marker, a connector, a body or actions. kind: 'band' is one collapsed group row (the stacked-list-item band: a status dot, a chevron, title, muted detail and a toggle labelled expandLabel, "Show each" for the missed runs); tone: 'warning' makes it amber, and the entry's children are the details it opens; expanded starts it open and the timeline's onExpandedChange hears each change. kind: 'run' is a past run as Cinder's status-first row: the status word and its dot lead, timestamp is the bold time, detail is the muted second line ("Failed at step 2 · GitHub didn't answer"), duration sits at the right before a chevron, and href makes the whole row the link. struck crosses an event's timestamp out, for an occurrence that will not start. The actions snippet draws controls at the end of an event's row; unlike marker, they are interactive.
Marker snippets are decorative. Do not place focusable or interactive content inside marker; the marker wrapper is hidden from assistive technology and marked inert.
-
Health check passed All probes returned healthy responses across the deployment target. -
Capacity warning Projected load crossed the warning threshold for the current pool. -
Rollback triggered Rollback automation started after error rates continued climbing.
When to use
- Showing dated workflow, audit, or run-history events on a temporal rail.
- Listing upcoming and past runs as compact rows split by a Now marker, with a labelled break where the clock changed.
- Surfacing a real-time social or activity stream — feed is the higher-affordance composition.
- Guiding users through a numbered procedural flow. Use Steps instead
- Showing async execution state with retries, branches, or progress. Use Run Step Timeline instead
- Showing a live activity or dense operational stream — use feed (its log arm covers operational streams).
Examples
Custom dot styles
A timeline with decorative marker snippets for each tone.
Gap threshold
With `gapThresholdMinutes`, the connector after an entry is hidden when the next entry is more than that many minutes away — visually breaking the line across large time gaps.
Grouped by day
A timeline grouped by UTC day while preserving source order.
Horizontal timeline
A compact horizontal timeline for phase comparisons.
Upcoming and past runs
The list variant with hollow pending rings, a Skip action on each upcoming run, the Now marker, the missed runs once as a collapsed amber band below it, and a separator where daylight saving time ended.
Vertical timeline
A timestamp-first event rail for workflow and audit history.
Props
Name | Type | Default | Description |
|---|---|---|---|
entries required | TimelineEntry[] | Timeline entries rendered in source order. | |
orientation | 'vertical' | 'horizontal' | 'vertical' | Layout orientation. |
variant | 'rail' | 'list' | 'rows' | 'rail' | Rail with connectors, compact rows with none, or a rail whose rows children draws whole. |
groupBy | 'none' | 'day' | 'week' | 'none' | Optional adjacent UTC day/week grouping mode. |
weekStartsOn | 'sunday' | 'monday' | 'monday' | Week start used for UTC week grouping. |
groupHeaderLevel | TimelineHeadingLevel | undefined | 3 | Heading level applied to rendered group headers. |
gapThresholdMinutes | number | Hide the following connector when adjacent valid timestamps exceed this gap (in minutes). | |
label | text | Fallback accessible label used only when aria-label and aria-labelledby are absent. | |
children | Snippet<[TimelineEntry]>undefined | Optional per-entry body content. | |
marker | Snippet<[TimelineEntry]>undefined | Decorative per-entry marker content. Must not contain interactive descendants. | |
actions | Snippet<[TimelineEntry]>undefined | Optional per-entry controls, drawn at the inline end of the entry's row (a "Skip" button on an
upcoming run). Unlike marker, they are interactive and in the tab order. Not drawn for a
now or separator entry. | |
onExpandedChange | ((entry: TimelineEntry, expanded: boolean) => void)undefined | Called when a band entry is opened or closed, with the entry and whether it is now open. |