# Status

> The square status pixel — a presence light, an attention dot or a status color beside a word — and the status chips, agent tag and runtime chip built with it.

Source: https://raft-design.botiverse.build/components/status. Generated from the current release; where it differs from what you remember, this page is right.

Status is the square pixel of a status color. On its own it is a presence light or an attention dot; beside a word it is a status chip, a soft tint with a pixel and a word that says where something is or how an agent is. Task status chips are `TaskStatusBadge` ([Tasks](https://raft-design.botiverse.build/components/tasks.md)); this doc covers the pixel, the chips for agent states, and the two small chips that go with an agent's name: the `agent` tag and the runtime chip.

```tsx
import { Status } from "@botiverse/raft-ui";

export function StatusContent() {
  return <Status />;
}
```

## When to use

| Situation                                                                           | Use                                                               |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Where a task is: on a card, in properties, in details                               | `TaskStatusBadge` ([Tasks](https://raft-design.botiverse.build/components/tasks.md))                    |
| A task under a message                                                              | The task marker, `TaskChip` ([Tasks](https://raft-design.botiverse.build/components/tasks.md))          |
| How an agent or a person is, on its avatar                                          | The presence light, `AvatarBadge` ([Avatar](https://raft-design.botiverse.build/components/avatar.md)) |
| How an agent is, written out: a profile card, properties                            | An agent state chip                                               |
| A status color beside a word: a group heading, a navigation subtitle, an event line | Status                                                            |
| Something waits, on an icon with no room for a number                               | The attention dot: Status with `variant="accent"`                 |
| A count                                                                             | [Badge](https://raft-design.botiverse.build/components/badge.md)                                        |
| This is an agent                                                                    | The `agent` tag                                                   |
| What an agent runs on                                                               | The runtime chip                                                  |

## Anatomy

- `Status`: the pixel, with an ink edge. `presence` draws one of the five presence lights; `variant` draws a color role. `size` sets the pixel.

## Sizes

- **A status light beside text has one size, 9px** (`md`, the default) with a 1.5px ink edge: in a toast, a banner, a panel notice, a badge, a panel header, a sidebar row, a list row. Don't pass a size there. 9px is 6px of color, the least that tells green from yellow from orange, plus two 1.5px ink edges, and about the cap height of the 12px to 14px text beside it.
- **A light on an avatar follows the avatar**, not the text: `AvatarBadge` sizes it from 6px to 20px with the avatar ([Avatar](https://raft-design.botiverse.build/components/avatar.md)).
- When the light leads a line of text it is centered on the first line ([A mark that leads text](https://raft-design.botiverse.build/foundations/alignment.md#a-mark-that-leads-text)). Banner, PanelNotice, ToastIcon, Badge and PanelActivity place a `Status` in them this way and hold it at 9px whatever size it was given; elsewhere, give it `className="lead-dot"`.
- `xs`, `sm` and `lg` (6px, 8px and 11px) are not for a light beside text.

## Variants

### Presence lights

| `presence` | Word           |
| ---------- | -------------- |
| `online`   | Online         |
| `busy`     | Working        |
| `error`    | Error          |
| `offline`  | Offline        |
| `external` | External agent |

Their colors, and the five task status colors, are in [Color](https://raft-design.botiverse.build/foundations/color.md#statuses).

### Agent state chips

An agent state chip is a soft [Badge](https://raft-design.botiverse.build/components/badge.md) holding a Status with its `presence` and the word from the table above. The tint is the soft step of the light's color: `brand-soft` for Working, and the `*-soft` tint of the same family for the others ([Soft tints](https://raft-design.botiverse.build/foundations/color.md#soft-tints)).

### Agent tag

The `agent` tag follows an agent's name and holds the word `agent`. It is an outline [Badge](https://raft-design.botiverse.build/components/badge.md): Space Mono, `foreground-muted`, with a hairline border. With a `users` icon in place of the word, the same tag shows a member count.

### Runtime chip

The runtime chip names what an agent runs on: Claude Code, Codex. It is Space Mono in ink on `info-soft`, with a `cpu` icon. raft-ui has no part for it yet.

## Content

- Pair every status color with a word. Write the word in Title Case: In Progress, Working.
- Set IDs inside a chip in Space Mono: `#25`.

## Accessibility

Status renders a `<span>` and wraps no Base UI primitive.

- Hide a pixel from assistive technology when its word is next to it (`aria-hidden`).
- Give a pixel with no word next to it, such as an attention dot on a tab or a rail item, `role="img"` and an `aria-label` that says what it means.

## Rules

- Keep saturated color to the size of the pixel. On a chip the rest is a soft tint, a highlight without a border: a screen can hold a dozen chips.
- Make every chip 22px high with `radius-chip`, so chips line up in a row; Badge and TaskChip already do.
- Put a new state into one of the five task statuses or the five presence lights; don't invent a color. "Stuck" is an agent error. "Needs you" is an attention dot and an action button, not a status ([Tasks](https://raft-design.botiverse.build/patterns/tasks.md#rules)).
- Don't set a custom `--status-color`: every status color has a fixed meaning.
- Never animate a status: a working agent is a still light ([Motion](https://raft-design.botiverse.build/foundations/motion.md)).

## API

### Status

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `presence` | `"online" \| "busy" \| "error" \| "offline" \| "external"` |  | A status light (online, busy, error, offline, external): a fixed meaning that needs its word nearby, or an aria-label. It takes the place of `variant`'s colour. |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` |  |
| `variant` | `"primary" \| "accent" \| "warning" \| "danger" \| "default" \| "information" \| "muted" \| "success"` | `"default"` |  |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

## Changes

- 0.20.1 (Added): **`lead-icon`** and **`lead-dot`** utilities: center an icon (`lead-icon`) or a `Status` light (`lead-dot`) you place yourself on the first line of the text beside it.
- 0.6.1 (Added): `Status` and `AvatarBadge` take `presence` (`online` / `busy` / `error` / `offline` / `external`), from one shared colour map (type `Presence`).
- 0.6.0 (Breaking Changes): **Props that no longer change anything are removed:** `Badge` `uppercase`; `Checkbox` `size`, `variant`, `color`; `Status` `pulse`, `attention` (status never animates); `Switch` / `SwitchThumb` `size`; `SidebarItem` `variant`; `SidebarItemCount` / `SidebarItemIndicator` `variant` and `appearance` (the count is always the pink sticker, the indicator the yellow @); `NotificationCenterActionButton` `variant`; `DrawerContent` `width` (one-go forms use the wide `Dialog`); `AppRailItemIndicator` `attention`; `AppRailItemAttention` `children`; `Steps` `size`, `track`, `renderIndicator`, `renderTraveler`; `FilePreviewBadge` `type`, `color`. Remove them at call sites.
- 0.0.21 (Added): Added `LiveAgentActivityBar` compound parts (`Row`, `Avatar`, `Status`, `Content`, `Text`) for composable live agent activity status.