BackgroundRunChip
StableA small chip for a run in the background that opens its details.
Also known as background task, running job
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Four runs in a row
Choose a run to see its details.
<BackgroundRunChip name="Invoices" status="needs-input" statusText="Needs you" elapsed="12 min" onClick={() => openDetails("invoices")} />Press a chip to open its details. The run that needs you is amber.
When to use it
A small pill for a run that keeps going while the person does other things. It stays calm while the run works and turns amber only when the run needs the person.
Made of: State icon · Run name · Short status · Time elapsed
Use it for
- A row of background runs in a header or footer.
- Opening a run's details or a quick peek.
- Drawing attention to a background run that is waiting on the person.
Not for
- A full list of runs with summaries and replies: use AgentSessionList.
- Saying who is in control of the screen: use TakeoverBar.
- A status that nobody needs to press: use AgentStatusIcon.
Do and avoid
Do
- Use it where space is tight, such as a header or a side rail.
- Keep the status to two or three words.
- Open a peek or panel with the full story on press.
- Group chips that need you first.
Avoid
- Do not use amber for working, done or failed runs.
- Do not put more than a name and a short status in the chip.
- Do not use a chip for an action. It only opens details.
- Do not let the elapsed time tick every second for screen readers.
On a phone
- The chip never grows wider than its container, and the name and status text are cut with an ellipsis when they do not fit.
- Nothing shows the full text of a cut name on a phone, so keep names and status words short.
- On a touch screen the chip keeps its size and has a 44px tap area.
Seen in products
- Claude Code agent view: each session has a state icon, and Space opens a peek panel with the question and a reply box.
- Claude Code lets a command run in the background and keeps it visible.
- Microsoft: background work stays easy to reach and mostly out of the way.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| namerequired | string | none | Name of the run. |
| statusrequired | AgentStatus | none | working, needs-input, idle, completed, failed or stopped. needs-input gets the amber style. |
| statusText | string | none | Short status. Defaults to a plain word for the status. |
| elapsed | string | none | Time the run has been going, such as 4 min. |
| expanded | boolean | none | Set while the details this chip opens are showing. Sets aria-expanded. |
| onClick | MouseEventHandler<HTMLButtonElement> | none | Opens the details. Other button attributes pass through. |
| className | string | none | Extra classes on the button. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one BackgroundRunChip switches all of this from its properties panel, across 4 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| State | Hover, Pressed and Focus come from the browser. | Default, Hover, Pressed, Focus |
| Name | name | Any text |
| StatusText | statusText | Any text |
| Elapsed | elapsed | Any text |
Tokens
Change one of these and every part that uses it follows.
--attention-soft--attention-fg--surface--line--radius-control
Built in
- It is one real button, and its name reads the state, the run name, the status and the time together.
- Amber comes with the words Needs you and a question-mark icon, so it does not rely on color.
- It tells screen readers whether its panel is open when you pass expanded.
- The spinning icon stops when people turn off motion in their system settings.
What you need to do
- Pass expanded while the panel it opens is showing. Leave it out if the chip goes to another page.
- Keep statusText short, because it is read in the button name with the run name and time.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide