AgentStatusIcon
StableA small icon that shows what an assistant is doing right now, with a different shape for each state.
Also known as status icon, run status
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
All six states
<div className="flex gap-4">
<AgentStatusIcon status="working" />
<AgentStatusIcon status="needs-input" />
<AgentStatusIcon status="idle" />
<AgentStatusIcon status="completed" />
<AgentStatusIcon status="failed" />
<AgentStatusIcon status="stopped" />
</div>Each state has its own shape. The icon has a name for screen readers, so it works alone in a crowded row.
When to use it
A tiny picture of an assistant's state that still reads in a crowded row. Each state has its own shape so it works without color, and only "needs you" is amber, because only then must a person act.
Made of: Icon · Visible text (optional)
Use it for
- Beside a task or run name, to show its state at a glance.
- In a compact header or row where there is no room for words.
- With showLabel on, when there is room to write the state as well.
Not for
- A run that people press to open its details: use BackgroundRunChip.
- A general label, such as a category or a count: use Badge.
- Showing how far along one long job is: use GenerationProgress.
Do and avoid
Do
- Put the icon next to the task name so they are read together.
- Show the text where there is room, such as a page header.
- Use "needs you" only when a person must act.
Avoid
- Don't use it for anything except what an assistant is doing.
- Don't change its color. The color is part of the meaning.
- Don't put the words only in a hover tip.
On a phone
- It is a small icon that keeps its size on a phone, 16px by default.
- With showLabel the words sit beside the icon in 12px text, so the status is not shown by the icon alone.
- It has no tap action, so wrap it in a button if it must open something.
Seen in products
- Claude Code agent view shows a state icon per row, animated while working.
- Claude Code agent view lists the states Working, Needs input (yellow), Idle, Completed (green), Failed (red) and Stopped (grey), and shows process status by icon shape.
- Claude Code agent view notes that status should use icon shape and text, not color alone.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| statusrequired | "working" | "needs-input" | "idle" | "completed" | "failed" | "stopped" | none | Which state to show. Selects the shape, the tone and the default label. |
| size | number | 16 | Glyph width and height in px. |
| label | string | none | Replaces the default accessible text, for example to translate it. |
| showLabel | boolean | false | Render the label as visible text beside the glyph. |
| className | string | none | Extra classes. With showLabel they go on the wrapper, otherwise on the svg. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one AgentStatusIcon switches all of this from its properties panel, across 12 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| Status | status | Working, Needs-input, Idle, Completed, Failed, Stopped |
| Show label | showLabel | On or off |
Tokens
Change one of these and every part that uses it follows.
--attention--success--danger--fg-muted--fg-subtle
Built in
- Without visible text, screen readers hear the state as the icon's name, such as "Needs input".
- With showLabel on, the icon is hidden from screen readers and the words are read once.
- Each state has its own shape, so color is never the only clue.
- The working icon spins, and stops when people turn off motion in their system settings.
What you need to do
- Pass label in the person's language when your app is not in English.
- Turn on showLabel instead of writing the state beside the icon yourself, so it is not read twice.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide