# Run Timeline

Every step of a run in order, with duration, tokens and expandable input/output.

- Category: AI & Agents
- Page: https://wunderui.com/components/run-timeline
- Tier: Core and Pro

## Install

Run Timeline ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { RunTimeline, RunTimelineMarker } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { RunTimeline } from "@wunderui/react"

export function Run() {
  return (
    <RunTimeline
      steps={[
        { id: "load", label: "Load overdue invoices", status: "done", durationMs: 640, output: "14 invoices" },
        { id: "match", label: "Match contacts", status: "running" },
        { id: "send", label: "Send reminders", status: "pending" },
      ]}
      activeStepId="match"
    />
  )
}
```

Expected result: You see three rows: a green check with Load overdue invoices and 640ms, a spinning loader on a tinted row, and a grey ring. Press the first row to open its output.

## When to use

### Use Run Timeline for

- The steps of an agent run, in order, with the status, time and cost of each
- A run that is still going: the list grows as steps start and finish
- A failed or cancelled run, with the error and what was left undone

### Use something else

- [Chat Tool](https://wunderui.com/components/chat-tool) for one tool call inside a chat message
- [Timeline](https://wunderui.com/components/timeline) for events that are not steps of a run, such as an activity history
- [Stepper](https://wunderui.com/components/stepper) for the steps of a form or a wizard that a person moves through

## Keyboard

A step with details has a native button as its label, so Tab and Enter work as usual. A step without details is plain text, and arrow keys do nothing.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous step that has details, and on to the buttons inside an open step. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | Opens the focused step, or closes it when it is open. `aria-expanded` follows. Opening a step closes the one that was open. |

## Behavior

What the list does with its steps, details, numbers, screen readers and motion.

- **Steps:** The list follows the steps you pass, so a streaming run just passes a longer array. New rows appear at once, without a transition.
- **Details:** A step with an input or an output opens like a disclosure, one at a time. The default open step applies on the first render only.
- **Numbers:** Tokens read like 3,420 tok, cost prints as you wrote it, and durations read 640ms, 2.1s or 1m 04s. A running step shows no clock, so pair the list with an Agent Status.
- **Active step:** The active step gets a tinted row and is marked as the current step for screen readers. It does not depend on the status, so you pick the row.
- **Failure and abort:** A failed step is red with a cross, and its error belongs in its output. Steps after a failure stay pending, and after a cancel you mark them skipped (grey dash).
- **Assistive technology:** Each marker carries its status as hidden text, so a row reads Done Load overdue invoices. Changes are not announced, so add a status line that says what happened.
- **Long content:** A long label is cut with an ellipsis and has no tooltip, so keep labels short. Inputs and outputs wrap and the row grows with them.
- **Motion:** The marker of a running step spins. The details slide open and the chevron turns.
- **Reduced motion:** With reduced motion the loader stands still and the details open at once. A running step is still clear from its icon, its hidden Running text and its highlight.

## Anatomy

- `RunTimeline`: An ordered list with one item per step, in the order you pass them. Each item carries its status.
- `Marker`: A 24 px circle with a status icon: a ring when pending, a turning loader when running, a green check when done, a red cross when failed, a grey dash when skipped. The status is also hidden text.
- `Label`: The label in 14 px medium text on one line, cut with an ellipsis. A pending step is grey, and with a body behind it the label is a button.
- `Chevron`: A 14 px chevron after the label of a step that has an input or an output. It turns when the step is open.
- `Numbers`: On the right of the row, in 12 px tertiary text with tabular figures: tokens, cost and the duration, in that order, each only when you pass it.
- `Details`: The input and output in a bordered box with a 12 px radius under the row, each with a small label. Closed details are inert.
- `Active row`: The active step gets an indigo tint that reaches 8 px past the row on both sides, and marks its list item as the current step.

## Best practices

### When to use

- Use RunTimeline for the steps of one run, in order, with the time and cost of each. For one tool call inside a chat message use Chat Tool; for a plan the agent has not started use Agent Plan.

### Do

- Give every step a stable id. The open step is remembered by id, so a list that grows or reorders keeps its open row.
- Show a failed step with the error as its output and open it by default, so the reason is on screen. Leave later steps pending, and mark them skipped when the run was cancelled.
- Pass measured durations, tokens and costs, already formatted, like $0.04. Leave out a number you don't have, such as the duration of a running step.
- Highlight the step the run is on and describe what is happening in a status line next to the list. The list itself does not announce changes.
- Put an Approval Card in the output of the step that waits and open that step by default, so the gate sits where the run stopped.

### Don't

- Don't put long output in a step, because the details grow with their content and never scroll. Link to a Terminal Output or a Log Stream instead.
- Don't invent steps the agent has not planned, and don't show a done step that has not run. A timeline is a record, not a promise.

## API reference

### RunTimeline

| Prop | Type | Default | Description |
|---|---|---|---|
| steps* | RunStep[] |  | The steps, in order. Each is `{ id, label, status, durationMs?, input?, output?, tokens?, cost? }`: `status` is `pending`, `running`, `done`, `failed` or `skipped`; `durationMs` is milliseconds; `input` and `output` are React nodes shown in the details; `tokens` is a number; `cost` is already formatted, for example `$0.04`. |
| activeStepId | string |  | The `id` of the step the run is on. Its row is tinted and its item gets `aria-current="step"`. |
| className | string |  | Extra classes for the list, for example `w-full` or a margin. |
| defaultExpandedId | string |  | The `id` of the step whose details are open on the first render. Later changes are ignored. |
| expandedId | string \| null |  | Controlled id of the open step; `null` closes all. Pair it with `onExpandedChange`. |
| framed | boolean | false | Puts every step in a bordered card (`tone` sets the border). Use it with `marker="dot"`. Default `false`. |
| marker | "dot" \| "icon" | "icon" | `icon` draws a status icon per step, `dot` a small dot. Default `icon`. |
| onExpandedChange | (id: string \| null) => void |  | Called with the id of the step that was opened, or `null` when it was closed. |

## Examples

### Step status: pending, running, done, failed, skipped

### Details: none, input and output, output only, an error

### Numbers: the duration, the tokens and the cost, or none

### Active step: off and on

### Marker: icons, dots and framed steps

## In context

### A run that streams: the list grows, failure and cancel stop it

Press Start run. Steps are added when they start and timed when they end; pick Fails at step 3 to see the error, the pending rest and Retry, or Cancel the run to mark the rest skipped.

### An approval inside the run

The Approval Card is the output of the step that waits, and the step opens by itself. Approve lets it finish and Reject skips it; either way the last step runs, and a line says who answered.

### A finished run, folded into one line

The status, duration and totals stay in view and the steps open on demand, so a long run does not push the page down. Open a step to read its input and output.

## For AI agents

`get_component("run-timeline")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
