Timeline
Chronological list of dated events. Each entry pairs a machine-readable <time> value with a title and optional description, rendered as an ordered list with a small indicator on a vertical spine. Items are passed as structured objects: { date, date_iso, title, content, state? }. Each entry's optional state (pending, current, or complete) drives the indicator styling - the current entry gets aria-current="date" and a highlighted dot, complete entries use the success color. The optional title_tag prop swaps each entry's title from <strong> to a real heading element (h2-h6) when the page hierarchy demands it. Use for case histories, project milestones, release timelines, and any narrative where the sequence and dates carry meaning.
Usage
When to use
- Project milestones, version histories, and release timelines
- Case histories or audit trails where the date of each step matters
- Editorial narratives that benefit from a vertical chronological rail
When not to use
- A flat list with no temporal sequence - use linklist or content
- Status of a single ongoing operation - use progress
- Numbered, ordered procedures without dates - use steps
Do
- Provide a machine-readable
date_isoalongside the human-friendlydatestring so assistive tech and indexing can parse it - Keep titles short and meaningful; reserve longer prose for the entry content
- Order entries chronologically (ascending or descending) and stay consistent across the page
Don't
- Don't use timeline for a two-entry list - the visual rail adds noise without value
- Don't put interactive form controls inside an entry - use a card grid instead
- Don't omit the date - the date column is the component's spine
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | array | - | Array of event objects. Each event has a human date, an ISO datetime, a title heading, an HTML content body, and an optional state field that controls indicator styling. |
title_tag | Enum: strong, h2, h3, h4, h5, h6 | h3 | Tag used for each entry title. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.horizontal | Orientation | - | Children flow along the horizontal axis. |
.vertical | Orientation | Yes | Children flow along the vertical axis. |
Examples
Default
Three entries, each carrying a date, a title and a paragraph of content.
Titles only
Five entries with the content slot empty, for a chronology that needs no elaboration per entry.
Long
Twelve entries, the length at which the connecting line and the date column have to hold over a full page.
Horizontal
The horizontal orientation, which lays the entries along a row and runs the connecting line across them.
States
All three progress words at once: two complete entries, the current one carrying aria-current="date", and one still pending.
Accessibility
- WCAG 2.2 AA
- Each entry uses a
<time datetime="...">element so assistive tech announces a parseable date - Entries are presented as a list so screen readers announce the count and current position
- An entry in the
currentstate carriesaria-current="date", the ARIA token for the current date of a collection.stepsenumerates steps rather than dates, so it marks its current itemaria-current="step" - The visual rail is decorative - the chronology is conveyed by the dates and order, not the line
- Reduced-motion users see no animation - timeline is a static layout