Status
Says where a piece of work stands, in one word.
Examples
Releasing prompt v14
Runs7
| Run | Agent | Status |
|---|---|---|
| run_4e11c2 | support-agent | Waiting on you |
| run_8f2a91 | triage | OK |
| run_77c0e4 | eval-runner | Running |
| run_3b19d2 | refund-agent | Failed |
| run_51aa07 | support-agent | Warning |
| run_9c04e8 | eval-runner | Queued |
| run_0d7f3a | triage | Idle |
Status
- Idle
idledefault
- Queued
queued
- Running
running
- OK
ok
- Warning
warn
- Failed
fail
- Waiting on you
waiting
Usage
When to use it
- Use
- A row, header or field shows work that moves through queued, running and an outcome.
- Use
- Work stops until a person acts: status="waiting" with the word that names the wait.
- Use
- A table column holds outcomes; sort it by statusRank, fail first.
- Not for
- The label is a category that never changes. Use Badge.
- Not for
- The person needs to know how far the work got. Use Progress.
- Not for
- The outcome needs a sentence and an action. Use Alert.
- Not for
- The change confirms something the person just did. Use Toast.
Rules
11 rules
- Must
- Set live on the one status the person is watching, and on no other in the view. Because each live Status holds its own status region, so a page of rows reads every run that settles, one over another.
- Never
- Color a status good or bad; only warn and fail take a text color. Because a green ok makes every healthy row compete with the amber and red ones the operator needs to find.
- Never
- Draw status as a green, amber or red dot or square; use Status. Because a dot has no word, so it vanishes in grayscale and forced colors and a screen reader reads nothing.
- Never
- Add a spinner beside a running row; the running arc is the spinner. Because Status already draws the arc for running, so a second spinner doubles the motion on every running row.
- Must
- Sort a status column by statusRank (fail 6, waiting 5, warn 4, running 3, queued 2, ok 1, idle 0), not by the word. Because sorting by the word puts Failed between Idle and OK, so the failed runs never reach the top.
- Never
- Show work paused on a person as warn; use status="waiting", whose word is "Waiting on you". Because an approval is a normal step, and a warm row sends the operator looking for a failure that is not there.
- Must
- Show at most one InkSlot (the paper waiting label) per card or panel; the rest of the queue is a count. Because the label says what waits on a person, and two in one card or panel leave no single thing to do first.
- Should
- Override the word with one to three that keep the outcome: Refund failed, never a sentence.
- Should
- Name the outcome in sentence case (Connected, Expires in 3d) instead of a glyph.
- Must
- Give a bare StatusArc name="Running". Because without name the arc is aria-hidden, so a screen reader skips that the work is running.
- Should
- Show one running count in the header instead of more than 12 turning arcs.
Accessibility
6 checks
- The word is the status for screen readers; color is never the only signal.
- Warn and fail use --warn-text and --fail-text, 4.5:1 or better on paper and the well in both themes; the InkSlot is ink text on paper, 4.5:1 or better in both themes.
- A live status speaks once through a polite status region when it settles; the visible word is aria-hidden meanwhile.
- The running arc is aria-hidden beside the word; a bare StatusArc is role="img" named by name.
- Status is not focusable.
- Forced colors drop warn and fail to plain words; the arc draws CanvasText and the InkSlot keeps a transparent 1px border so its box survives.
Edge cases
10 edge cases
- Long word
- Wraps under itself; the arc stays on the first line.
- 18 statuses in 120px
- They wrap; show a running count instead of many arcs.
- Right to left
- The arc sits at the start and the word follows.
- Zoom 200%
- The word and the rem-sized arc double together.
- Pressed through six states ten times a second
- The live region updates only on ok, warn and fail.
- Inside a kind row
- data-status beats the inherited data-kind; fail stays red.
- No status prop
- Renders Idle; no children renders the default word.
- Run never returns
- Stays running and live stays silent; the caller sets warn after its deadline.
- Reduced motion
- The arc stops, stays drawn, and the word says Running.
- Two waits in one card or panel
- Show one InkSlot with the count; in a DataTable the wait is the plain ink word and each row keeps its own action.
API
6 props
status'idle' | 'queued' | 'running' | 'ok' | 'warn' | 'fail' | 'waiting'default'idle'variant'plain' | 'field'default'plain'labelstring | truelivebooleanInkSlot size'default' | 'sm'default'default'childrenReactNode
Tokens
12 tokens
--type-state-word- 400 14px/16px var(--font-sans)
--features-data- "tnum", "zero", "ss04"
--text-1- var(--ink)
--text-2- oklch(var(--ink-c) / 0.80)
--text-3- oklch(var(--ink-c) / 0.66)
--warn-text- oklch(49% 0.100 68)
--fail-text- oklch(51% 0.180 26)
--dur-spin- 800ms
--ease-spin- linear
--surface-page- var(--paper)
--line-control- oklch(var(--ink-c) / 0.16)
--radius-inner- 4px