# Badge

## Overview

A compact, inline label used to communicate status, category, or count. Badges are always non-interactive by default — they display information, not trigger actions.

---

## When to Use

- Status indicators: "Active", "Inactive", "Pending", "Error"
- Category tags in lists and tables
- Count indicators (notifications, pending items)
- Feature flags or role labels

## When NOT to Use

- For clickable filters — use `Toggle` or `Button` instead.
- For destructive inline actions — use a `Button variant="destructive"`.

---

## Variants

| Variant       | Usage                                     |
| ------------- | ----------------------------------------- |
| `default`     | Filled primary color — main labels        |
| `secondary`   | Muted fill — secondary or neutral labels  |
| `outline`     | Bordered, transparent — subtle status     |
| `destructive` | Red — error or danger status              |
| `success`     | Soft green — positive or completed status |
| `info`        | Soft blue — informational status          |
| `warning`     | Soft amber — caution or pending status    |

---

## Props

| Prop        | Type                                                                                         | Default     | Required | Description                  |
| ----------- | -------------------------------------------------------------------------------------------- | ----------- | -------- | ---------------------------- |
| `variant`   | `'default' \| 'secondary' \| 'outline' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'` | No       | Visual style                 |
| `asChild`   | `boolean`                                                                                    | `false`     | No       | Renders as the child element |
| `className` | `string`                                                                                     | —           | No       | Additional CSS classes       |

---

## Examples

```tsx
import { Badge } from 'xertica-ui/ui';

<Badge>Active</Badge>
<Badge variant="secondary">Draft</Badge>
<Badge variant="outline">Pending</Badge>
<Badge variant="destructive">Error</Badge>
<Badge variant="success">Completed</Badge>
<Badge variant="info">Info</Badge>
<Badge variant="warning">Caution</Badge>
```

### In Table Cells

```tsx
<TableCell>
  <Badge variant="success">Active</Badge>
</TableCell>
```

---

## AI Rules

- Status labels in tables and lists must ALWAYS use `<Badge>` — never plain text or colored `<span>`.
- Use semantic variants to convey meaning: `success` for completed/positive, `info` for informational, `warning` for caution, `destructive` for errors.
- Never invent a custom variant by styling a badge with raw colors. Use only the 7 documented variants.
- When you need a custom color label (e.g., brand-specific), apply `className` with semantic token classes: `className="bg-primary/10 text-primary border-primary/20"`.

---

## Related Components

- [`Button`](./button.md) — When the label needs to be clickable
- [`NotificationBadge`](./notification-badge.md) — For overlay dot/count indicators on icons
- [`Table`](./table.md) — Common context for Badge usage