# Timeline

> An ordered list of what happened — a task's history in task-status colors and plain words, or an agent's activity log in presence colors and Space Mono.

Source: https://raft-design.botiverse.build/components/timeline. Generated from the current release; where it differs from what you remember, this page is right.

A Timeline lists what happened, in order. Each step is a status pixel on a hairline, with its title and its time. It has two uses: a task's History, in the colors of the task statuses and in plain words, and an agent's activity log, in the colors of the presence lights and in Space Mono.

```tsx
import {
  Timeline,
  TimelineContent,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@botiverse/raft-ui";

export function TimelinePreviewContent() {
  return (
    <Timeline className="w-72">
      <TimelineItem>
        <TimelineTitle>Draft</TimelineTitle>
        <TimelineContent>Draft opened for review</TimelineContent>
        <TimelineTime>2026-10-01 09:12</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="success">
        <TimelineTitle>Checks</TimelineTitle>
        <TimelineContent>All checks passed</TimelineContent>
        <TimelineTime>2026-10-01 10:40</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="warning">
        <TimelineTitle>Review</TimelineTitle>
        <TimelineContent>One reviewer asked for changes</TimelineContent>
        <TimelineTime>2026-10-01 14:05</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="danger">
        <TimelineTitle>Deploy</TimelineTitle>
        <TimelineContent>Deploy to staging failed</TimelineContent>
        <TimelineTime>2026-10-01 16:30</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="accent">
        <TimelineTitle>Review</TimelineTitle>
        <TimelineContent>Waiting on a reviewer</TimelineContent>
        <TimelineTime>2026-10-02 08:00</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="information">
        <TimelineTitle>Release</TimelineTitle>
        <TimelineContent>Waiting on the release window</TimelineContent>
        <TimelineTime>2026-10-02 09:30</TimelineTime>
      </TimelineItem>
    </Timeline>
  );
}
```

## When to use

