Skip to main content

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 chip instead
  • For standalone status messages - use message or announcement
  • As the primary CTA - use button instead

Do

  • Pair status color with a text label or icon
  • Let badges inherit their size from the parent via em units
  • 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​

SlotRequiredDescription
contentYesVisible badge text.

Props​

PropTypeDefaultDescription
sr_textstring-Visually hidden text for screen readers (appended after visible content).
urlstring-When set, renders the badge as a link.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.infoIntent-Informational message.
.warningIntent-Warning or caution.
.dangerIntent-Error, destructive, or critical.
.successIntent-Confirmation or completion.
.solidFill-Filled surface; background and border rendered.
.outlineFill-Bordered surface; transparent background.
.ghostFill-No surface; text or icon only.
.xsSize-Extra small.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.pillShape-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.
  • chip - interactive selectable / removable counterpart