Badge
Small inline label for counts, categories, and status indicators.
Scales with the parent font size via em units. Supports status
variants, optional icons, pill shape, and can render as a link
for navigable categorization.
Usage
When to use
- Counts next to navigation items (e.g. unread messages)
- Category or topic labels inline with content
- Status indicators (success, warning, error) attached to a related element
When not to use
- For interactive selection or removal - use
chipinstead - For standalone status messages - use
messageorannouncement - As the primary CTA - use
buttoninstead
Do
- Pair status color with a text label or icon
- Let badges inherit their size from the parent via
emunits - Provide screen-reader context for count badges (e.g. "3 unread")
Don't
- Rely on color alone to communicate meaning
- Nest interactive controls inside a badge
- Use badges for long-form text - keep them terse
API
Slots
| Slot | Required | Description |
|---|---|---|
content | Yes | Visible badge text. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
sr_text | string | - | Visually hidden text for screen readers (appended after visible content). |
url | string | - | When set, renders the badge as a link. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.info | Intent | - | Informational message. |
.warning | Intent | - | Warning or caution. |
.danger | Intent | - | Error, destructive, or critical. |
.success | Intent | - | Confirmation or completion. |
.solid | Fill | - | Filled surface; background and border rendered. |
.outline | Fill | - | Bordered surface; transparent background. |
.ghost | Fill | - | No surface; text or icon only. |
.xs | Size | - | Extra small. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.pill | Shape | - | Fully rounded ends. |
Examples
Default
Default badge.
Status
Grid of status variants: info, success, warning, error.
Pill
Pill-shape variant with fully rounded corners.
With icon
Badge with an icon before the text.
Linkable
Badge rendered as an <a> for navigable categorization.
Count
Count badge with screen-reader context (e.g. "3 unread").
Accessibility
- WCAG 2.2 AA
- Meaning must not be conveyed by color alone - include text or an icon with accessible name.
- Count badges must provide screen-reader context (e.g. "3 unread") via visually hidden text.
- Color contrast must meet AA for every variant.
- Linkable badges must have visible focus styles.
Related
- chip - interactive selectable / removable counterpart