Default
Neutral
Info
Ready
Needs review
Failed
Experimental
Small
Default
Large
}
variant="outline"
>
Badge docs
);
}
```
## Overview [#overview]
Use a badge to display a short status, count, category, or piece of metadata where people scan rather than read: table rows, list items, card headers, filter chips. Badges annotate other content. They are not containers for sentences, and they are not actions — when something needs to be clicked, render the badge as a real link or button so it behaves like one. See [Links and interactivity](#links-and-interactivity).
## Anatomy [#anatomy]
A badge is a small inline container with text and an optional leading icon. It renders a `span` by default, so it participates in a sentence or row without breaking line flow. Labels stay on one line by design; the component never wraps them.
## Variants [#variants]
Choose the variant by meaning, then by emphasis. `outline` and `secondary` are neutral; `success`, `warning`, `info`, `error`, and `destructive` map to states people already know from elsewhere in the product. Use one status vocabulary across your app: if `Failed` is `error` in one table, it should not be `destructive` in another.
Honest caveat about the API surface: several variants are visual aliases of each other. `info`, `accent`, and `default` share identical styles, as do `error`, `danger`, and `destructive`, and `neutral` matches `secondary`. Prefer the semantic names (`error`, not `danger`) so intent survives future restyling.
## Sizes [#sizes]
Sizes are `sm` (18 px tall, micro type), `default` (22 px), and `lg` (32 px). Use `sm` inside dense table cells and meta lines, `default` almost everywhere, and `lg` sparingly for hero-level labels. Icon size scales with the badge automatically.
## Links and interactivity [#links-and-interactivity]
By default a badge is static decoration with no keyboard presence — nothing to focus, nothing to announce beyond its text. That is correct for statuses. To make one navigable, pass Base UI's `render` prop with a real `Link`; the badge keeps its look while gaining link semantics, a visible `focus-visible` ring, and an expanded touch target of at least 44 × 44 px on coarse pointers.
## Accessibility [#accessibility]
A badge is announced as part of the surrounding text — there is no "badge" role. Write labels that make sense spoken aloud in context: `Failed` reads naturally after a row's other content; a bare colored dot reads as nothing at all. Never encode meaning in the variant color alone; pair color with text, and add an icon (`aria-hidden`) when you want a second non-color cue.
Mark decorative icons `aria-hidden="true"` so screen readers don't announce "check" before "Ready". The component disables pointer events on child SVGs but does not hide them from assistive technology for you.
Labels use theme tokens and adapt to dark mode automatically. The `gradient` variant is the exception — it uses fixed hardcoded colors — so verify its legibility in both themes before adopting it. Because labels never wrap, very long text will overflow its container rather than break the layout; shorten the label or truncate deliberately.
Badges have no loading, disabled, or validation states — they are static metadata. If a value is still loading, show a skeleton or spinner in its place instead of a placeholder badge.
## Installation [#installation]