# xpl-badge

`xpl-badge` is a small, non-interactive status indicator used to communicate counts, states, or supplementary information next to another element. Badges are **never clickable** – use a button or link if you need interaction.

Badges support multiple **variants** (colors), **sizes**, **shapes**, and **dot styles**, so they can be used both as pill labels and as compact status / notification indicators.

## Usage

```html
<xpl-badge variant="green">Active</xpl-badge>
<xpl-badge variant="yellow">Pending</xpl-badge>
<xpl-badge variant="red">Error</xpl-badge>
<xpl-badge variant="gray" size="small">Draft</xpl-badge>
```

Attach badges close to the item they describe (a label, row, chip, or control). Prefer **short labels** (often one or two words) for readability.

### Label text and overflow

Slot content is rendered inside an internal `.xpl-badge__label` wrapper (you do not add this in your markup). Labels are **single-line**: text does not wrap to multiple lines. When horizontal space is tight (for example a narrow column or flex layout), overflowing text **truncates with an ellipsis** (`…`). The host respects the parent width (`max-width: 100%`). If truncation makes a label hard to read, shorten the copy or widen the layout; use a tooltip or similar only if your product needs the full string on hover.

## Sizes & shapes

- **size**
  - `default` (default): `24px` tall pill, used for most cases.
  - `small`: `20px` tall, more compact for dense UIs or table rows.
- **shape**
  - `rounded` (default): full pill with fully rounded ends.
  - `boxy`: rounded corners but not a full pill; better for more neutral / data-heavy contexts.

```html
<xpl-badge size="default" shape="rounded">Default pill</xpl-badge>
<xpl-badge size="small" shape="boxy">Small boxy</xpl-badge>
```

## Dots and dot-only badges

### Dot badge (pill with leading dot)

Set `dot` to add a colored dot before the text, inside the pill:

```html
<xpl-badge variant="green" dot>Online</xpl-badge>
<xpl-badge variant="yellow" dot>Syncing</xpl-badge>
<xpl-badge variant="red" dot>Error</xpl-badge>
```

### Dot-only badge (compact status / count)

> [!IMPORTANT]
> Dot-only badges are meant to be used with **numeric values** (or very short strings). For longer text labels, use the standard badge (without `dot-only`).

- When overlaying another element with a background color, use the `bordered` property so the badge separates clearly from what is behind it.

Set `dot-only` when you want a badge built around the dot:

- With **no children**: renders a small circular status dot.
- With **children**: renders a compact pill with text or a number inside (for example an unread count).
- **Notification-style counts** are often appended to a label or another component. Dot-only label text follows the same **single-line truncation** rules as standard badges when space is limited.
- Use **`bordered`** to toggle a ring around the dot badge for separation from an avatar or similar surface.

```html
<!-- Status dot only -->
<xpl-badge variant="green" dot-only></xpl-badge>

<!-- Dot with count / text -->
<xpl-badge variant="red" dot-only>3</xpl-badge>
<xpl-badge variant="blue" dot-only>99+</xpl-badge>
```

## Variants

Use variants to communicate state or category. Preferred values for `variant`:

- `purple` (default)
- `green`
- `yellow`
- `orange`
- `gray`
- `red`
- `blue`

The legacy semantic names `success`, `warning`, `inactive`, and `error` are still accepted and map to `green`, `yellow`, `gray`, and `red` respectively. Prefer the color names for new code.

```html
<xpl-badge variant="purple">Default</xpl-badge>
<xpl-badge variant="orange" dot>In progress</xpl-badge>
<xpl-badge variant="blue" dot-only>12</xpl-badge>
```

- Each dot has **stronger solid color** for dot-only badges, with dark-mode adjustments handled by CSS.

- Each variant uses Apollo Foundation badge tokens (`--xpl-background-badge-`*, `--xpl-border-badge-*`, `--xpl-icon-badge-*`, `--xpl-text-badge-*`) that auto-switch between light and dark modes. Dot-only badges use the corresponding `--xpl-icon-badge-*` accent color for their solid fill.

