# Plan Step

One step of an agent plan: number or status icon, title, status in words and how long it took.

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

## Install

Plan Step ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { PlanStep, PlanStepDensity, PlanStepMeta, PlanStepStatus } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

export function Step() {
  return <PlanStep status="done" title="Audit contrast on the docs site" duration="1m 12s" />
}
```

Expected result: You should see a green check in a round badge, the title Audit contrast on the docs site, and Done with 1m 12s at the end of the row.

## When to use

### Use Plan Step for

- A step of a plan the agent proposes or is running
- A row that says in words whether a step is queued, running, done, failed, skipped or blocked
- A step that opens sub-steps, with your own toggle in the action slot

### Use something else

- [Agent Plan](https://wunderui.com/components/agent-plan) for the whole plan with progress, editing and phases, built from Plan Steps
- [Run Timeline](https://wunderui.com/components/run-timeline) for the log of what a run actually did, with the input and output of each tool call
- [Approval Card](https://wunderui.com/components/approval-card) for a gate in the middle of a run that a person has to answer

## Behavior

What a step shows for each status, how its time works, what assistive technology hears and what moves.

- **Status:** Six statuses: queued, running, done, failed, skipped and blocked. Skipped means the agent chose not to run it; blocked means it waits on something else.
- **Time:** A running step counts up from its start time once a second, and keeps ticking under reduced motion. The count is empty on the server and first paint, so there is no hydration mismatch.
- **Name and role:** A step is a plain element with no role and cannot be focused. The status word is text after the title and is read with the step; the marker is hidden from assistive technology.
- **Live region:** A step does not announce status changes or its clock. When a step goes from running to done, put the change into a status line that is already in the page.
- **Action slot:** Whatever you put in the action slot is yours: it is focusable if it is a button, and the step does not touch it. Name it after what it acts on.
- **Density:** The compact density shrinks the marker to 20 px and the text to 13 px, and drops the detail and meta even when they are passed.
- **Motion:** The only movement is the spinning icon of a running step. Under reduced motion it stands still and the word Running carries the status.

## Anatomy

- `PlanStep`: One row of a plan with its status. A running step sits on an indigo tint with an 8 px radius and 10 px padding; the other statuses have no box.
- `Marker`: A round badge, 28 px (20 px compact), hidden from screen readers. It shows the step number while queued or blocked and an icon otherwise, spinning while running.
- `Title`: The step title in 14 px medium text (13 px compact), one line, truncated at the end. A skipped title is struck through.
- `Status label`: The status in words and in the status colour: Queued, Running, Done, Failed, Skipped or Blocked. It is always shown, so colour is never the only signal.
- `Time`: The duration you format, or a clock that counts up from the start while the step runs. A dash when there is neither.
- `Action`: A slot at the end of the row for your own control, such as a Retry button on a failed step or a toggle that opens sub-steps.
- `Detail`: Detail text in 13 px under the title, indented to match. Left out in the compact density.
- `Meta`: Label and value pairs separated by dots under the detail, such as Target and Estimate. Left out in the compact density.

## Best practices

### When to use

- Use a Plan Step for a step named in advance, before and during a run. For a log of what a run actually did, with input and output, use Run Timeline.

### Do

- Put the steps in an ordered list, one item each. A step is a plain element, so the list tells a screen reader how many steps there are.
- Set a status on every step and pass the start time on the running one. It then counts up by itself, starting on the client, so there is no hydration mismatch.
- Add an action such as Retry to a failed step and explain the failure in the detail. A failed step with no way forward is a dead end.
- Announce status changes in a status line that is already in the page before it has text. The step itself announces nothing.
- Use the compact density in side panels. It drops the detail and meta, so keep what matters in the title.

### Don't

- Don't rely on the marker colour. The status word sits next to the title in every density, so keep it.
- Don't invent a status the step does not have. There is no stopped or cancelled: show a parked step as queued and say in the plan header that the run stopped.

## API reference

### PlanStep

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | What the step does, one line, truncated at the end. A node, so it can hold a code element. A skipped step is struck through. |
| action | React.ReactNode |  | Your own control at the end of the row, such as a Retry button on a failed step or a toggle that opens sub-steps. |
| className | string |  | Extra classes for the step, for example a width. |
| density | "compact" \| "default" | "default" | `default` or `compact`. Compact shrinks the marker and the text and drops the detail and meta. |
| detail | React.ReactNode |  | A line of text under the title that says what the step is doing or why it failed. Left out in the compact density. |
| duration | React.ReactNode |  | How long the step took, formatted by you, such as `1m 12s` or `0:16`. The step shows a dash when this is empty and there is no `since`. |
| index | number |  | The step number, shown in the marker while the step is queued or blocked. The other statuses show an icon. |
| meta | PlanStepMeta[] |  | Label and value pairs under the detail, such as `{ label: "Target", value: "packages/react/tabs.tsx" }`. Left out in the compact density. |
| since | Date \| string \| number |  | When the step started, as a `Date`, an ISO string or a timestamp. A running step then counts up from it once a second. |
| status | "running" \| "done" \| "queued" \| "failed" \| "skipped" \| "blocked" | "queued" | Where the step is: `queued`, `running`, `done`, `failed`, `skipped` or `blocked`. It sets the marker, the colour of the status word and the word itself. |
| wrap | boolean |  | Whether a long title wraps onto more lines or truncates. Default: it wraps below 768 px (phones have no room for an ellipsis) and truncates from there up. `true` always wraps, `false` always truncates. |

## Examples

### Detail: nothing, a line of text, label and value pairs, an action

### Time: a duration, a live clock, no time

### Title: short, long, with code

### Wrap a long title or truncate it

## In context

### Sub-steps: a step that opens its children

The toggle sits in the action slot and says what it opens, and the parent's status follows its children. Press the chevron, or Tab to it and press Enter or Space.

### Run: the steps change status as the agent works

Press Start the run. The running step counts up and a status line says what changed, Stop parks the running step and Retry runs the failed one again; screen readers hear each change.

### Panel: compact steps in a side column

Compact density keeps one line per step, so a long plan fits a narrow panel. The status word stays next to every marker.

## For AI agents

`get_component("plan-step")`

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