Badge
A compact label for status, counts, and categories. Single-element like Button; status variants are soft tints derived from semantic tokens, so they re-theme everywhere.
Try it yourself. This one is live, and its code is right below.
Installation#
Usage#
import { Badge } from "@/components/ui/badge"
export function Example() {
return <Badge>New</Badge>
}Anatomy#
import { Badge, BadgeAvatar, BadgeCount, BadgeIcon, BadgeNumber, BadgeProgress, BadgeReveal, BadgeText } from "@/components/ui/badge"
<BadgeReveal>
<Badge>
<BadgeAvatar />
<BadgeIcon />
<BadgeProgress />
<BadgeText />
<BadgeCount>
<BadgeNumber />
</BadgeCount>
</Badge>
</BadgeReveal>Playground#
The whole control set is derived from the component’s recipe: change a tone or add a size and this follows on its own. Note that dismissal isn’t a flag but a handler, so the trailing button exists exactly when onRemove does.
The tone. Soft fills for status, solid for emphasis.
Fully rounded instead of the control radius.
The house default for a status badge.
Adds a trailing dismiss button via onRemove.
<Badge>In review</Badge>Variants#
Status#
Soft status variants pair a tinted background (the status hue at /10) with a darker text counterpart and no border, so the fill carries the color while the label stays legible. Both derive from one semantic token (--success, --warning, --info), so they re-theme across all four themes.
Categorical#
Four extra hues for labeling categories, feature flags, and tags. All follow the same soft-tint pattern and re-theme across all four themes.
With dot#
The dot prop adds a leading status dot in the variant color - ideal for presence and at-a-glance state. The background is stripped so only the dot carries the color.
Toggling the dot#
Drive dot from state and the change animates: the dot grows in and pushes the label over, the tint gives way to the hairline, and the label settles on foreground. Turning it off plays the same thing in reverse, back to the tinted badge. A badge that never passes dot renders no dot at all.
Custom color#
When the color arrives with the data (a dispatch call code with its category hex, a team, a label a user picked), pass it as color. The variant still picks the treatment: any page-ground tone gives the soft tint, with the label pulled toward the theme's foreground so a pale yellow still reads; primary (or secondary) gives a solid fill whose ink is chosen from the color itself, near-black on a light fill and white on a dark one; outline draws the hairline in the color. With dot the dot takes it.
The ink is read from hex (#rgb, #rrggbb, with or without alpha) and rgb(); any other form (a named color, hsl(), a var()) paints fine but gets white ink, so prefer hex for solid badges. The same choice is exported as readableInk(color), returning "dark" or "light", for your own surfaces.
Appearance#
variant picks the tone, appearance picks how it is painted. soft, the default, is a tint, surface adds a hairline in the tone's ink, solid fills it, and modern is a neutral surface where only the leading icon or dot carries the tone. Each tone carries its own ink and solid per theme, so light and cream read as crisp as dark.
Live#
pulse turns the dot on and gives it a slow echo, for something that is happening right now. Keep it to one per view. It holds still under reduced motion.
Animated#
Four client parts give the badge motion that carries meaning. Each one holds still under reduced motion.
State change
BadgeText rolls to its new string and eases the width to fit; BadgeIcon grows the new glyph in whenever swap changes. The tint crosses to the new tone on its own.
Rolling count
BadgeNumber turns each digit like a drum, up when the value grows and down when it shrinks; only the digits that change move.
Working
sweep passes the ink band through the label for open-ended work; BadgeProgress fills a ring when there is a number.
Enter and leave
BadgeReveal opens and closes the badge's slot in a row, so neighbours slide instead of jumping.
Sizes#
Pill#
Set pill for fully rounded edges - pairs well with dot and icon badges.
With icon#
Avatar and flag#
BadgeAvatar and Flag sit first and size to the badge, with the start padding tightened so the picture keeps an even margin.
Count#
BadgeCount nests a number at the end, tinted from the badge's own ink so it stays legible on every tone.
Dismissible#
Pass onRemove to render a trailing dismiss button. Give each a descriptive removeLabel for screen readers. For filters people toggle and clear, reach for Chip: it is the interactive sibling, with the same heights and tones.
As child#
Use asChild to render the badge styles on another element, such as a link. As a link it gains a hover fill, a focus ring, and a trailing arrow that nudges forward.
API reference#
Badge
A single <span> that labels a status, count or category. Forwards all native <span> props; accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "primary" | "secondary" | "outline" | "success" | "warning" | "info" | "destructive" | "purple" | "pink" | "teal" | "orange" | "overlay" | "overlayLight" | "default" | The fill: neutral, solid, outline, a soft status tint, a categorical hue, or a dark or light glass for media. |
| appearance | "soft" | "surface" | "solid" | "modern" | "soft" | How the tone is painted: a tint (the default), a tint with a hairline in the tone's ink, a solid fill (white ink, dark on amber and on dark themes), or a neutral surface where only the leading icon or dot takes the tone. |
| size | "sm" | "md" | "lg" | "md" | Fixed heights of 20, 24 and 28px, matching Chip xs, sm and the step above. Sets padding, type, corner and icon size. |
| pill | boolean | false | Fully rounded ends. |
| dot | boolean | - | A leading dot in the variant's tone; the fill gives way to a hairline. Passing a boolean (even false) keeps the slot mounted, so flipping it animates. |
| pulse | boolean | - | Turns the dot on with a slow echo, for something live. Still under reduced motion. |
| color | string | - | Any CSS color. Paints the variant's treatment from it: a soft tint for the page-ground tones, a solid fill with a computed dark or white ink for primary / secondary, the hairline for outline; the dot takes it as is. Ignored by the overlay* fills. The root gets data-color and, when solid, data-ink (dark | light). The exported readableInk(color) returns that same pick. |
| onRemove | () => void | - | Renders a trailing dismiss button that calls it. |
| removeLabel | string | "Remove" | The accessible label of the dismiss button. Name the item ("Remove Design"). |
| asChild | boolean | false | Renders the badge styles onto its single child (Radix Slot), such as a link. Ignores dot and onRemove. A link gets a hover fill, a focus ring and a nudging trailing arrow. |
BadgeAvatar
A picture placed first inside the badge, sized to it. Forwards all native <img> props; alt defaults to empty since the label names the person.
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | - | The image URL. |
BadgeCount
A number nested at the end of the badge, tinted from its ink. Forwards all native <span> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | - | The count. |
BadgeText
Client. A label that rolls to its new string and eases the badge width to fit. Forwards native <span> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | string | - | The label. Changing it plays the roll. |
| sweep | boolean | - | Passes the ink band through the label, for open-ended work. |
BadgeIcon
Client. Wraps the leading glyph so it is sized and toned like a direct icon, and grows the new one in on swap.
| Prop | Type | Default | Description |
|---|---|---|---|
| swap | string | - | Any key for the current glyph; changing it plays the swap. |
BadgeNumber
Client. A number whose digits roll like drums when it changes. Labelled with its value for assistive tech.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | - | A non-negative integer. |
BadgeProgress
Client. A ring that fills to the value, sized and toned like a leading icon. Exposes progressbar semantics.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | - | 0 to 100. |
BadgeReveal
Client. Wraps a badge in a row and opens or closes its slot, so neighbours slide. Hidden and inert while closed.
| Prop | Type | Default | Description |
|---|---|---|---|
| show | boolean | - | Whether the badge is in the row. |
Elena Ruiz
Jonas