Skip to content
WunderUI

Plan Step

Pro

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

Playground

Sync tokens from FigmaRunning—

Rewriting the variant map so legacy props keep resolving after the rename.

Targetpackages/react/tabs.tsxEstimate4 min

Installation

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

Then import what you need:

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

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

Sync tokens from FigmaRunning0:16

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.

Audit contrast on the docs siteDone1m 12s

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.

Sync tokens from FigmaQueued—

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

Compare the invoice export against the ledger for SeptemberDone0:42

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.

Sync tokens from FigmaRunning0:16

Rewriting the variant map so legacy props keep resolving after the rename.

Targetpackages/react/tabs.tsxEstimate4 min

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

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

  • The step title in 14 px medium text (13 px compact), one line, truncated at the end. A skipped title is struck through.

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

  • The duration you format, or a clock that counts up from the start while the step runs. A dash when there is neither.

  • Optional

    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.

  • Optional

    Detail text in 13 px under the title, indented to match. Left out in the compact density.

  • Optional

    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.

PropTypeDefaultDescription
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 requiredReactNode—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.
indexnumber—The step number, shown in the marker while the step is queued or blocked. The other statuses show an icon.
detailReactNode—A line of text under the title that says what the step is doing or why it failed. Left out in the compact density.
metaPlanStepMeta[]—Label and value pairs under the detail, such as . Left out in the compact density.
durationReactNode—How long the step took, formatted by you, such as or . The step shows a dash when this is empty and there is no .
sinceDate | 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.
actionReactNode—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.
classNamestring—Extra classes for the step, for example a width.
wrapboolean—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.

MCPget_component("plan-step")
InstallIncluded in Core and Pro

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