Skip to content
WunderUI

Run Timeline

Pro

What the agent did, in order: every step with its status, how long it took, what it cost, and the input and output behind it.

Playground

  1. Done
    420 tok$0.01640ms

    Input

    status: overdue, age: 30+ days

    Output

    14 invoices, $42,860 in total
  2. Done
    3,420 tok$0.042.1s

    Input

    14 invoice ids

    Output

    14 contacts, all with an email address
  3. Running
    2,310 tok

    Input

    template: invoice-overdue-30
  4. Pending

    Input

    to: 14 recipients
  5. Pending
    Log the result

Installation

Run Timeline comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • Chat Tool for one tool call inside a chat message
  • Timeline for events that are not steps of a run, such as an activity history
  • Stepper for the steps of a form or a wizard that a person moves through

Step status

Every step has one of five statuses, each with its own marker, and a line to the next step that turns green behind a finished one. The marker also carries the status as hidden text.

  1. Done
    Load overdue invoices640ms
  2. Pending
    Match contacts
  3. Pending
    Send reminders

Details

A step with an input or output opens in place, one at a time, and a step with neither stays a single line with no chevron. Show the error of a failed step as its output.

  1. Done
    Load overdue invoices640ms
  2. Done
    Match contacts2.1s
  3. Pending
    Send reminders

Numbers

The right side of a row holds tokens, cost and duration, in that order, each only when you pass it. A step that is still running has no duration yet.

  1. Done
    Load overdue invoices640ms
  2. Done
    Match contacts2.1s
  3. Pending
    Send reminders

Active step

The active step is highlighted and marked as current. Use it for the step that runs or waits, not for one that has finished.

  1. Done
    Load overdue invoices640ms
  2. Running
    Match contacts1,210 tok
  3. Pending
    Send reminders

Marker and frame

marker="dot" swaps the status icons for small dots, and framed puts every step in its own card. A step can carry a tool chip, a note, a body (for example an error card), a right cell and a tone that colours the frame. expandedId and onExpandedChange control which step is open.

Marker

  1. Done
    Read 214 variablesfigma.read3.2s
  2. Running
    Compare with styles.csstokens.diff
  3. Waiting for you
    Push to docs-preview
    Waits for your approval.

Keyboard interactions

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.

TaborShiftTab
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.
EnterorSpace
Opens the focused step, or closes it when it is open. follows. Opening a step closes the one that was open.

Behavior and motion

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

The figure marks a run with the last step open. The highlighted row of the active step and the hidden status text have no number.

  1. Done
    420 tok$0.01640ms

    Input

    status: overdue

    Output

    14 invoices
  2. Done
    3,420 tok$0.042.1s

    Input

    14 invoice ids

    Output

    14 contacts
  3. Done
    5.2s

    Input

    to: 14 recipients

    Output

    14 sent, 0 bounced
  • data-slot="run-timeline"

    An ordered list with one item per step, in the order you pass them. Each item carries its status.

  • 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.

  • 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.

  • Optional

    A 14 px chevron after the label of a step that has an input or an output. It turns when the step is open.

  • Optional

    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.

  • Optional

    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.

  • Optional

    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

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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 is a plain component, so the table lists every prop. A step has an id, a label and a status, plus optional duration, input, output, tokens and cost.

An ordered list with one item per step, in the order you pass them. Each item carries its status.

PropTypeDefaultDescription
steps requiredRunStep[]—The steps, in order. Each is : is , , , or ; is milliseconds; and are React nodes shown in the details; is a number; is already formatted, for example .
activeStepIdstring—The of the step the run is on. Its row is tinted and its item gets .
defaultExpandedIdstring—The of the step whose details are open on the first render. Later changes are ignored.
marker"dot" | "icon""icon" draws a status icon per step, a small dot. Default .
framedbooleanfalsePuts every step in a bordered card ( sets the border). Use it with . Default .
expandedIdstring | null—Controlled id of the open step; closes all. Pair it with .
onExpandedChange(id) => void—Called with the id of the step that was opened, or when it was closed.
classNamestring—Extra classes for the list, for example or a margin.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("run-timeline")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.