---
outline: deep
---

# Badge

Badges are used to draw attention and display statuses or counts. Commonly used in tabular data, lists, and navigation to indicate state or category.

**`<l-badge>`** — Custom Element (no Shadow DOM)

## Options

### Appearance

Add `appearance="filled"` (tinted background, no border), `appearance="filled-outlined"` (tinted background with border), or `appearance="accent"` (strong background, contrast text). Default is outlined (border, no background).

```html
<div class="flex flex-col gap-3">
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Outlined</span>
    <l-badge>Default</l-badge>
    <l-badge variant="info">Info</l-badge>
    <l-badge variant="success">Success</l-badge>
    <l-badge variant="warning">Warning</l-badge>
    <l-badge variant="danger">Danger</l-badge>
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Filled</span>
    <l-badge appearance="filled">Default</l-badge>
    <l-badge
      appearance="filled"
      variant="info"
      >Info</l-badge
    >
    <l-badge
      appearance="filled"
      variant="success"
      >Success</l-badge
    >
    <l-badge
      appearance="filled"
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      appearance="filled"
      variant="danger"
      >Danger</l-badge
    >
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Filled outlined</span>
    <l-badge appearance="filled-outlined">Default</l-badge>
    <l-badge
      appearance="filled-outlined"
      variant="info"
      >Info</l-badge
    >
    <l-badge
      appearance="filled-outlined"
      variant="success"
      >Success</l-badge
    >
    <l-badge
      appearance="filled-outlined"
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      appearance="filled-outlined"
      variant="danger"
      >Danger</l-badge
    >
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Accent</span>
    <l-badge appearance="accent">Default</l-badge>
    <l-badge
      appearance="accent"
      variant="info"
      >Info</l-badge
    >
    <l-badge
      appearance="accent"
      variant="success"
      >Success</l-badge
    >
    <l-badge
      appearance="accent"
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      appearance="accent"
      variant="danger"
      >Danger</l-badge
    >
  </div>
</div>
```

### Pill

Add the `pill` attribute for a fully rounded shape.

```html
<div class="flex flex-col gap-3">
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Outlined</span>
    <l-badge pill>Default</l-badge>
    <l-badge
      pill
      variant="info"
      >Info</l-badge
    >
    <l-badge
      pill
      variant="success"
      >Success</l-badge
    >
    <l-badge
      pill
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      pill
      variant="danger"
      >Danger</l-badge
    >
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Filled</span>
    <l-badge
      pill
      appearance="filled"
      >Default</l-badge
    >
    <l-badge
      pill
      appearance="filled"
      variant="info"
      >Info</l-badge
    >
    <l-badge
      pill
      appearance="filled"
      variant="success"
      >Success</l-badge
    >
    <l-badge
      pill
      appearance="filled"
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      pill
      appearance="filled"
      variant="danger"
      >Danger</l-badge
    >
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Filled outlined</span>
    <l-badge
      pill
      appearance="filled-outlined"
      >Default</l-badge
    >
    <l-badge
      pill
      appearance="filled-outlined"
      variant="info"
      >Info</l-badge
    >
    <l-badge
      pill
      appearance="filled-outlined"
      variant="success"
      >Success</l-badge
    >
    <l-badge
      pill
      appearance="filled-outlined"
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      pill
      appearance="filled-outlined"
      variant="danger"
      >Danger</l-badge
    >
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="text-sm text-tertiary w-28">Accent</span>
    <l-badge
      pill
      appearance="accent"
      >Default</l-badge
    >
    <l-badge
      pill
      appearance="accent"
      variant="info"
      >Info</l-badge
    >
    <l-badge
      pill
      appearance="accent"
      variant="success"
      >Success</l-badge
    >
    <l-badge
      pill
      appearance="accent"
      variant="warning"
      >Warning</l-badge
    >
    <l-badge
      pill
      appearance="accent"
      variant="danger"
      >Danger</l-badge
    >
  </div>
</div>
```

### Sizes

Add `size="sm"` or `size="lg"`. Default is md.

```html
<l-badge size="sm">Small</l-badge>
<l-badge>Medium</l-badge>
<l-badge size="lg">Large</l-badge>
```

### Variants

Add `variant="info"`, `variant="success"`, `variant="warning"`, or `variant="danger"`. Default is neutral.

```html
<l-badge>Neutral</l-badge>
<l-badge variant="info">Info</l-badge>
<l-badge variant="success">Success</l-badge>
<l-badge variant="warning">Warning</l-badge>
<l-badge variant="danger">Danger</l-badge>
```

## Accessibility

### Criteria

- **Color contrast** — Text and background meet minimum contrast ratio across all appearances and variants
- **Non-text contrast** — Badge borders meet non-text contrast minimum against adjacent surfaces
- **Not color alone** — Do not rely on badge color alone to convey status — always include a text label

### Rules

- Always include visible text inside the badge — do not use color alone to convey meaning
- When a badge conveys dynamic status, wrap it in a `role="status"` container so screen readers announce changes

## API reference

### Importing

```js
import 'luxen-ui/badge';
```

```css
@import 'luxen-ui/css/badge';
```

### Attributes & Properties

- **variant**: `BadgeVariant | undefined` — Style variant: `info`, `success`, `warning`, `danger`, or `neutral` (default)
- **pill**: `boolean` (default: `false`) — Display as pill shape
- **size**: `BadgeSize | undefined` — Badge size: `sm`, `lg`. Default is md.
- **appearance**: `BadgeAppearance | undefined` — Visual appearance: `filled`, `filled-outlined`, `accent`. Default is outlined.