Status

Examples

Beside a payment

Rent to Sam

Sent

While it moves

Sending, 42%

What happened

Scheduled for FridayDeclined, money returned

When to use it

Use: The state of a job that takes time: a transfer, a statement export, an upload.
Use: A row in a list of jobs, where each needs a state to scan.
Use: Beside a title in a detail view, to say where the work stands.
Not for: A step the assistant took inside a chat. Use Tool call.
Not for: A category or plan label that never changes. Use Badge.
Not for: A percentage as a bar. Use a progress bar, or put the figure in label.

7 rules

Must: Show the word with the dot, even in a tight row. Because the green Paid and red Declined dots look alike to a red-green colorblind reader.
Must: Use the default label or add detail to it; never invent a synonym. Because Complete on one screen and Paid on another read as two different states.
Should: Put a number or reason after a comma in label, such as Sending, 42%.
Never: Add a pulsing or pinging dot; the spinner is the only loop. Because a pulsing Scheduled dot looks like work in progress, which only the running spinner means.
Must: Keep five states; express a sixth in label on the nearest state. Because STATUS_META has five keys, so an unknown status throws when it renders.
Must: Wrap a status that changes while watched in role="status". Because Status is a plain span, so a change to Declined is never announced.
Never: Pass label="" when there is no detail; pass undefined so the default word shows. Because the component keeps an empty string and leaves a bare colored dot.

4 checks

: The word is always drawn, so the state never rests on color.
: Status is plain text and does not announce changes; use role="status" around it.
: The spinner keeps turning under reduced motion because it is the only sign that work runs.
: The dot is a background fill and may vanish in forced colors; the word carries the state.

6 edge cases

Long label: Wraps in the row; an unbroken string overflows, so keep labels short.
Narrow container: The dot centers against the wrapped text.
Right to left: The dot sits at the start and the word follows.
Reduced motion: The spinner keeps turning by design.
Status swaps: The mark and word change at once with no layout shift.
Inside a link or cell: It is an inline span; the dot keeps its own color.

3 props

status: 'queued' | 'running' | 'done' | 'failed' | 'canceled' default required
label: string default from STATUS_META
STATUS_META: Record<StatusName, {label, dot}>

8 tokens