Skip to main content

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_iso alongside the human-friendly date string 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​

PropTypeDefaultDescription
itemsarray-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_tagEnum: strong, h2, h3, h4, h5, h6h3Tag used for each entry title.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.horizontalOrientation-Children flow along the horizontal axis.
.verticalOrientationYesChildren 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 current state carries aria-current="date", the ARIA token for the current date of a collection. steps enumerates steps rather than dates, so it marks its current item aria-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
  • steps - ordered procedures without dates
  • card - richer block presentation when dates are not the spine
  • progress - in-progress measurement of a single operation