---
title: Badge
description: Small status label
visibility: guest
draft: false
---

# Badge

A compact label for status, counts, or categorization. Badges are pill-shaped by default and come in six semantic intents.

## Live Sandbox

This is a hydrated playground for the component. Toggle "Live preview" on the block below to swap the static HTML render for a real Livewire instance — every prop in the component's sandbox schema becomes an editable form field inside the iframe, so you can try different prop combinations live without writing any local code.

:::preview{title="Sandbox" sandbox="badge" props='{"intent":"primary","size":"md","body":"Beta"}'}
<x-wirekit::badge intent="primary">Beta</x-wirekit::badge>
:::

## Basic Usage

:::preview{title="Variants"}
<x-wirekit::row gap="xs" :wrap="true">
    <x-wirekit::badge intent="primary">Primary</x-wirekit::badge>
    <x-wirekit::badge intent="success">Success</x-wirekit::badge>
    <x-wirekit::badge intent="warning">Warning</x-wirekit::badge>
    <x-wirekit::badge intent="danger">Danger</x-wirekit::badge>
    <x-wirekit::badge intent="info">Info</x-wirekit::badge>
    <x-wirekit::badge intent="neutral">Neutral</x-wirekit::badge>
</x-wirekit::row>
:::

## Sizes

:::preview{title="Sizes"}
<x-wirekit::badge size="sm">Small</x-wirekit::badge>
<x-wirekit::badge size="md">Medium</x-wirekit::badge>
<x-wirekit::badge size="lg">Large</x-wirekit::badge>
:::

## Surfaces

The `surface` prop changes how the intent color is applied. `soft` (default) is
the tinted chip; `solid` fills with the intent color and uses an on-color
foreground; `outline` is transparent with an intent-colored ring. All three read
the same semantic intent tokens, so they restyle automatically under any theme.

:::preview{title="Soft surface (default)"}
<x-wirekit::row gap="xs" :wrap="true">
    <x-wirekit::badge intent="primary">Primary</x-wirekit::badge>
    <x-wirekit::badge intent="success">Success</x-wirekit::badge>
    <x-wirekit::badge intent="warning">Warning</x-wirekit::badge>
    <x-wirekit::badge intent="danger">Danger</x-wirekit::badge>
    <x-wirekit::badge intent="neutral">Neutral</x-wirekit::badge>
</x-wirekit::row>
:::

:::preview{title="Solid surface"}
<x-wirekit::row gap="xs" :wrap="true">
    <x-wirekit::badge intent="primary" surface="solid">Primary</x-wirekit::badge>
    <x-wirekit::badge intent="success" surface="solid">Success</x-wirekit::badge>
    <x-wirekit::badge intent="warning" surface="solid">Warning</x-wirekit::badge>
    <x-wirekit::badge intent="danger" surface="solid">Danger</x-wirekit::badge>
    <x-wirekit::badge intent="neutral" surface="solid">Neutral</x-wirekit::badge>
</x-wirekit::row>
:::

:::preview{title="Outline surface"}
<x-wirekit::row gap="xs" :wrap="true">
    <x-wirekit::badge intent="primary" surface="outline">Primary</x-wirekit::badge>
    <x-wirekit::badge intent="success" surface="outline">Success</x-wirekit::badge>
    <x-wirekit::badge intent="warning" surface="outline">Warning</x-wirekit::badge>
    <x-wirekit::badge intent="danger" surface="outline">Danger</x-wirekit::badge>
    <x-wirekit::badge intent="neutral" surface="outline">Neutral</x-wirekit::badge>
</x-wirekit::row>
:::

## With Dot Indicator

Use the `dot` prop to add a small colored dot to the left of the label. Useful for status indicators.

:::preview{title="Status dots"}
<x-wirekit::badge :dot="true" intent="success">Online</x-wirekit::badge>
<x-wirekit::badge :dot="true" intent="warning">Away</x-wirekit::badge>
<x-wirekit::badge :dot="true" intent="danger">Offline</x-wirekit::badge>
<x-wirekit::badge :dot="true" intent="neutral">Idle</x-wirekit::badge>
:::

## With Icons

Badges accept any content, including icons:

:::preview{title="Badges with leading icons"}
<x-wirekit::badge intent="success">
    <x-wirekit::icon name="check" class="h-3 w-3" />
    Verified
</x-wirekit::badge>
<x-wirekit::badge intent="warning">
    <x-wirekit::icon name="warning" class="h-3 w-3" />
    Pending
</x-wirekit::badge>
<x-wirekit::badge intent="danger">
    <x-wirekit::icon name="close" class="h-3 w-3" />
    Rejected
</x-wirekit::badge>
<x-wirekit::badge intent="info">
    <x-wirekit::icon name="info" class="h-3 w-3" />
    Info
</x-wirekit::badge>
:::

## Width & Layout

Badges are inline elements that auto-size to their text content. They naturally flow within text or alongside other elements. By default a badge is a **single-line, fixed-height pill** — its text never wraps.

## Multi-line labels

For a long label in a narrow space (a taxonomy chip in a table cell), set `wrap`. In wrap mode the badge swaps its fixed height for a minimum height plus vertical padding, so the pill **grows with the wrapped text** instead of the second line spilling below the surface. Without `wrap`, forcing `white-space: normal` alone leaves the extra lines outside the pill.

:::preview{title="A wrapping badge grows to fit its label"}
<x-wirekit::badge intent="info" wrap style="max-width: 12rem">Religious founders &amp; spiritual teachers</x-wirekit::badge>
:::

