# Timeline

An ordered list of events, such as the steps of an agent run or the history of an order: each event has a marker (a dot, an icon or an avatar) colored by its status, a connector line to the next one, a title, a time, a description and any content. Vertical by default, or horizontal in a row.

**Dependencies:** npm: 0 direct, 1 total; registry: 2 direct, 2 total.

## Usage

### When to use

- Show events in the order they happened, such as the steps of an agent run, a deploy or the history of an order.
- An activity feed where each entry says who did what and when.

### When not to use

- Steps of a flow the user moves through. Use Stepper.
- A list of items with no order in time. Use a list or Table.
- A single status. Use Badge or Alert.

## Variants

### orientation

vertical stacks events down the page; horizontal lays them out in equal columns that scroll sideways when narrow.

Values: `vertical`, `horizontal`. Default: `vertical`.

### size

Marker box, text and spacing: 24, 32 or 40px markers.

Values: `sm`, `md`, `lg`. Default: `md`.

### status

On TimelineItem. Colors the marker from the status tokens.

Values: `default`, `success`, `warning`, `danger`, `info`. Default: `default`.

## Examples

### Agent run

Icons in soft status circles for the steps of a run, with the current step marked.

```tsx
<Timeline>
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" current />
</Timeline>
```

### Order history

Dots colored by status, with a description under each event.

```tsx
<Timeline>
  <TimelineItem status="success" title="Delivered" time="Oct 24" description="Left at the front desk." />
  <TimelineItem status="warning" title="Delivery delayed" time="Oct 23" description="Weather on the route." />
  <TimelineItem title="Shipped" time="Oct 21" />
  <TimelineItem title="Order placed" time="Oct 20" />
</Timeline>
```

### Statuses

Each status colors the dot (solid) or the icon circle (soft) from its status tokens.

```tsx
<Timeline>
  <TimelineItem title="Default" time="09:00" />
  <TimelineItem status="success" title="Success" time="09:05" />
  <TimelineItem status="warning" title="Warning" time="09:10" />
  <TimelineItem status="danger" title="Danger" time="09:15" />
  <TimelineItem status="info" title="Info" time="09:20" />
</Timeline>
```

### Activity with avatars

An avatar marker shows who acted; content holds anything under the description.

```tsx
<Timeline>
  <TimelineItem avatar={<Avatar alt="" color="blue">LT</Avatar>} title="Linh commented" time="2 hours ago">
    <Card className="p-md text-sm">Can we keep the old name for one release?</Card>
  </TimelineItem>
  <TimelineItem avatar={<Avatar alt="" color="green">AP</Avatar>} title="An opened the pull request" time="Yesterday" />
</Timeline>
```

### Failed step

danger marks a failed event; put the retry in the content.

```tsx
<Timeline>
  <TimelineItem status="success" icon={<IconCheck />} title="Build" time="1m 12s" />
  <TimelineItem status="danger" icon={<IconX />} title="Deploy" time="8s" description="The health check timed out.">
    <Button size="sm" variant="outline">Retry</Button>
  </TimelineItem>
</Timeline>
```

### Horizontal

orientation="horizontal" lays events out in equal columns that scroll sideways when narrow.

```tsx
<Timeline orientation="horizontal">
  <TimelineItem status="success" title="Placed" time="Oct 20" />
  <TimelineItem status="success" title="Shipped" time="Oct 21" />
  <TimelineItem status="info" title="Out for delivery" time="Oct 24" current />
  <TimelineItem title="Delivered" />
</Timeline>
```

## Do and don't

### Do

- Put events in the order they happened, oldest first, unless the newest matters most, as in an activity feed.
- Use status for the outcome of an event, and say it in the title too.
- Use one kind of marker per Timeline where you can; mix icons and avatars only when who acted matters.

### Don't

- Do not use Timeline for the steps of a flow the user moves through; use Stepper.
- Do not rely on the marker color alone; statusLabels and the title carry the meaning.
- Do not put long forms inside an event; link to a page instead.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `enum` | `vertical`, `horizontal` | `vertical` | vertical stacks events down the page; horizontal lays them out in equal columns that scroll sideways when narrow. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | Marker box, text and spacing: 24, 32 or 40px markers. |
| `statusLabels` | `{ success?: string; warning?: string; danger?: string; info?: string }` |  |  | Words read after a title for each status. Defaults: done, needs attention, failed, in progress. Vietnamese: xong, cần chú ý, thất bại, đang chạy. |
| `status` | `enum` | `default`, `success`, `warning`, `danger`, `info` | `default` | On TimelineItem. Colors the marker from the status tokens. |
| `icon` | `node` |  |  | On TimelineItem. An icon in a soft status circle, in place of the dot. |
| `avatar` | `node` |  |  | On TimelineItem. An Avatar in place of the dot, such as the person who acted. Give it the Timeline's size. |
| `title` | `node` |  |  | On TimelineItem. What happened. |
| `time` | `node` |  |  | On TimelineItem. When it happened, as shown, such as 10:42 or 2 hours ago. |
| `dateTime` | `string` |  |  | On TimelineItem. A machine-readable date for time, such as 2026-10-24T10:42. |
| `description` | `node` |  |  | On TimelineItem. A line or two of detail under the title. |
| `current` | `boolean` |  | `false` | On TimelineItem. Marks the current event with aria-current="step". |
| `scrollLabel` | `string` |  | `Timeline` | Names the scroll region of a horizontal timeline, which the keyboard can focus to scroll. Default "Timeline". |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | The ol: events stacked down the page, or in a row that scrolls sideways when narrow. |
| `item` | One event, a li: the rail, then the body. |
| `rail` | The marker and the line to the next marker. Hidden from screen readers. |
| `marker` | A box the size of the marker (24, 32 or 40px) that holds a dot, an icon in a soft status circle, or an avatar, so titles line up whatever the marker. Dots use the solid status color (color-gray, color-success, color-warning, color-danger, color-info); icons use the soft status fill and text (color-background-* with color-text-*). |
| `connector` | The 1px line (border-strong) from one marker to the next, with a gap at both ends. The last event has none. |
| `body` | The title row, the description and the content. |
| `title` | What happened, in medium weight primary text. |
| `time` | When it happened, in secondary text with tabular numbers. Vertical: on the title's row, never wrapping under it. Horizontal: always under the title. |
| `description` | A line or two of detail in secondary text. |
| `content` | Anything under the description, such as a Card, a CodeBlock or Buttons. |

## Accessibility

Role: `list`

| Keys | Action |
| --- | --- |
| `Tab` | Moves through any links or buttons inside the events. The list itself takes no focus. |

- The Timeline is an ordered list, so screen readers announce the number of events and the position of each one.
- Markers and lines are hidden from screen readers. A status other than default adds words after the title, EN `done`, `needs attention`, `failed`, `in progress`; change them with statusLabels.
- current marks one event with aria-current="step".
- Give time a dateTime so it renders as a time element with a machine-readable date.

## Install

```bash
npx werewolf-ui add timeline
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://www.werewolf-ui.dev/docs/installation.md) for requirements and the alternative registry setup.