Presents ordered events, milestones, or state transitions with a connected vertical rail.
Anatomy
A timeline has a vertical rail, event markers, primary event titles, optional supporting descriptions, optional meta (such as a timestamp), and optional marker-less rows (such as a Banner) for explanatory context.
Guidelines
Use Timeline when the order of events changes how someone understands the state of an object. It is especially useful for delivery events, journey activity, status history, audits, and other records where a plain list hides cause, sequence, or attribution.
Do not use Timeline for unrelated facts, navigation, menus, or lists where sequence is incidental.
Best Practices
Write event titles as past-tense outcomes, such as Sent email, Machine opened, or Human clicked.
Use descriptions to explain why an event matters, not to repeat the title.
Use marker-less rows sparingly to explain a rule, transition, or attribution change that affects nearby events.
Use isCurrent once per timeline when one event is the current status. Leave color unset (it defaults to grey) for expected or unavailable events to de-emphasize them.
The marker is a Coin. Use color to convey event meaning and shape (circle or rounded-square) to distinguish marker categories when color alone is not enough. Use isCurrent to ring the marker for the current or most important event.
Markers align to the first line of each row's content, so the title, icon, and timestamp scan together — the same whether or not a row has a title. The connecting line runs from each marker straight to the next, so the rail stays continuous regardless of row height.
Use lineVariant sparingly. Prefer solid for the normal sequence, dashed for expected or provisional continuity, and dotted for related or provisional notes.
Meta sits in a leading column before the marker by default, suited to activity logs with a persistent date or timestamp column. Use metaPosition="trailing" when the timestamp is secondary to the event content.
Types
TimelineItem is the default row for an event. Give it a markerIcon, markerIconSrc, or markerContent (text such as a step number, or any node) to render a marker coin.
A TimelineItem with no markerContent, markerIcon, or markerIconSrc is a marker-less row that hosts explanatory context — typically a Banner — inside the sequence. It renders no coin, runs full width, and the rail passes straight through it.
Appearance
Use semantic colors consistently: blue for informational delivery steps, green for successful human or completed steps, yellow for caution or machine-attributed states, red for failed or critical states, purple for feature-specific states, and grey for neutral states.
Do not invent new marker sizes, line widths, or text styles. Use the provided markerSize, shape, lineVariant, metaPosition, and row state props before adding custom styles.
Use markerSize="lg" sparingly for larger activity rows, especially when custom row content is framed or needs more scan weight. Use markerSize="sm" for dense timelines with short titles.
Behaviors
Timeline renders as an ordered list by default. Items render as list items by default, including marker-less rows.
Markers are decorative unless markerLabel is provided. Add markerLabel only when the marker communicates information not already present in visible text.
Content
Keep titles short enough to scan. Put timestamps, dates, counts, or short statuses in meta. Put longer explanation in description or a Banner inside a marker-less TimelineItem.