Source: https://monarchui.dev/components/badge/

Components · Data display

# Badge

Status and metadata labels in six tones.

@rookcom/monarch-react

Component

## Tones and variants

## Usage examples

The example at the top of the page is the only one for this component.

## Purpose

A short status or metadata label, such as a ticket state, a count or a version.

### Use when

- Showing the status of a row or record (`subtle`, the default).
- Showing a count (`solid`) or neutral metadata (`outline`).

### Avoid when

- The label is an action: use Button.
- The message needs a sentence of explanation: use Alert.

## Design principles

- Never the only way to convey meaning: the text carries the status, colour only reinforces it.
- Tone names the meaning (`success`, `danger`), not the colour.

## API reference

```tsx
import { Badge } from '@rookcom/monarch-react';
```

| Export | Kind | Rendering | Root class |
| --- | --- | --- | --- |
| `Badge` | component | server-safe | `.mn-badge` |

All native `<span>` attributes pass through.

Generated from the TypeScript declarations of `packages/react/src/components/data-display/badge`.

## Properties

### `Badge`

Short status or metadata label. Never the only way to convey meaning: keep the text.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `ReactNode` |  |
| `className` | `string` |  |
| `dot` | `boolean` | Leading status dot. |
| `id` | `string` |  |
| `size` | `"sm" \| "md"` |  |
| `tone` | `Tone` |  |
| `variant` | `"subtle" \| "solid" \| "outline"` | `subtle` (default) for status in tables, `solid` for counts, `outline` for metadata. |

## Variants

| Prop | Values | Description |
| --- | --- | --- |
| `tone` | `'neutral'``'accent'``'info'``'success'``'warning'``'danger'` | Semantic colour. Default `neutral`. Exposed as `data-tone`. |
| `variant` | `'subtle'``'solid'``'outline'` | `subtle` (default) for status in tables, `solid` for counts, `outline` for metadata. Exposed as `data-variant`. |
| `size` | `'sm'``'md'` | Default `md`. Exposed as `data-size`. |
| `dot` | `'true'``'false'` | Adds a leading status dot. |

## States

| State | Exposed as | Behaviour |
| --- | --- | --- |
| Static | – | Badge has no interactive states; it is a plain `<span>`. |

## Interaction behaviour

- None. Badge is not focusable and has no event handling of its own.

## Keyboard support

Not interactive, so there is no keyboard behaviour.

## Accessibility

Role

none (a plain span)

Accessible name

Its text content.

- The status dot is `aria-hidden`, so only the text is announced.
- Keep the text meaningful on its own; colour is never the only signal.

## Responsive behaviour

- No breakpoints: the badge sizes to its text at every width.

## Theme support

- Colours are semantic tone tokens, so light, dark and more-contrast themes apply automatically.
- `accent` follows the product accent; the other tones do not change per product.

## Do and don't

### Do

- Use `subtle` badges for status inside tables and lists.
- Keep labels to one or two words.

### Don't

- Do not rely on the tone colour alone to convey meaning.
- Do not make a badge clickable; wrap the action in a Button instead.

## Related components

- [StatusBadge](https://monarchui.dev/components/status-badge/): Planned: a badge driven by a typed status registry.
- [Alert](https://monarchui.dev/components/alert/): A message that needs a sentence, not a label.

## Dependencies

| Kind | Depends on |
| --- | --- |
| npm packages | None |
| Monarch components | None |

## Testing coverage

- Renders tone as `data-tone` and hides the dot from assistive technology.

| Check | Covered |
| --- | --- |
| Axe in jsdom | Yes |
| Server rendering | Yes |
| Browser suites | Visual baselines: /__gallery |

Tests: `packages/react/src/components/data-display/badge`

## All example code

### Tones and variants

```tsx
import { Badge } from '@rookcom/monarch-react';

{(['neutral', 'accent', 'info', 'success', 'warning', 'danger'] as const).map((t) => (
  <Badge key={t} tone={t} dot>
    {t}
  </Badge>
))}
<Badge tone="success" variant="solid">
  3
</Badge>
<Badge tone="info" variant="outline">
  Beta
</Badge>
<Badge size="sm">v0.1.0</Badge>
```