# Badge

**When to use:** Small count or status indicator — unread counts, notification dots, "new" markers. Use standalone, or wrap an icon/avatar/button to overlay the badge on one of its corners.

**Keywords:** pill

**Import:** `import { Badge, BadgeStyleType, BadgePosition, ThemeColor } from '@ahrowe/ui'`

**Styles:** `BadgeStyleType.Filled` (default) | `BadgeStyleType.Light` | `BadgeStyleType.Outlined`, in any `color`: a `ThemeColor` (default `Primary`) or any CSS colour, see [ThemeColor.md](ThemeColor.md). A `dot` is always solid.

**Position (when wrapping `children`):** `BadgePosition.TopRight` (default) | `BadgePosition.TopLeft` | `BadgePosition.BottomRight` | `BadgePosition.BottomLeft`. A badge over its `children` sits on the page colour, so `Light`, `Outlined` and a `Neutral` `Filled` look as they do on the page instead of letting the avatar or icon show through.

```tsx
import { Badge, BadgeStyleType, ThemeColor } from '@ahrowe/ui';
import { faBell } from '@fortawesome/free-solid-svg-icons';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';

// Standalone count
<Badge count={3} />

// Caps at `max` and shows "99+"
<Badge count={128} max={99} />

// Custom content instead of a count
<Badge content="NEW" />

// Plain dot, no text
<Badge dot color={ThemeColor.Error} />

// A status label
<Badge content="Paid" styleType={BadgeStyleType.Light} color={ThemeColor.Success} />

// Overlaying an icon
<Badge count={12} color={ThemeColor.Error}>
  <FontAwesomeIcon icon={faBell} />
</Badge>

// Hidden at 0 by default — opt in to show it
<Badge count={0} showZero>
  <FontAwesomeIcon icon={faBell} />
</Badge>
```

**Key props:**

| Prop | Type | Description |
|------|------|-------------|
| `count` | `number` | Number to display. Hidden when `0` unless `showZero` is set |
| `max` | `number` | Highest number shown before collapsing to `${max}+` (default `99`) |
| `content` | `ReactNode` | Custom content overriding the computed `count` text |
| `dot` | `boolean` | Render as a plain dot with no text |
| `showZero` | `boolean` | Show the badge when `count` is `0` |
| `styleType` | `BadgeStyleType` | `Filled` (default), `Light` or `Outlined`. Ignored by a `dot` |
| `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour |
| `position` | `BadgePosition` | Corner the badge attaches to when wrapping `children` (default `TopRight`) |
| `children` | `ReactNode` | Element the badge overlays. Omit to render the badge inline on its own |

**Slots:** `badge`

## Migration from colour styles

Before 0.43, `BadgeStyleType` was a colour, and `Primary` was filled while the others were a light
tint. Style and colour are now separate props, so every colour comes in every style. The old
members are gone and TypeScript points at each:

| Before | After |
|--------|-------|
| `styleType={BadgeStyleType.Primary}` | nothing: `Filled` `Primary` is the default |
| `styleType={BadgeStyleType.Default}` | `styleType={BadgeStyleType.Light} color={ThemeColor.Neutral}` |
| `styleType={BadgeStyleType.Success}` (and `Info`, `Warn`, `Error`) | `styleType={BadgeStyleType.Light} color={ThemeColor.Success}` |
| `dot styleType={BadgeStyleType.Error}` | `dot color={ThemeColor.Error}` |