---
title: Timeline
description: Displays a timeline of events.
icon: timer
author:
  name: pasqualevitiello
  url: https://github.com/pasqualevitiello
mode: wide
---

<PoweredBy packages={[{ name: 'Origin UI', url: 'https://originui.com/timeline' }]} />

### Installation

```package-install
npx shadcn@latest add @redpanda/timeline
```

<ComponentPreview name="timeline-basic-demo" />

## When to use

Timeline displays chronological events. Use this decision tree:

```mermaid
graph TD;
    A[❓ Showing chronological data?] --> B{Sequential events?};
    A --> C[⚠️ Use other display components];
    B --> D[✅ Use Timeline Component];
    B --> E{Unordered information?};
    D --> F{Timeline complexity?};
    E --> G[⚠️ Use List or Cards];
    F --> H[✅ Basic Timeline];
    F --> I[✅ Detailed Timeline with dates];
    F --> J[✅ Activity Timeline];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class D,H,I,J recommended;
    class C,G discouraged;
    class A,B,E,F decision;
```

## Usage

```tsx
import {
  Timeline,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from '@/registry/components/timeline';
```

```tsx
<Timeline defaultValue={3}>
  {items.map((item) => (
    <TimelineItem key={item.id} step={item.id}>
      <TimelineHeader>
        <TimelineSeparator />
        <TimelineTitle className="-mt-0.5">{item.title}</TimelineTitle>
        <TimelineIndicator />
      </TimelineHeader>
    </TimelineItem>
  ))}
</Timeline>
```

## Examples

### Default

<ComponentPreview name="timeline-basic-demo" description="A timeline with event titles" />

### Detailed

<ComponentPreview name="timeline-detailed-demo" description="A detailed timeline with dates" />

### Activity

<ComponentPreview name="timeline-activity-demo" description="A timeline with activities" />

### Activity (Card)

<ComponentPreview name="timeline-activity-card-demo" description="A timeline with activities wrapped in a card" />

## Credits

- We use [Origin UI](https://originui.com/timeline) for the timeline component and style.

## Activity rows

Use `Timeline variant="activity"` for a compact activity list without the stepper
rail offset. Its items align icons, avatars, and content in a row, with 12-pixel
vertical padding and a 12-pixel gap. Content uses the standard foreground rather
than the stepper's secondary description color.

Both activity demos use this recipe. A containing `CardContent` owns horizontal
padding, so its rows do not add another horizontal inset. This intentionally
standardizes the old custom activity spacing; the default stepper geometry and
controlled step APIs are unchanged.