Timeline

The timeline lays out a sequence of events along a connected line, with each event marked by an indicator. Use it for activity feeds, changelogs, and order or shipment history, or set value to drive it as a step progress indicator.

Preview

Installation

npx shadcn@latest add @cubby-ui/timeline

Usage

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

<Timeline>
  <TimelineItem>
    <TimelineIndicator />
    <TimelineSeparator />
    <TimelineHeader>
      <TimelineDate />
      <TimelineTitle />
    </TimelineHeader>
    <TimelineContent />
  </TimelineItem>
  <TimelineItem>
    <TimelineIndicator />
    <TimelineHeader>
      <TimelineDate />
      <TimelineTitle />
    </TimelineHeader>
    <TimelineContent />
  </TimelineItem>
</Timeline>

Composition

Timeline
└── TimelineItem
    ├── TimelineIndicator
    ├── TimelineSeparator
    ├── TimelineHeader
    │   ├── TimelineDate
    │   └── TimelineTitle
    └── TimelineContent

Set orientation on Timeline to lay items out vertically or horizontally.

Examples

Horizontal

Set orientation="horizontal" to flow events left to right.

Stepper

Pass value and onValueChange to drive the timeline as a step progress indicator.

API Reference

The Timeline component is a custom implementation. It does not extend Base UI.

Timeline Props

• defaultValue: number (default: 1) - Initial active step (uncontrolled)
• value: number - Active step (controlled)
• onValueChange: (value: number) => void - Callback when active step changes
• orientation: "horizontal" | "vertical" (default: "vertical") - Timeline layout direction

TimelineItem Props

• step: number (required) - Step number for this timeline item