Timeline

Install

pnpm dlx shadcn@latest add @vegastack/timeline

Usage

import {
  Timeline,
  TimelineItem,
  TimelineSeparator,
} from "@/components/ui/timeline";

<Timeline aria-label="Activity">
  <TimelineSeparator>Today</TimelineSeparator>
  <TimelineItem node={<StatusIcon status="done" size="sm" label="" />}>
    <Item size="sm">
      <ItemContent>
        <ItemTitle>Deal moved to Won</ItemTitle>
      </ItemContent>
      <ItemContent className="text-muted-foreground">
        <RelativeTime date={when} now={now} refresh={false} />
      </ItemContent>
    </Item>
  </TimelineItem>
</Timeline>;

Timeline is rail geometry only — the continuous vertical connector with a node per entry. Everything a row needs already exists: Item parts for the event itself, RelativeTime for timestamps, Avatar for actors, and Marker's separator variant renders the group headers. There is deliberately no TimelineTitle/TimelineDescription — that would fork Item's vocabulary.

Scope

Anatomy

Timeline is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

Anatomy

Timeline              <ol> — the record
├─ TimelineSeparator  group header via Marker variant="separator"
└─ TimelineItem       <li>: aria-hidden rail (node + connector) + content
   └─ Item            the event row — Item owns the anatomy

Status nodes and linked rows

The rail node is decorative (aria-hidden) — meaning must live in the row content. A whole row becomes a link through Item's own render, not through the timeline.

Day grouping

TimelineSeparator renders a computed group header through Marker's separator variant. The component imposes no grouping of its own — the host decides where a day boundary falls and emits a separator there.

API Reference

Item

TimelineSeparator adds no props of its own — it accepts everything <li> accepts and renders its children through Marker variant="separator". Place separators between items, never as the final child (the last item's connector hides via :last-child).

Accessibility

• Compose Item rows directly — an Item outside an ItemGroup carries no ARIA role, so the <li> stays the only list item and nothing nests invalidly. A render-composed interactive row keeps its native link/button role.
• An <ol> of <li> entries, labelled via aria-label; group separators are real list items (an <ol> may only contain list items) rendered through Marker's separator variant — wrap their children in a heading element when the label should join the page outline.
• The rail column (node + connector) is aria-hidden decorative geometry; an entry's status must also appear as text in its content, never by node colour alone. Superseded entries need a text signal, never strike-through alone.
• Give each entry a <time dateTime> — RelativeTime renders one, with its deliberate no-aria-live policy (a feed that re-announces every minute is noise). Leave the timestamp column at the row's own type size: RelativeTime is a focusable tooltip trigger, and its invisible hit area is sized against a 14px line box, so shrinking it to text-sm drops the effective target under the 24px floor.

Do / Don't