Skip to main content

Badge

A non-interactive label used to highlight short, scannable information (a status, a category tag, or a count) in the smallest possible footprint.

When to use

  • Show a status, such as Succeeded, Failed, Pending, or Beta.
  • Tag a list item, a table row, or a card with a category.
  • Show a count, such as 12 new, with brief context.
  • Prefer Button or Anchor when the label must respond to a click. To give a link the look of a badge, see Polymorphism.
  • Prefer Kbd for a keyboard key or a shortcut.
  • Prefer MultiSelect for tags that the user picks and removes.

When not to use

  • For long-form text. Keep labels to one or two short words.
  • As the sole signal of meaning. Pair color with a label or icon so the distinction works without color (color blindness, monochrome themes).

Choosing a color

Prefer functional colors (success, warning, danger, info, accent, neutral) for status meaning so theming stays coherent. Reach for named hues only when the badge's semantic role isn't already covered.

Every color, with and without an icon:

Polymorphism

To render something else as a Badge, use the asChild prop to compose. This is useful when you want to splat the Badge styling onto a react-router Link.

API Reference

Badge

All props from span, plus:

PropTypeDefaultDescription
appearance"muted"Defines the visual style of the Badge. Currently only supports the muted variant.
asChild?booleanfalseUse the asChild prop to compose the Badge styling onto alternative element types or your own React components.
color?"accent" | "danger" | "important" | "info" | "neutral" | "success" | "warning" | "amber" | "blue" | "cyan" | "emerald" | "fuchsia" | "gray" | "green" | "indigo" | "lime" | "orange" | "pink" | "purple" | "red" | "rose" | "sky" | "teal" | "violet" | "yellow""neutral"The color variant of the Badge. Supports every named color, functional and palette.
icon?ReactNodeAn icon to render inside the badge. Sized to the badge. Decorative by default: it renders aria-hidden unless the SVG carries aria-label, aria-labelledby, role, or an explicit aria-hidden.

Data attributes

Data AttributeValueDescription
data-slot"badge"On the badge element. Stable styling hook that survives a className override or an asChild swap.
data-slot"badge-label"On the <span> wrapping children, beside the icon slot. display: contents, so every child stays a flex item of the badge and the gap still falls between them. Style a label by styling your own child, not this slot.