## Tooltip & Leading Icon

`tooltip` surfaces a supplementary explanation through WireKit's own [Tooltip](/components/tooltip) component — it appears on hover, focus, touch, and keyboard, and is announced to screen readers via `aria-describedby` (the badge label stays the accessible name). `leadingIcon` renders a decorative status glyph before the label. Every badge also carries a subtle depth shadow so it reads less flat.

:::preview{title="Badge with tooltip + leading icon"}
<x-wirekit::row gap="sm" wrap>
    <x-wirekit::badge intent="success" leading-icon="check" tooltip="Deployed to production">Live</x-wirekit::badge>
    <x-wirekit::badge intent="warning" leading-icon="clock" tooltip="Awaiting review">Pending</x-wirekit::badge>
    <x-wirekit::badge intent="danger" leading-icon="x-circle" tooltip="Build failed">Failed</x-wirekit::badge>
</x-wirekit::row>
:::

## Trailing Icon & Dismissible

`trailingIcon` mirrors `leadingIcon` but renders after the label (handy for a
link arrow). `dismissible` adds a keyboard-operable close button that removes the
badge and dispatches a `wirekit:badge-dismissed` event — useful for removable
filter chips. Override the button's accessible name with `dismissLabel`.

:::preview{title="Trailing icon + dismissible chips"}
<x-wirekit::row gap="sm" wrap>
    <x-wirekit::badge intent="info" trailing-icon="arrow-right">Read more</x-wirekit::badge>
    <x-wirekit::badge intent="primary" surface="outline" dismissible dismiss-label="Remove Design filter">Design</x-wirekit::badge>
    <x-wirekit::badge intent="neutral" dismissible dismiss-label="Remove Engineering filter">Engineering</x-wirekit::badge>
</x-wirekit::row>
:::

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intent` | string | `'neutral'` | Semantic intent: `primary`, `accent`, `neutral`, `success`, `warning`, `danger`, `info` |
| `size` | string | `'md'` | `sm`, `md`, `lg` |
| `surface` | string | `'soft'` | `soft` (tinted chip), `solid` (filled + on-color text), or `outline` (transparent + ring) |
| `dot` | bool | `false` | Shows a small colored dot before the label |
| `tooltip` | string\|null | `null` | Supplementary explanation, surfaced through the WireKit [Tooltip](/components/tooltip) component (hover / focus / touch / keyboard) |
| `leadingIcon` | string\|null | `null` | Decorative status glyph rendered before the label (icon alias, e.g. `check` / `clock`) |
| `trailingIcon` | string\|null | `null` | Decorative glyph rendered after the label (icon alias, e.g. `arrow-right`) |
| `dismissible` | bool | `false` | Renders a keyboard-operable close button that removes the badge and dispatches `wirekit:badge-dismissed` |
| `dismissLabel` | string | `'Remove'` | Accessible name for the dismiss button |
| `wrap` | bool | `false` | Multi-line mode — a long label wraps and the pill grows (min-height + padding) instead of clipping the second line |
| `scope` | string\|null | `null` | Scoped personalization name |

## Accessibility

- Badges render as `<span>` elements — inline by default
- The dot indicator has `aria-hidden="true"` (decorative — its color is the only signal, which is already expressed via the text intent)
- For status badges that convey meaning beyond their color, ensure the text label describes the state clearly (e.g. "Online", "Error", "Expired")

## Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

## Pitfalls

- **Don't put interactive content inside a badge.** Badges are inline `<span>` elements — for clickable status pills wrap them with a `<x-wirekit::link>` or use `<x-wirekit::button size="sm" intent="..." />`.

## Design Tokens

Badges use tinted backgrounds via CSS `color-mix()` for a subtle, theme-aware look. All colors derive from semantic tokens:

| Intent | Background | Text | Border |
| --- | --- | --- | --- |
| `primary` | `--color-wk-accent` (12% mix) | `--color-wk-accent-content` | `--color-wk-accent` (25%) |
| `success` | `--color-wk-success` (12% mix) | `--color-wk-success-text` | `--color-wk-success` (25%) |
| `warning` | `--color-wk-warning` (12% mix) | `--color-wk-warning-text` | `--color-wk-warning` (25%) |
| `danger` | `--color-wk-danger` (12% mix) | `--color-wk-danger-text` | `--color-wk-danger` (25%) |
| `info` | `--color-wk-accent` (8% mix) | `--color-wk-accent-content` | `--color-wk-accent` (20%) |
| `neutral` | `--color-wk-bg-muted` | `--color-wk-text` | `--color-wk-border-subtle` |

All intents automatically adapt to light/dark mode via the underlying tokens.

## Customization

Override defaults without publishing views via `config/wirekit.php`:

```php
'components' => [
    'badge' => ['intent' => 'primary', 'size' => 'lg'],
],
```

Or merge custom classes inline:

```blade
<x-wirekit::badge class="uppercase tracking-wider">Beta</x-wirekit::badge>
```

## Usage & Conventions

> **Prop conventions** — this component uses one or more of the shared semantic prop names (`intent` / `variant` / `tone` / `surface`). See [Prop naming conventions](/extending/prop-naming-conventions) for the canonical vocabulary, alias matrix, and decision tree.

## Further Reading

- [MDN: `aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) — for icon-only badges
- [MDN: Semantic colors in design systems](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors)