Skip to content
WunderUI

Agent Status

Pro

The state of one agent run as a pill: queued, running, waiting for you, done, failed or cancelled, with the time it has been there.

Playground

Running

Installation

Agent Status comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import { AgentStatus } from "@wunderui/react"

Then use it:

tsx
import { AgentStatus } from "@wunderui/react"

export function RunState({ startedAt }: { startedAt: Date }) {
  return <AgentStatus status="running" since={startedAt} />
}

Expected result: You should see a small indigo pill with a turning loader and Running, 0s, counting up once a second. Switch the status to done with an end time and it shows a green check and the fixed duration.

When to use

Use Agent Status for

  • The state of one agent run: queued, running, waiting for a person, done, failed or cancelled
  • The time a run has been in that state, or how long it took
  • A header, a row of a run list or a card of a dashboard

Use something else for

  • Run Timeline for the steps of a run, each with its own status and duration
  • Usage Meter for spend against a budget
  • Badge for a static label that is not the state of a run

Counter

A live run counts up from its start. A finished run with an end time shows its fixed duration, and without an end time it shows the time since the start and keeps counting.

Running

Size

Use the small pill in dense rows, where the row already carries the context.

Running

Label

Keep the status and change the word only when a more precise one helps. The pill never wraps.

Waiting for you

Paused

A paused run shows a pause icon and no live counter. Pass since with endedAt (the moment of the pause) to show how long it ran before it was held.

Paused

Behavior and motion

What the pill does with its clock, its label, assistive technology and motion.

Clock
Running and waiting count up once a second. A finished run with start and end times shows a fixed duration; with only a start time it keeps counting, by the second under an hour, then by the minute.
Format
Under a minute it reads 47s, under an hour 4m 07s, then 2h 14m. An invalid start time, or an end before the start, causes no error, and without a readable start there is no counter.
First paint
A live counter is empty on the server and the first client render, then fills in, so the pill widens. A fixed duration renders at once.
Label
The default word per status, or your own label as a string. The pill neither wraps nor shrinks, so keep a custom label short.
Assistive technology
A screen reader reads the pill as its text, like Running, 2m 14s. It announces no change, and the counter is deliberately not a live region, or it would speak every second.
Failure and abort
Failed is red and cancelled is grey, each with its own icon and word. Use cancelled when a person stopped the run and failed when it broke.
Motion
Only the running icon moves: it turns. Nothing else animates, and a status change swaps tint, icon and word at once.
Reduced motion
With reduced motion on, the loader stands still. The word Running and the counter, which still ticks, say what is going on.

Anatomy

The figure marks a running pill with a counter. A pill without a start time has no counter and no number 4.

Running
  • data-slot="agent-status"

    A pill with a 1 px border in 12 px medium text. Tint, icon and word follow the status; it is a plain span with no role and no live region.

  • A 14 px Lucide icon (12 px in the small size) in the text colour. Running shows a loader that turns when motion is allowed; the icon is decorative and the word carries the state.

  • The status word (Idle, Running, Waiting for you, Done, Failed, Cancelled) or your own label. It never wraps; the pill takes the width of its text.

  • Optional

    A time such as 2m 14s in regular weight with tabular figures, shown when a start time is set. It appears after the first client render, so the server never prints a stale time.

Best practices

  • Do

    Pass a start time for running and waiting; both tick every second. For a finished run pass an end time too, and the pill shows the fixed duration.

  • Do

    Use waiting when a person has to act (Waiting for you) and idle for a queued run. A run blocked on an approval is waiting, not running.

  • Do

    Say a change in a status line next to the pill, like Failed at step 3, nothing was sent. The pill is silent, and a colour or icon never carries the state alone.

  • Do

    Pass a new start time when the status changes, so the counter shows how long the run has been in the new state. Keep the old one only if the counter means the whole run.

  • Do

    Override the label only for a more precise word such as Needs approval or Retrying, and keep the status that matches the run so tint and icon stay right.

  • Don’t

    Don't build the pill from a Badge and a Spinner. It has one icon, one tint and one word per state, and its counter keeps running when a run stalls.

  • Don’t

    Don't show failed or cancelled without saying what was already done. The pill says the run stopped, not what it left behind: add that sentence next to it.

API reference

AgentStatus is a plain component, so the table lists every prop.

A pill with a 1 px border in 12 px medium text. Tint, icon and word follow the status; it is a plain span with no role and no live region.

PropTypeDefaultDescription
status required"cancelled" | "paused" | "running" | "done" | "idle" | "failed" | "waiting"—The state of the run: , , , , , or . Picks the tint, the icon and the default word. is a held run: a static pause icon and no live counter.
sinceDate | string | number—When the run entered this status, or when it started when you also pass . A , an ISO string or a timestamp in milliseconds. Starts the counter.
endedAtDate | string | number—When a finished run ended. With the pill shows the fixed duration . Ignored while the status is or .
labelstring—Replaces the default word of the status, for example . A string, kept on one line.
showElapsedbooleantrue by default. Set to hide the counter even when is set, for a row that already carries a timestamp.
size"sm" | "default""default" (12 px text, 14 px icon) or (11 px text, 12 px icon) for dense rows.
classNamestring—Extra classes for the pill, for example a margin.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("agent-status")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.