Skip to main content
WireKit
Copy for LLM

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.

Sandbox
Beta 
<x-wirekit::badge intent="primary">Beta</x-wirekit::badge>

Basic Usage

Variants
Primary Success Warning Danger Info Neutral 
<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

Sizes
Small Medium Large 
<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.

Soft surface (default)
Primary Success Warning Danger Neutral 
<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>
Solid surface
Primary Success Warning Danger Neutral 
<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>
Outline surface
Primary Success Warning Danger Neutral 
<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.

Status dots
Online Away Offline Idle 
<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:

Badges with leading icons
Verified Pending Rejected Info 
<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.

A wrapping badge grows to fit its label
Religious founders & spiritual teachers 
<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 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.

Badge with tooltip + leading icon
Live
Pending
Failed 
<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.

Trailing icon + dismissible chips
Read more Design Engineering 
<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 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:

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

Or merge custom classes inline:

<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 for the canonical vocabulary, alias matrix, and decision tree.

Further Reading

Was this page helpful?

Voting requires cookies or local storage. What we store