Timeline

Usage

Timeline is for read-only chronology: activity feeds, audit trails, incident history, release logs, roadmaps. Anything where the order is the meaning and the reader is looking back at what happened.

It deliberately has no notion of a current step you can advance, no completion state, and nothing to click. Events are content, not controls. If the user needs to move through a known sequence — a checkout, an onboarding flow, a multi-step form — a timeline is the wrong shape; that job wants a stepper, which this library does not yet ship.

The API is composable rather than a single component with props, which is the same exception the Legend takes. An event carries a card, a chip, an avatar or prose, and props cannot express that. Children can.

Anatomy

Import the Timeline component and access all parts using dot notation.

import {Timeline} from "@blakeui/pro-react";

<Timeline>
  <Timeline.Item>
    <Timeline.Rail>
      <Timeline.Marker />
      <Timeline.Connector />
    </Timeline.Rail>
    <Timeline.Content />
  </Timeline.Item>
</Timeline>;

Timeline.Rail, Timeline.Marker and Timeline.Connector are all supplied automatically when you leave them out, so an item needs only its Timeline.Content — write them explicitly when you want to give the marker children or force a connector.

The component owns the chronology layout and nothing else. It renders an <ol> of <li> and gives each item a rail; everything inside Timeline.Content is yours, and keeps its own semantics — headings stay headings, <time> stays <time>, links stay focusable. Use real HTML and real components in there rather than reaching for props that do not exist.

Centered Milestones

axis="center" runs the rail down the middle, which is the only axis on which placement means anything — an edge rail has one usable side, so every item resolves to side="end" there. placement="alternate" then flips content from side to side, and itemAlign="center" puts each marker at the middle of its own block so the alternation reads as one spine.

Studio Review

Compact Log

Incident Response

Version History

Repository Activity

Split Content

CSS Classes

Base Classes

• .timeline — The root <ol>. display: flex in a column with row-gap: var(--timeline-gap), min-width: 0, and list styling stripped. The vertical rhythm is this gap rather than padding on the item, which is what lets a centred marker sit at the true middle of its own content; the two lines bridge the gap by bleeding into it with a negative margin.
• .timeline--axis-start — Two columns, auto minmax(0, 1fr): rail then content. The default.
• .timeline--axis-center — Three columns, minmax(0, 1fr) auto minmax(0, 1fr): content, rail, content. Both outer columns are minmax(0, …), so long content wraps instead of pushing the rail off centre.
• .timeline--size-sm / .timeline--size-md / .timeline--size-lg — Set the four size variables together: a 12 / 16 / 20px marker, a 1 / 2 / 2px line, a 10 / 12 / 16px rail gap, and 13 / 14 / 15px content.
• .timeline--density-compact / .timeline--density-comfortable — Set --timeline-gap to 12px or 24px. Nothing else moves.

Element Classes

• .timeline__item — The <li>, display: grid with column-gap: var(--timeline-rail-gap). Carries data-status, data-side and data-align, plus aria-current="true" when the status is current.
• .timeline__rail — The marker-and-connector column, itself a three-row grid — lead line, marker, connector — justify-items: center and align-self: stretch. At data-align="start" the rows are 0 auto 1fr, so the marker tops out and no line is drawn above it; at data-align="center" they are 1fr auto 1fr and a ::before lead line fills row 1 on every item but the first.
• .timeline__marker — The dot. var(--timeline-marker-size) square, fully rounded, with border: 1px solid var(--timeline-marker-ring), background-color: var(--timeline-marker-fill) and color: var(--timeline-marker-ink). Bordered-flat — a ring and a fill, never a shadow. A marker with children (:not(:empty)) grows to --timeline-marker-size + 8px on both axes and takes 2px of padding, and a descendant svg is forced to 12px square.
• .timeline__connector — The line to the next event. var(--timeline-line-width) wide, background-color: var(--separator), filling row 3 of the rail and bleeding a full --timeline-gap past the item so it meets the next marker. On the last item — where it exists only because force asked for it — it becomes a 24px stub with no bleed, and :has() grows the item to hold it so the ink never leaves the <ol>'s box.
• .timeline__content — The event. min-width: 0, font-size: var(--timeline-font-size), line-height: 1.5, color: var(--foreground). Under a centred axis its data-side picks column 1 or 3 and hugs it to the rail with justify-self, which aligns the block without re-aligning your text.

