# Badge

> A small status label — for counts, tags, and state indicators.

URL: https://apogee.avaui.dev/docs/badge
Last updated: 2026-10-15

A small status label — for counts, tags, and state indicators.

Last updated October 15, 2026

```astro
<Badge color="primary" variant="solid">New</Badge>
<Badge color="critical" variant="solid">Error</Badge>
```

## Add

```sh
npx @ava-ui/apogee add badge
```

No component dependencies.

## Usage

```astro
---
import Badge from '@/components/apogee/Badge/Badge.astro'
---
<Badge color="primary" variant="solid">New</Badge>
```

## API

`@composable` — exposed to Content Editors in AVA. Any other native `<span>` attribute passes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `'primary' \| 'neutral' \| 'critical' \| 'positive' \| 'warning'` | `'neutral'` | The hue. |
| `variant` | `'solid' \| 'faded' \| 'outline'` | `'faded'` | The fill style. |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Height: 20 / 24 / 28px. |
| `rounded` | `boolean` | `false` | Fully round ends. |
| `highlighted` | `boolean` | `false` | Stronger fill for an active filter or selected state. |
| `truncate` | `boolean` | `false` | Clamps long labels (max 10rem) with an ellipsis. |
| `class` | `string` | — | Extra classes, appended last. |

Slots: `start` and `end` for a small icon.

## Variants × colors

Every `variant` for every `color`:

```astro
<Badge color="primary" variant="solid">Primary</Badge>
<Badge color="neutral" variant="solid">Neutral</Badge>
<Badge color="critical" variant="solid">Critical</Badge>
<Badge color="positive" variant="solid">Positive</Badge>
<Badge color="warning" variant="solid">Warning</Badge>

<Badge color="primary">Primary</Badge>
<Badge color="neutral">Neutral</Badge>
<Badge color="critical">Critical</Badge>
<Badge color="positive">Positive</Badge>
<Badge color="warning">Warning</Badge>

<Badge color="primary" variant="outline">Primary</Badge>
<Badge color="neutral" variant="outline">Neutral</Badge>
<Badge color="critical" variant="outline">Critical</Badge>
<Badge color="positive" variant="outline">Positive</Badge>
<Badge color="warning" variant="outline">Warning</Badge>
```

## Sizes

```astro
<Badge size="small">Small</Badge>
<Badge size="medium">Medium</Badge>
<Badge size="large">Large</Badge>
<Badge rounded>Rounded</Badge>
```

## Padding

The side that holds an icon pads less:

```astro
<Badge>Plain</Badge>
<Badge><Check slot="start" />Verified</Badge>
<Badge>Next<Check slot="end" /></Badge>
```

## States

```astro
<Badge color="primary">Filter</Badge>
<Badge color="primary" highlighted>Filter</Badge>
<Badge variant="solid" color="positive">Live</Badge>
<Badge variant="solid" color="positive" highlighted>Live</Badge>
<Badge truncate>A label far too long to fit in a small chip</Badge>
```

With no content a Badge renders as a dot indicator:

```astro
<Badge color="critical" />
<Badge color="positive" />
```

## BadgeContainer

Anchors a Badge on the corner of an avatar, icon or button.

```astro
<BadgeContainer>
<Avatar name="Ada Lovelace" />
<Badge slot="badge" color="critical" />
</BadgeContainer>
<BadgeContainer position="bottom-end" overlap>
<Avatar name="Alan Turing" />
<Badge slot="badge" variant="solid" color="positive" rounded size="small">3</Badge>
</BadgeContainer>
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `'top-end' \| 'bottom-end'` | `'top-end'` | Corner the badge sits on. |
| `overlap` | `boolean` | `false` | Pushes the badge outward for round elements. |
| `class` | `string` | — | Extra classes on the wrapper. |

Static — a `<span>`, not a control. No hover/focus/disabled states. If a badge needs to be clickable (a removable filter chip), wrap it in a `<button>` yourself; Badge doesn’t provide one.

## Examples

With a leading icon — like Button, the child SVG auto-sizes:

```astro
<Badge color="primary" variant="solid"><Check /> Verified</Badge>
```

As a count next to a label:

```astro
<span class="flex items-center gap-2">
  Inbox
  <Badge color="critical" variant="solid">12</Badge>
</span>
```

## Accessibility

Native semantics, no extra ARIA needed for a static label. If a badge’s count updates live (e.g. an unread counter), pass `aria-live="polite"` via passthrough so assistive tech picks up the change.

## Tokens

| Token | Used for |
| --- | --- |
| `--background-{hue}-faded` / `--foreground-{hue}` | `faded` variant, per `color` |
| `--background-{hue}` / `--on-{hue}` | `solid` variant |
| `--border-{hue}` / `--foreground-{hue}` | `outline` variant |

## Do / Don’t

-   **Do** keep badge text to one or two words, or a short number.
-   **Do** reserve `danger` for genuinely negative states (errors, overdue) — not just to draw attention.
-   **Don’t** use Badge as a button — it has no focus or press states.
-   **Don’t** wrap long sentences in a Badge; it doesn’t wrap gracefully and isn’t meant to hold prose.

## Content

-   Sentence case or a single number, no ending period. Prefer a status word (“Active”, “Beta”, “12”) over a phrase.

## Related

[

TagA chip for labels and categories. Optionally a link, optionally removable.

](https://apogee.avaui.dev/docs/tag)[

AvatarA user image, with an initials fallback derived from name.

](https://apogee.avaui.dev/docs/avatar)[

StatDisplays a labelled metric with an optional trend indicator. For dashboards and summary rows.

](https://apogee.avaui.dev/docs/stat)