# Badge (/docs/badge)

A compact label for statuses, categories, and counts.

## Install

```bash
npx shadcn@latest add https://4af.selfsimilar.dev/r/badge.json
```

## Usage

```tsx
import { Badge } from "@/components/ui/badge";

<Badge variant="solid" shape="pill">Approved</Badge>
<Badge status="loading">Syncing</Badge>
<Badge status="danger" icons={{ danger: <CircleX /> }}>Failed</Badge>
<Badge color="oklch(0.7 0.15 250 / 0.15)">Beta</Badge>
```

## API

**Main exports:** `Badge`, `BadgeIconsProvider`, types `BadgeStatus` and `BadgeIcons`

A label for statuses, categories, and counts, with an optional icon or dot. Label and glyph
changes animate through the shared `Morph` component.

The default size is `sm`. Boxed badges are 16px high with a 4px radius at `sm`, 20px with a 4px
radius at `md`, and 24px with a 6px radius at `lg`.

## Variants

| Variant | Treatment |
| --- | --- |
| `solid` (default) | A translucent status-coloured fill; text and icon in the same, stronger status colour. |
| `outline` | No fill and a grey outline; only the text and icon follow `status`. |
| `plain` | No background or outline. |

`shape="pill"` fully rounds `solid` and `outline` badges; `rounded` is the default and `plain`
ignores it.

| Prop | Description |
| --- | --- |
| `color` | Any CSS colour, replacing the `solid` fill. Used as given, so pass a translucent colour for the default wash look. Text and icon keep the `status` colour. Ignored by `plain` and `outline`. The badge carries `data-color` while it applies. |

```tsx
<Badge color="oklch(0.7 0.15 250 / 0.15)">Beta</Badge>
```

## Status icons

| Status | Default icon |
| --- | --- |
| `neutral` | `Circle` |
| `info` | `Info` |
| `success` | `Check` |
| `warning` | `AlertTriangle` |
| `danger` | `OctagonAlert` |
| `loading` | Shared loader (`loader`, then `LoaderProvider`, then `AsciiLoader`) |

| Prop / part | Description |
| --- | --- |
| `icon` | One glyph for this badge, whatever its status. `icon={null}` hides it. |
| `icons` | Per-status glyphs for this badge, e.g. `{ danger: <CircleX /> }`. Unnamed statuses fall through. |
| `loader` | The loading glyph for `status="loading"`. |
| `BadgeIconsProvider icons={…}` | Per-status glyphs for every badge in a subtree, portals included. Nested providers merge over outer ones. |

Precedence, most specific first: `icon`, `icons`, `loader` (loading only), `BadgeIconsProvider`,
the default. A `null` entry in `icons` or the provider hides the icon for that status. Glyphs are
sized to the badge (`size-2.5` / `size-3` / `size-3.5`) unless they set their own size.

```tsx
<BadgeIconsProvider icons={{ danger: <CircleX />, success: <CircleCheck /> }}>
  <App />
</BadgeIconsProvider>
```

## Layout animation

Badge animates its width when its content changes. In a list that filters or reorders, such as a
Command Palette or a table row, set `animateLayout={false}` on badges whose content doesn't
change. Otherwise the badge FLIP-animates its own position as the row moves, which slides it
within the row and adds layout cost.

```tsx
<Badge animateLayout={false}>Beta</Badge>
```