Timeline

Ordered events with a progress step. Drive completion with defaultValue or controlled value. Vertical or horizontal, LTR and RTL.

Vertical

Launch log

A calm vertical changelog. Completed steps fill the indicator via defaultValue.

Loading…

Horizontal

Sprint phases

orientation="horizontal" for a short delivery plan across the sprint.

Loading…

Installation

CLI

npx @sonojs/ui@latest add timeline

Usage

timeline.tsx

import {
  Timeline,
  TimelineContent,
  TimelineDate,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from "@/components/ui/timeline"

export function Example() {
  return (
    <Timeline defaultValue={2} className="w-full max-w-lg">
      <TimelineItem step={1}>
        <TimelineHeader>
          <TimelineDate>Mar 12, 2025</TimelineDate>
          <TimelineTitle>Private alpha</TimelineTitle>
        </TimelineHeader>
        <TimelineIndicator />
        <TimelineSeparator />
        <TimelineContent>
          Invite-only access for design partners.
        </TimelineContent>
      </TimelineItem>
      <TimelineItem step={2}>
        <TimelineHeader>
          <TimelineDate>Jun 3, 2025</TimelineDate>
          <TimelineTitle>Public beta</TimelineTitle>
        </TimelineHeader>
        <TimelineIndicator />
        <TimelineSeparator />
        <TimelineContent>
          Waitlist opened with usage meters and team invites.
        </TimelineContent>
      </TimelineItem>
      <TimelineItem step={3}>
        <TimelineHeader>
          <TimelineDate>Sep 18, 2025</TimelineDate>
          <TimelineTitle>General availability</TimelineTitle>
        </TimelineHeader>
        <TimelineIndicator />
        <TimelineSeparator />
        <TimelineContent>
          Stable SLA and self-serve onboarding for every plan.
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  )
}

Props

Prop	Type	Default	Description
defaultValue	number	1	Initial active step. Items with `step` ≤ this value are completed.
value	number	—	Controlled active step.
onValueChange	(value: number) => void	—	Called when the active step changes.
orientation	"vertical" · "horizontal"	"vertical"	Layout axis for items, separators, and indicators.
step	number	—	`TimelineItem` only. Ordinal index compared to the active step.
asChild	boolean	false	`TimelineDate` / `TimelineIndicator` — merge props onto the child.