Agent Status
Three small ways to show where an agent is: a mark that turns into a check, a dot that pulses while it works, and a badge with the status in words.
- Read 50 invoices from the inbox1m 12s
- Match 47 invoices to purchase orders2m 40s
- Approve the new IBAN for Northwind4m 05s
- Draft payment run for Friday0m 38s
- Sync totals to the ledger0m 09s
- Email suppliers about late invoices0m 00s
Installation#
Usage#
Pass the agent's status and each part picks its own colour, pulse and words from one table, so a mark, a dot and a badge for the same agent always agree.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Anatomy#
import {
AgentStatusMark,
AgentStatusDot,
AgentStatusBadge,
useAgentStatusLabel,
} from "@/components/ui/agent-status"
import { agentStatuses, agentStatusMeta, type AgentStatus } from "@/lib/agent"Mark#
The mark for a step in a run. It stays a dot while the agent is live and becomes a check, a warning or a stop sign once it settles.
Live status#
The dot and the glyph share one spot, so a change blurs one out as the other comes in. Step through a run to see it.
Idle
Dot#
The dot alone, for a tab, an avatar corner or a dense table. Only working and waiting move.
Dot sizes#
Three sizes, from beside a line of small text to a header.
Badge#
The status in words. Only the two that need a person take colour: waiting and failed.
Badge options#
Every badge prop passes through: two sizes, a leading dot, a pulse, and your own words in place of the label.
In an agent list#
The mascot carries who the agent is and the badge carries where it is. Leave the mascot's own status off here, so the state is said once.
Capture
Reading 50 invoices from the inbox
Guard
Approve the new IBAN for Northwind
Ledger
Could not reach the ERP
Digest
Next run tomorrow at 08:00
API reference#
Every part accepts className, merged last.
AgentStatusMark
A 14px mark for a step or a row. Live statuses show a dot; done, failed and cancelled swap it for a glyph in place. Hidden from screen readers, so pair it with a label. Forwards all native <span> props except children.
| Prop | Type | Default | Description |
|---|---|---|---|
| status* | "working" | "waiting" | "idle" | "done" | "failed" | "cancelled" | - | The status to show. A change crossfades between the dot and the glyph. |
| Data attribute | Description |
|---|---|
| data-slot | agent-status-mark. |
| data-status | The status passed. |
AgentStatusDot
A Dot with its tone and pulse picked from the status. Forwards every Dot prop except tone and pulse.
| Prop | Type | Default | Description |
|---|---|---|---|
| status* | "working" | "waiting" | "idle" | "done" | "failed" | "cancelled" | - | Working pings in green, waiting blinks in amber, failed is red, the rest are neutral. |
| size | "xs" | "sm" | "md" | "sm" | 6, 8 or 10px. |
| shape | "round" | "square" | "round" | Circle or soft square. |
| ring | boolean | false | A faint inner ring, for a dot over a photo or a coloured fill. |
| Data attribute | Description |
|---|---|
| data-status | The status passed. |
AgentStatusBadge
A Badge with the status in words. Forwards every Badge prop.
| Prop | Type | Default | Description |
|---|---|---|---|
| status* | "working" | "waiting" | "idle" | "done" | "failed" | "cancelled" | - | Picks the label and the colour: warning for waiting, destructive for failed, neutral for the rest. |
| variant | BadgeProps["variant"] | - | Overrides the colour the status would pick. |
| size | "sm" | "md" | "md" | Badge height. |
| dot | boolean | false | A leading dot in the badge colour. |
| pulse | boolean | false | Pulses the leading dot. |
| children | React.ReactNode | - | Replaces the status label, e.g. a reason for the failure. |
| Data attribute | Description |
|---|---|
| data-status | The status passed. |
useAgentStatusLabel
useAgentStatusLabel(status, override?) returns the status in words from the nearest LabelsProvider, so text beside a mark or a dot matches the badge. Returns override when you pass one.
agentStatusMeta
From @/lib/agent. For each status: tone, pulse, badge, loud (it needs a person) and settled (it has finished). Every part above reads it.
agentStatuses
From @/lib/agent. Every status in order, for filters and pickers. agentStatusOrder sorts the loud ones first.