### Design Tokens

Tokens used by this component from `@xplortech/apollo-foundation`.

**Color**
- `--xpl-background-badge-{default,green,yellow,grey,blue,red}` — variant backgrounds
- `--xpl-border-badge-{purple,green,yellow,grey,blue,red}` — variant borders
- `--xpl-text-badge-{default,green,yellow,gray,blue,red}` — variant text colors
- `--xpl-icon-badge-{default,green,yellow,grey,blue,red}` — dot / dot-only fill
- `--xpl-text-inverse` — dot-only text (green, blue, red)
- `--xpl-text-strong` — orange variant text
- `--xpl-border-inverse` — dot-only bordered ring
- `--xpl-color-transparent-0` — dot-only / orange transparent border
- `--xpl-color-neutral-1100` — dot-only text on yellow, gray, orange
- `--xpl-background-surface-transparent-0` — orange background (dark mode)
- `--xpl-background-accent-brand` — orange dot/dot-only fill (tech debt)
- `--xpl-color-orange-{100,300}` — orange variant primitives (tech debt)

**Spacing**
- `--xpl-space-{2,4,8,12}` — padding variants

**Sizing**
- `--xpl-size-{150,125,050}` — height / dot sizes
- `0.875rem` literal — dot-only badge height/min-width (no 14px Foundation token; tech debt)

**Typography**
- `--xpl-font-family-default` — font family
- Default badge extends `.xpl-text-title-5` (Figma `Title/5`); small badge extends `.xpl-text-callout-bold` (Figma `Callout/Bold`)
- `0.5rem` literal — dot-only (number) badge font-size/line-height (no 8px Foundation token or typography level; tech debt)

**Border**
- `--xpl-border-small` — border width (1px)
- `--xpl-border-radius-{full,small}` — shape variants

<!-- Auto Generated Below -->


## Properties

| Property   | Attribute  | Description                                                                                                                                                                                                                                                                                            | Type                                                                                                                          | Default     |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `bordered` | `bordered` | Whether badge shows a bordered ring                                                                                                                                                                                                                                                                    | `boolean`                                                                                                                     | `false`     |
| `dot`      | `dot`      | Whether badge shows a dot icon before the text (inside the pill)                                                                                                                                                                                                                                       | `boolean`                                                                                                                     | `undefined` |
| `dotOnly`  | `dot-only` | When true, render a compact badge built around the dot. - With no children: just a dot (status/dot badge) - With children: a small dot badge with the text/number inside                                                                                                                               | `boolean`                                                                                                                     | `false`     |
| `shape`    | `shape`    | Badge shape rounded (pill) boxy (rounded corners)                                                                                                                                                                                                                                                      | `"boxy" \| "rounded"`                                                                                                         | `'rounded'` |
| `size`     | `size`     | Badge size default \| small                                                                                                                                                                                                                                                                            | `"default" \| "small"`                                                                                                        | `'default'` |
| `variant`  | `variant`  | Badge variant (color).  Preferred values: `purple`, `green`, `yellow`, `orange`, `gray`, `red`, `blue`.  The legacy semantic names `success`, `warning`, `inactive`, and `error` are still accepted and map to `green`, `yellow`, `gray`, and `red` respectively. Prefer the color names for new code. | `"blue" \| "error" \| "gray" \| "green" \| "inactive" \| "orange" \| "purple" \| "red" \| "success" \| "warning" \| "yellow"` | `'purple'`  |


## Dependencies

### Used by

 - [xpl-avatar](../xpl-avatar)
 - [xpl-list-item](../xpl-list/xpl-list-item)

### Graph
```mermaid
graph TD;
  xpl-avatar --> xpl-badge
  xpl-list-item --> xpl-badge
  style xpl-badge fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*