# Status (/docs/agent-ui/components/status)

Use a status badge beside a run, a job or a tool call to show whether it's waiting, running, needs input or is done. Its mark and its text both say the status, so it never depends on color alone.

<Example caption="Each badge shows its run's status. When the status changes, the mark morphs into its new shape.">
<g />

```tsx
import { Status } from "@/components/ui/status";

export default function StatusExample() {
  return (
    <ul className="flex w-72 flex-col gap-2 text-sm">
      <li className="flex items-center justify-between gap-3">
        Build
        <Status status="complete" />
      </li>
      <li className="flex items-center justify-between gap-3">
        Deploy to staging
        <Status status="running" />
      </li>
      <li className="flex items-center justify-between gap-3">
        Approve release
        <Status status="awaiting-input" />
      </li>
    </ul>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/status
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/status-web
```

## Composition [#composition]

```text
Status
├── StatusIcon
└── StatusLabel
```

`Status` renders both parts when you pass no children; any children you pass replace them. `StatusIcon` draws the mark and is hidden from screen readers, and `StatusLabel` shows the label, or its own children.

## Usage [#usage]

### Status and Label [#status-and-label]

Set `status` as the work moves along: `pending`, `running`, `awaiting-input`, `complete`, `error` or `cancelled`. The label follows it: "Pending", "Running", "Needs input", "Complete", "Failed" or "Cancelled". Pass `label` for your own words, like "Deployed".

A new label can change the badge's width, so put it at the end of a row, where nothing comes after it. Its height stays the same for every status.

### Announcements [#announcements]

When the status changes to `awaiting-input`, `complete`, `error` or `cancelled`, the badge tells screen readers its label, politely. Other changes, and label changes while the status stays the same, are quiet. The badge takes no focus and has no keys.

### Motion [#motion]

The mark morphs from one status to the next. Under `prefers-reduced-motion`, or with `motion="reduced"`, it fades over 120 ms instead, and with `motion="none"` it changes at once.

## API Reference [#api-reference]

### StatusOptions

| Prop      | Type                                                                                 | Description                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status?` | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"` | The run status the badge shows. Default: `"pending"`                                                                                              |
| `label?`  | `string \| undefined`                                                                | The badge's text, announced when the status changes. Defaults to "Pending", "Running", "Needs input", "Complete", "Failed" or "Cancelled".        |
| `motion?` | `"auto" \| "none" \| "reduced"`                                                      | How the mark changes between statuses: `"auto"` follows `prefers-reduced-motion`, `"reduced"` fades and `"none"` swaps at once. Default: `"auto"` |

### Agent [#agent]

An agent connected with `createAgent` sees each badge as a `kind-status` and reads its `status`. It has no actions.

<Caption>
Runs in React and Web Components. On `<kind-status>`, `status`, `label` and `motion` are attributes of the same name, and the element fills in its mark and label when it has no children. It writes the label into an empty `<kind-status-label>`, and leaves text you wrote there alone.
</Caption>