Status Classes

Status is a data-status attribute rather than a class, set on both the item and the marker. The marker's own value wins by proximity, so <Timeline.Marker status="danger" /> inside a default item needs no extra specificity. Each value sets the same three custom properties:

• [data-status="default"] — --default fill, --muted ring, --default-foreground ink. A solid neutral dot.
• [data-status="current"] — --accent-soft fill, --accent-soft-foreground ring and ink, and a 2px ring instead of 1px so the live event is findable at a glance. This is the status that carries aria-current.
• [data-status="success"] — --success-soft fill, --success-soft-foreground ring and ink.
• [data-status="warning"] — --warning-soft fill, --warning-soft-foreground ring and ink.
• [data-status="danger"] — --danger-soft fill, --danger-soft-foreground ring and ink. The raw --danger is never painted as a fill or as text: it is identical in both themes and measures 1.89:1 on the dark surface.
• [data-status="muted"] — --default-soft fill, --muted ring, --default-foreground ink. Reads as hollow beside default's filled dot, so de-emphasis comes from the fill rather than from dimming the glyph.

Every ring clears the 3:1 non-text contrast floor in both themes. Marker ink clears 4.5:1 throughout in light; in dark, current and danger sit at ~3.4:1 against their own tint, so prefer an icon or a short glyph over a text label in those two, or leave the marker empty.

CSS Variables

All six are declared on .timeline and inherited by every part, so overriding one on the root retunes the whole component.

• --timeline-marker-size — Marker diameter. 16px at md.
• --timeline-line-width — Connector and lead-line thickness. 2px at md.
• --timeline-rail-gap — Horizontal space between the rail and the content. 12px at md.
• --timeline-font-size — Content type size. 0.875rem at md.
• --timeline-gap — Vertical space between items. 24px at comfortable.
• --timeline-marker-nudge — Derived, not authored: how far a start-aligned marker drops to sit on the first line's optical centre, (--timeline-font-size × 1.5 − --timeline-marker-size) ÷ 2. The connector adds it to its own bleed so the stroke still reaches the next marker.

Motion

Items animate in on mount — opacity plus an 8px rise over 280ms on var(--ease-out), staggered 50ms per item. The animation is motion/react rather than a CSS transition, so the reduced-motion opt-out lives in JS and covers both halves: prefers-reduced-motion: reduce and an explicit [data-reduce-motion="true"] on the component or any ancestor. Under either, the stagger is dropped and the rise is snapped out in a single frame while the fade plays at full length — gentler, never frozen.

API Reference

Timeline

The root. Renders an <ol>, holds the layout contract, and hands each item its index. Also accepts every native <ol> attribute.

Timeline.Item

One event — an <li>. Also accepts every native <li> attribute.

Timeline.Rail

The marker-and-connector column. Rendered automatically when an item omits it. Also accepts every native <div> attribute.

Timeline.Marker

The dot on the rail. Also accepts every native <span> attribute.

Timeline.Connector

The line to the next event. Always decorative, so always aria-hidden. Also accepts every native <span> attribute.

Timeline.Content

The event itself — a plain <div>, so whatever you put inside keeps its own semantics. Also accepts every native <div> attribute.

useTimelineItem

Reads the current item's resolved state. Only valid inside a Timeline.Item — use it to build a custom part alongside the built-in ones.

import {useTimelineItem} from "@blakeui/pro-react";

function StepNumber() {
  const {index, isLast} = useTimelineItem();
  return <span>{isLast ? "Final" : `Step ${index + 1}`}</span>;
}