| Situation                                                                                                                              | Use                                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| A task's History, collapsed under its properties in task details                                                                       | Timeline ([Built from existing parts](https://raft-design.botiverse.build/components.md#task-details))                                         |
| What an agent did ([Hand-offs and approvals](https://raft-design.botiverse.build/people-and-agents/handoffs-and-approvals.md#the-record-afterwards)) | Timeline, as an activity log                                                                                                              |
| The steps of a flow the person goes through                                                                                            | [Steps](https://raft-design.botiverse.build/components/steps.md)                                                                                                                |
| Facts about an item, not events                                                                                                        | [DescriptionList](https://raft-design.botiverse.build/components/description-list.md)                                                                                |
| Messages and event lines in a conversation                                                                                             | [SystemMessage](https://raft-design.botiverse.build/components/system-message.md) in the conversation ([Conversation](https://raft-design.botiverse.build/patterns/conversation.md)) |

## Anatomy

- `Timeline`: the ordered list. Required.
- `TimelineItem`: one step, with its marker and the line to the next step. Required.
  - `TimelineTitle`: what happened. Required.
  - `TimelineContent`: a detail line in Space Mono: a commit, a file count. Optional.
  - `TimelineTime`: when, in Space Mono, at the right end of the first line. Optional.

Only the title and the time share the first line. A detail below them runs the full width of the item: the time reserves its column for that first line alone, so holding the detail beside it would narrow the detail by a time it never sits next to — on a phone, most of the row. An item with no title keeps its one line, where the detail does sit beside the time.

A long title and a long time still compete on the first line, because a time does not wrap. Keep a time short where the column is narrow.

## Variants

| Variant                                           | Use for                                                                                                                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Task history: `taskStatus` on each item           | The pixel is the task's status after that step, in its `task-status-*` color                                                                                  |
| Activity log: `color` (or `variant`) on each item | The pixel takes the colors of the presence lights: `presence-busy` (yellow) while working, `presence-error` (orange) for an error, lime (`success`) when done |
| `icon` on an item                                 | An icon in place of the pixel, in the item's color, for a step that needs one                                                                                 |
| `itemPlacement="right"`                           | Markers on the right, text aligned to them                                                                                                                    |
| `horizontal`                                      | A short sequence of milestones in a row                                                                                                                       |

```tsx
import { Check, Clock } from "lucide-react";
import { Timeline, TimelineContent, TimelineItem, TimelineTitle } from "@botiverse/raft-ui";

const checkIcon = <Check strokeWidth={3} />;

const clockIcon = <Clock strokeWidth={2.5} />;

export function TimelineIconContent() {
  return (
    <Timeline iconSize={16} className="w-72">
      <TimelineItem variant="success" icon={checkIcon}>
        <TimelineTitle>Shipped</TimelineTitle>
        <TimelineContent>An icon replaces the dot</TimelineContent>
      </TimelineItem>
      <TimelineItem variant="information" icon={clockIcon} lineType="dashed">
        <TimelineTitle>In transit</TimelineTitle>
        <TimelineContent>It takes the variant's color</TimelineContent>
      </TimelineItem>
      <TimelineItem color="var(--palette-lavender-400)">
        <TimelineTitle>Custom color</TimelineTitle>
        <TimelineContent>Or a custom color</TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}
```

```tsx
import {
  Timeline,
  TimelineContent,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@botiverse/raft-ui";

export function TimelinePlacementContent() {
  return (
    <div className="grid w-full max-w-lg grid-cols-2 gap-8">
      <Timeline>
        <TimelineItem>
          <TimelineTitle>Left</TimelineTitle>
          <TimelineContent>Markers on the left</TimelineContent>
          <TimelineTime>09:00</TimelineTime>
        </TimelineItem>
        <TimelineItem variant="success">
          <TimelineTitle>Left</TimelineTitle>
          <TimelineContent>The default placement</TimelineContent>
          <TimelineTime>10:00</TimelineTime>
        </TimelineItem>
      </Timeline>
      <Timeline itemPlacement="right">
        <TimelineItem>
          <TimelineTitle>Right</TimelineTitle>
          <TimelineContent>Markers on the right</TimelineContent>
          <TimelineTime>09:00</TimelineTime>
        </TimelineItem>
        <TimelineItem variant="success">
          <TimelineTitle>Right</TimelineTitle>
          <TimelineContent>Text aligns to the markers</TimelineContent>
          <TimelineTime>10:00</TimelineTime>
        </TimelineItem>
      </Timeline>
    </div>
  );
}
```

```tsx
import { Timeline, TimelineContent, TimelineItem, TimelineTime } from "@botiverse/raft-ui";

export function TimelineHorizontalContent() {
  return (
    <Timeline horizontal>
      <TimelineItem>
        <TimelineContent>Order placed</TimelineContent>
        <TimelineTime>Mon</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="information">
        <TimelineContent>Packed</TimelineContent>
        <TimelineTime>Tue</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="success" lineType="dashed">
        <TimelineContent>Shipped</TimelineContent>
        <TimelineTime>Wed</TimelineTime>
      </TimelineItem>
      <TimelineItem variant="warning">
        <TimelineContent>Out for delivery</TimelineContent>
        <TimelineTime>Thu</TimelineTime>
      </TimelineItem>
    </Timeline>
  );
}
```

## Content

### Task history

- Write each title as who did what, with the name in bold: "**Bugen** claimed it", "**Bugen** moved it to In Review".
- Put the evidence in the detail line: "commit c41e09 · 4 files changed".

### Activity log

- Set the title and the detail in Space Mono: the log is what a machine wrote ([Typography](https://raft-design.botiverse.build/foundations/typography.md#principles)).
- Mark a step done by a subagent with a `subagent` tag.
- Write only what the agent did. Don't show its prompts or its output.

## Accessibility

- `Timeline` renders a native `ol` and each `TimelineItem` an `li`, so the order and the number of steps are announced. raft-ui adds no Base UI primitive.
- The marker and the line are hidden from assistive technology. When the color carries meaning, say it in the title too: "moved it to In Review", "failed: CI".

## Rules

- Don't make a timeline clickable. To go to the object of a step, link that object in the title: the task, the commit, the file.
- Mark a step that failed in orange (`warning`, or `presence-error` in a log), not `danger`: red is only for consequences that cannot be undone ([Color](https://raft-design.botiverse.build/foundations/color.md#meanings-of-color)).

## API

### Timeline

An ordered list of events; each `TimelineItem` has a marker and a line to the next.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `horizontal` | `boolean` | `false` | Lays the items out in a row instead of a column. |
| `iconSize` | `number` |  | Marker size in px. Defaults to 9px for the marker and 14px for an `icon`. |
| `itemPlacement` | `TimelineItemPlacement` | `"left"` | Which side the markers sit on in a vertical timeline. Ignored when `horizontal`. |
| `size` | `TimelineSize` | `"md"` | Title size: `lg` opens the title to 16/24; `sm` and `md` share the 14/20 scale. |

Also takes the attributes of its element.

### TimelineContent

Also takes the attributes of its element.

### TimelineItem

One event: a marker on the axis, then its title, content and time as children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `string` |  | A custom marker color; overrides `variant`. |
| `icon` | `ReactNode` |  | Replaces the dot marker; takes the variant's color. |
| `lineType` | `TimelineLineType` | `"solid"` | The line from this item to the next. |
| `taskStatus` | `TaskStatusId` |  | Render the marker from a task status's colour token instead of a generic `variant`. Takes precedence over `variant`; `color` still wins when both are set. Omit it and the item behaves exactly as before. |
| `variant` | `TimelineItemVariant` | `"default"` | Marker color role. |

Also takes the attributes of its element.

### TimelineTime

Also takes the attributes of its element.

### TimelineTitle

Also takes the attributes of its element.

## Changes

- 0.10.0 (Changed): `Tooltip`, `ComboboxSelect` options, `Steps` and `Timeline` use the type scale instead of fixed sizes, so they follow the desktop values.
- 0.5.30 (Added): Added the `taskStatus` prop on `TimelineItem`, which paints the marker from the status colour. Omitting it leaves the item unchanged.