Badges and chips

One compact label primitive for statuses, counts, tags, filters, and metadata.

Use badges for short, read-only metadata, including statuses, counts, tags, and filter labels. A badge should support nearby content, not replace a heading, button, or full status message.

Status badges

<layout-cluster gap="var(--space-sm)">
  <badge status="success">Ready</badge>
  <span data-badge="true" data-status="warning">Needs review</span>
  <span class="badge badge-error">Blocked</span>
  <badge status="info">Draft</badge>
  <badge status="primary">Featured</badge>
</layout-cluster>

<badge status="success">Ready</badge>
<span data-badge data-status="warning">Needs review</span>
<span class="badge badge-error">Blocked</span>
<badge status="info">Draft</badge>
<badge status="primary">Featured</badge>

Status colors are visual reinforcement. Keep the status word in the badge so meaning is not communicated by color alone.

Surface variants

<layout-cluster gap="var(--space-sm)" align="center">
  <badge variant="muted">Muted</badge>
  <span data-badge="true" data-variant="subtle">Subtle</span>
  <span class="badge badge-default">Default</span>
  <badge variant="overt">Overt</badge>
</layout-cluster>

<badge variant="muted">Muted</badge>
<span data-badge data-variant="subtle">Subtle</span>
<span class="badge badge-default">Default</span>
<badge variant="overt">Overt</badge>

Sizes

<layout-cluster gap="var(--space-sm)" align="center">
  <badge size="sm" variant="subtle">Small</badge>
  <badge size="md" variant="subtle">Medium</badge>
  <badge size="lg" variant="subtle">Large</badge>
</layout-cluster>

Tags and filter labels

“Badge” and “chip” describe the same visual primitive here. Prefer the badge API in new code; the old chip hosts remain aliases so existing markup keeps working.

<layout-cluster gap="var(--space-sm)">
  <span data-badge="true" variant="subtle">Design systems</span>
  <badge variant="default">CSS</badge>
  <span class="badge badge-muted">Archived</span>
  <chip variant="overt">Legacy chip host</chip>
</layout-cluster>

<span data-badge variant="subtle">Design systems</span>
<badge variant="default">CSS</badge>
<span class="badge badge-muted">Archived</span>

<!-- Compatibility alias; prefer a badge host in new code. -->
<chip variant="overt">Legacy chip host</chip>

Labels do not wrap by default, which keeps pills intact in clusters and dense UI. For unusually long content, add wrap, data-wrap, or .badge-wrap; first consider whether plain text is more appropriate.

For an interactive or removable filter, use a native button rather than adding behavior to a presentational label:

<button type="button" aria-label="Remove CSS filter">
  CSS <span aria-hidden="true">×</span>
</button>

Public API

Use <badge>, [data-badge], or .badge. When the badge is ordinary inline metadata, prefer semantic HTML such as <span data-badge>; the custom element remains available as a concise styling host. Legacy <chip>, [data-chip], and .chip hosts map to the same implementation.

• Sizes: sm, md, lg
• Surface variants: subtle, default, muted, overt
• Statuses: success, warning, error, info, primary, overt
• Wrapping: non-wrapping by default; opt in with wrap, data-wrap, or .badge-wrap

Common customization variables:

• --badge-background and --badge-color
• --badge-border-color and --badge-border-width
• --badge-background-*, --badge-color-*, and --badge-border-* for the muted, subtle, default, and overt roles
• --badge-radius
• --badge-padding-inline and --badge-padding-block
• --badge-gap

Practical patterns

<h3>
  Deployment
  <badge status="success">Live</badge>
</h3>

<button type="button">
  Notifications <badge variant="overt" aria-label="3 unread">3</badge>
</button>

When a numeric badge lacks nearby context, give it an accessible label. Badges are not interactive on their own; put one inside a real button or link when the surrounding control is interactive.

Use variant, data-variant, or a .badge-* variant class for appearance. Older role="subtle|default|muted|overt" markup remains visually compatible, but is deprecated because role is an accessibility attribute.