# Badge

> A short, non-interactive status or count label in six tones and three variants.

Category: Data display · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/badge

Use Badge to label status ("Deployed", "Pending") or counts. Tones are functional: success, warning, danger and info carry meaning, while neutral and inverse are for categorisation. Use Tag for removable keywords and Chip for selectable filters.

## Import

```tsx
import { Badge } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Badge } from '@bindshq/stance-react';

export function Basic() {
  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
      <Badge tone="success" dot>
        Deployed
      </Badge>
      <Badge tone="warning" dot>
        Pending
      </Badge>
      <Badge tone="danger" dot>
        Failed
      </Badge>
      <Badge>Draft</Badge>
    </div>
  );
}
```

### Tones and variants

```tsx
import { Badge } from '@bindshq/stance-react';

export function Tones() {
  const tones = ['neutral', 'info', 'success', 'warning', 'danger', 'inverse'] as const;
  return (
    <div style={{ display: 'grid', gap: 12 }}>
      {(['soft', 'solid', 'outline'] as const).map((v) => (
        <div key={v} style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
          {tones.map((t) => (
            <Badge key={t} tone={t} variant={v}>
              {t}
            </Badge>
          ))}
        </div>
      ))}
    </div>
  );
}
```

### Counts

```tsx
import { Badge } from '@bindshq/stance-react';

export function Counts() {
  return (
    <div style={{ display: 'flex', gap: 8 }}>
      <Badge count={3} tone="inverse" variant="solid" aria-label="3 unread notifications" />
      <Badge count={48} aria-label="48 users" />
      <Badge
        count={240}
        tone="danger"
        variant="solid"
        aria-label="More than 99 failed deliveries"
      />
    </div>
  );
}
```

### Sizes and dots

```tsx
import { Badge } from '@bindshq/stance-react';

export function Sizes() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
      <Badge size="sm" tone="info" dot>
        Beta
      </Badge>
      <Badge size="md" tone="info" dot>
        Beta
      </Badge>
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Badge | `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'inverse'` | `'neutral'` | Meaning conveyed by colour; always pair with text. |
| Badge | `variant` | `'soft' \| 'solid' \| 'outline'` | `'soft'` | Fill style. |
| Badge | `size` | `'sm' \| 'md'` | `'md'` | Height 18 or 22px. |
| Badge | `dot` | `boolean` | `false` | Leading status dot. |
| Badge | `count` | `number` | None | Numeric count when there are no children. |
| Badge | `max` | `number` | `99` | Counts above max show as "max+". |

## Accessibility

- Badges are static text. The tone is never the only signal; the label text carries the meaning.
- Give count-only badges context with aria-label, e.g. aria-label="12 unread notifications".
- Every tone and variant meets 4.5:1 text contrast in light, dark and high-contrast themes.

## Guidelines

**Do**

- Keep labels to one or two words.
- Use the same tone for the same status everywhere.

**Don’t**

- Make badges clickable; use Chip or Button.
- Rely on tone without text.

## Related

- https://stanceui.com/components/tag
- https://stanceui.com/components/chip