StepTimeline
StableA list of steps in a task, showing which are done, in progress, waiting or failed.
Also known as stepper, steps, progress steps, activity timeline
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
In progress
Find missing documents
2 people
doneSend reminders
Waiting for approval
active- 3
Confirm receipt
todo
<StepTimeline steps={[
{ id: "a", title: "Find missing documents", detail: "2 people", state: "done" },
{ id: "b", title: "Send reminders", detail: "Waiting for approval", state: "active" },
{ id: "c", title: "Confirm receipt", state: "todo" },
]} />One step done, one in progress, one waiting.
When to use it
Shows the stages of a task in order, so people see at a glance what is done, what is happening now and what failed.
Made of: Status icon · Line between steps · Title · Detail · Status text for screen readers
Use it for
- A task whose steps must happen in order.
- Showing where a running workflow stands.
- Showing which step failed, with later steps still waiting.
Not for
- Open items with no set order: use Checklist.
- Events with dates, such as a history of changes: use Timeline.
- The details of one tool the assistant used: use ToolCallCard.
Do and avoid
Find flights
Found 4 options to Lisbon
doneBook the hotel
Payment did not go through
failed- 3
Send the plan
todo
- 1
Buy sunscreen
todo - 2
Pack a charger
todo - 3
Call grandma
todo - 4
Water the plants
todo
Do
- Mark only one step as in progress at a time.
- Use the detail line to say who or what is being waited on.
- Keep titles short, starting with an action word.
- Say why a step failed in its detail line, so people do not have to look elsewhere.
Avoid
- Do not use it for to-dos with no order. Use Checklist.
- Do not use it for dozens of steps. It cannot fold or scroll.
- Do not use amber here. Amber is for rows that need a person, in Checklist and ApprovalPrompt.
On a phone
- Steps stack in one column, and titles and details wrap inside the space beside the marker.
- Nothing in it is tappable, so there are no touch targets to size. Detail text is 12px.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| stepsrequired | Step[] | none | Ordered steps. Step is { id: string; title: string; detail?: string; state: "done" | "active" | "todo" | "failed" }. |
"Show code under the preview gives the code for the example on the stage."
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- done
- A step with state done shows a green check and a green connector line.
- active
- A step with state active shows a spinner and is marked as the current step.
- todo
- A step with state todo shows its number and dimmed title.
- failed
- A step with state failed shows a red cross.
Tokens
Change one of these and every part that uses it follows.
--success--danger--accent--border / --border-strong--fg-muted / --fg-subtle
Built in
- It is a numbered list named "Task progress".
- The step in progress is marked as the current step for screen readers.
- Each step has hidden text with its state (done, active, todo or failed), so meaning does not rest on color or icon.
- The spinner on the current step is read as "Loading".
What you need to do
- Mark only one step as active at a time.
- Put the reason for a failure in the step's detail. The hidden text only says "failed".
- Tell people when a step finishes or fails, for example with a short status message. The list does not announce changes.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide