Plan Step
ProOne step of an agent plan: a number or status icon, the title, the status in words and how long it took.
Playground
Rewriting the variant map so legacy props keep resolving after the rename.
Targetpackages/react/tabs.tsx·Estimate4 min
The npm registry did not answer within 30 s. Nothing was published.
Waits for Publish to npm to finish.
Installation
Plan Step comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
PlanStep,
PlanStepDensity,
PlanStepMeta,
PlanStepStatus,
} from "@wunderui/react"Then use it:
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 for
- Agent Plan for the whole plan with progress, editing and phases, built from Plan Steps
- Run Timeline for the log of what a run actually did, with the input and output of each tool call
- Approval Card for a gate in the middle of a run that a person has to answer
Detail
A step can say what it is doing, name its target and estimate, and offer a way forward. The detail block is left out in compact density, so keep what matters in the title.
Rewriting the variant map so legacy props keep resolving after the rename.
Rewriting the variant map so legacy props keep resolving after the rename.
Targetpackages/react/tabs.tsx·Estimate4 min
The npm registry did not answer within 30 s. Nothing was published.
Time
A finished step shows how long it took, as text you format, and a running step counts up every second. Without either the step shows a dash.
Title
The title is one line and truncates at the end, so give the step a width to truncate in. It can hold a code element.
pnpm test in packages/reactQueued—Wrap
By default a long title wraps below 768 px and truncates from there up. wrap forces it to wrap everywhere, wrap={false} to truncate everywhere.
Wrap a long title or truncate it
Behavior and motion
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
The figure shows a running step with a detail block, meta pairs and an action. Detail and meta are left out in the compact density.
Rewriting the variant map so legacy props keep resolving after the rename.
Targetpackages/react/tabs.tsx·Estimate4 min
- 1data-slot="plan-step"
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.
- 2
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.
- 3
The step title in 14 px medium text (13 px compact), one line, truncated at the end. A skipped title is struck through.
- 4
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.
- 5
The duration you format, or a clock that counts up from the start while the step runs. A dash when there is neither.
- 6Optional
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.
- 7Optional
Detail text in 13 px under the title, indented to match. Left out in the compact density.
- 8Optional
Label and value pairs separated by dots under the detail, such as Target and Estimate. Left out in the compact density.
Best practices
- 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.
- Do
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.
- Do
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.
- Do
Announce status changes in a status line that is already in the page before it has text. The step itself announces nothing.
- Do
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
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 is a plain component, not a wrapper of a primitive, so this table lists every prop.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| status | "running" | "done" | "queued" | "failed" | "skipped" | "blocked" | "queued" | Where the step is: , , , , or . It sets the marker, the colour of the status word and the word itself. |
| title required | 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. |
| index | number | — | The step number, shown in the marker while the step is queued or blocked. The other statuses show an icon. |
| detail | 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. |
| meta | PlanStepMeta[] | — | Label and value pairs under the detail, such as . Left out in the compact density. |
| duration | ReactNode | — | How long the step took, formatted by you, such as or . The step shows a dash when this is empty and there is no . |
| since | Date | string | number | — | When the step started, as a , an ISO string or a timestamp. A running step then counts up from it once a second. |
| action | 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. |
| density | "compact" | "default" | "default" | or . Compact shrinks the marker and the text and drops the detail and meta. |
| className | string | — | Extra classes for the step, for example a width. |
| 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. always wraps, always truncates. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("plan-step")The full library index for assistants is at /llms.txt.
Related components
Ship the Tabs v2 release
2 of 7 done
- Read the migration notesDone1m 12s
- Audit contrast on the docs siteDone0:48
- Sync tokens from FigmaRunning—
Rewriting the variant map so legacy props keep resolving after the rename.
Targetpackages/react/tabs.tsx·Estimate4 min
- 4Update the token mapQueued—
- 5Run the test suiteQueued—
- 6Publish to npmQueued—
- 7Notify the release channelQueued—
AI & Agents4 stylesProAgent PlanThe agent's plan as a checklist: follow it live, edit it before the run, or group it into phases.- Done420 tok$0.01640ms
Input
status: overdue, age: 30+ daysOutput
14 invoices, $42,860 in total - Done3,420 tok$0.042.1s
Input
14 invoice idsOutput
14 contacts, all with an email address - Running2,310 tok
Input
template: invoice-overdue-30 - Pending
Input
to: 14 recipients - PendingLog the result
AI & Agents5 stylesProRun TimelineEvery step of a run in order, with duration, tokens and expandable input/output.Send 14 payment reminders
Medium riskEmails the contact on every invoice more than 30 days overdue. Sent emails cannot be recalled.
2 min agoPOST /email/bulk to: 14 recipients template: invoice-overdue-30 dry_run: false
AI & Agents5 stylesProApproval CardThe human-in-the-loop gate: what the agent wants to do, how risky it is, approve or reject.