# Notification Badge

## Overview

A small overlay indicator that appears on top of another element (typically an icon button) to communicate an unread count or attention cue. Appears as a colored dot (attention) or a numbered badge (count).

---

## When to Use

- Notification bell icons in the header with unread count
- Navigation items with pending action counts
- Tab indicators with item counts

---

## Props

| Prop        | Type                                                                                         | Default         | Required | Description                                             |
| ----------- | -------------------------------------------------------------------------------------------- | --------------- | -------- | ------------------------------------------------------- |
| `count`     | `number`                                                                                     | `0`             | No       | Number to display                                       |
| `max`       | `number`                                                                                     | `99`            | No       | Maximum count to display (shows `{max}+` when exceeded) |
| `dot`       | `boolean`                                                                                    | `false`         | No       | Renders a dot indicator instead of a count badge        |
| `showZero`  | `boolean`                                                                                    | `false`         | No       | Show the badge even when count is 0                     |
| `variant`   | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'info' \| 'warning'` | `'destructive'` | No       | Color variant                                           |
| `className` | `string`                                                                                     | —               | No       | Additional classes                                      |

---

## Examples

### Notification Bell with Count

```tsx
import { NotificationBadge, Button } from 'xertica-ui/ui';
import { Bell } from 'lucide-react';

<NotificationBadge count={3} variant="destructive">
  <Button variant="ghost" size="icon" aria-label="Notifications">
    <Bell className="size-4" />
  </Button>
</NotificationBadge>;
```

### Dot Indicator

```tsx
import { Mail } from 'lucide-react';

<NotificationBadge dot variant="success">
  <Button variant="ghost" size="icon" aria-label="Messages">
    <Mail className="size-4" />
  </Button>
</NotificationBadge>;
```

### Status Variants

```tsx
<NotificationBadge count={5} variant="info">...</NotificationBadge>
<NotificationBadge count={2} variant="warning">...</NotificationBadge>
<NotificationBadge count={1} variant="success">...</NotificationBadge>
```

---

## AI Rules

- Always wrap the target element as a child — the badge positions itself automatically in the top-right corner.
- When count is `0`, prefer not rendering the badge at all rather than showing `0` (use `showZero` to override).
- Maximum display value defaults to `99` — showing `99+` instead of large numbers.
- For standalone status labels (not overlays), use `<Badge>` instead.

---

## Related Components

- [`Badge`](./badge.md) — For standalone inline status labels