Badge
FreeLabel a row, card or control with a short status or category.
npx wunderui-cli add badgePlayground
Installation
npx wunderui-cli add badgeWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Badge,
BadgeCounter,
BadgeIndicator,
BadgeProcessing,
} from "@/components/ui/badge"
import type {
BadgeColor,
BadgeCounterTone,
BadgeIndicatorKind,
BadgeProcessingState,
BadgeStyle,
} from "@/components/ui/badge"Then use it:
import { Badge } from "@/components/ui/badge"
export function Status() {
return (
<Badge color="green" badgeStyle="light" shape="pill">
Approved
</Badge>
)
}Expected result: You should see one small green pill with the word Approved.
When to use
Use Badge for
- A short status or category on a row, a card or a heading, such as Paid, Draft or Beta
- A count next to a navigation label or on the corner of an icon button
- A running operation and its result, such as Syncing, Synced and Failed
- Chips that filter or select, a person as a chip, and the entries of a multi-value field
Use something else for
- Alert for a message people need to read, with a title and an action
- Trend Chip for the change in a number, with its direction
- Avatar for presence on a person: the avatar draws its own status mark
- Segment for switching between two or more views, with one always selected
Style
Four looks for the same colours. Subtle fits most labels, solid the one that must stand out, outline a quiet rim, plain text with a dot.
Color
Six tones carry a status: neutral, brand, info, success, warning and danger. Six more colours label categories like a team, where colour alone means nothing.
Shape
A pill reads as a status, a rounded badge as a tag. Pick one shape per list.
Size
Small is 20 px high and fits tables and lists. Medium is 24 px and sits beside a heading.
Content
A badge holds a short label. Add an icon or dot before it, or a remove button after it for tags people can take off.
Counter
A count next to a label, or on the corner of an icon button. Counts above 99 read 99+.
Indicator
A small signal on an object. Each kind has its own shape, so presence never depends on colour alone.
Processing
A running operation and its result. The spinner turns only while the work runs.
Chips
The interactive relatives of the badge. A chip selects or filters, an entity chip names a person, an input token is one entry in a field.
Chip
Entity chip
Input token
Keyboard interactions
A badge is a span and takes no focus. Only what does something is a control: the remove button, a badge rendered as a button or link, and the chips.
- TaborShift+Tab
- Moves focus to the next or previous control: a remove button, a chip, a badge rendered as a link or button.
- EnterorSpace
- Runs the focused control: removes the tag, toggles the chip, opens the list of a dropdown chip.
Behavior and motion
What the badge does itself, and what it leaves to the page.
- Static by default
- A badge is a plain span: no role, no focus, no pointer. It reads as part of the text around it, so the label has to make sense there.
- Color and style
- Tinted looks use the tint tokens of the hue, so they follow light and dark mode. Every color and style pair is measured for AA contrast; the solid style uses white or the darkest step of the hue.
- A badge that does something
- As a button or link, the badge shows a ring in its own color on hover, scales down on press and gets the focus ring. The remove button is left out then, so two controls never nest.
- Remove
- A remove handler draws the remove button and calls your function. The badge does not hide itself: take the tag out of your list, and move focus to the next tag or the field.
- Counter
- A count above 99 reads 99+. An overlay counter hides at zero unless you keep it and needs a relative parent, and an inline counter shows 0 in tertiary text.
- Indicator
- The indicator is an image with an accessible name from its label, or a default for its kind. An overlay needs a relative parent, and its ring uses the card color so it stays readable on any surface.
- Processing
- The processing badge is a status region, marked busy while pending, and swaps the spinner for a check or a warning sign when the work ends. The text always names the state.
- Chips
- A chip keeps no state of its own: pass selected and open, and change them in the click handler. They set the matching aria-pressed, aria-checked or aria-expanded.
- Motion
- Color and ring changes use the fast duration. A pressed badge scales to 95 %, the remove button to 90 %, and the processing spinner turns until the work ends.
- Reduced motion
- With reduced motion on, the processing spinner is a still icon and the remove button no longer scales on press. The state is still named in text.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- 1
A short label in a rounded box, in 12 colors, 6 styles, two sizes (20 or 24 px) and a rounded or pill shape. As a button or link it gains hover, focus and press states.
- 2Optional
A Lucide icon as a child, or a dot. The icon is 12 px on a small badge and 14 px on a medium one, follows the label color, and sits 4 or 6 px before it.
- 3
One short line, 12 px semibold on a small badge and 14 px on a medium one. It never wraps and clips what does not fit, so keep the label to a word or two.
- 4data-slot="badge-remove"Optional
A 16 px round button with an X, drawn when a remove handler is set. It is a separate button with its own name and the badge itself stays inert; it is left out when the badge is a button or link.
- data-slot="badge-dot"Optional
- Optional
A Badge for a table cell, made from a label string, with the light border style by default.
- data-slot="badge-counter"Optional
A count next to a label, or on the corner of an icon button, in neutral, brand or danger tones. Counts above 99 read 99+, and an overlay counter hides itself at zero.
- data-slot="badge-indicator"Optional
A small signal: unread, presence (online, away, busy, offline) or a symbol (check, warning, lock). Each kind has its own shape, not only its own color, and carries an accessible name.
- Optional
A running operation and its result: pending (a turning spinner), success or error. The label always names the state.
- Optional
An interactive pill that filters, selects or opens a list. Selection shows as the indigo tint and a mark, never as color alone.
- data-slot="chip"
- data-slot="chip-main"
- data-slot="token-chip"
- data-slot="entity-chip"
- Optional
A person, team or workspace as a pill: a 24 px mark (an avatar, an image, a flag) before the name, and an optional remove button. Written ; EntityChip is a deprecated alias.
- Optional
One entry inside a multi-value field, such as an email address. An invalid token gets a warning icon and the red tint; the field names the error. Written ; TokenChip is a deprecated alias.
Best practices
- Do
Give each status one color and keep it wherever that status appears. Write the status in the label as well, so color is never the only cue.
- Do
Use the light or light border style in tables and lists, and keep the solid style for the one badge that should stand out.
- Do
Render the badge as a button when it does something. Only a button or link gets the pointer cursor, the hover ring and the focus ring.
- Do
Put an overlay counter on the corner of a relatively positioned button and name the count in the button, like Notifications, 3 unread. The counter itself stays decorative.
- Do
Use Chip for a filter or a choice. It announces its selected state and shows a mark as well as the tint.
- Don’t
Don't use a Badge as a selection control. A removable tag takes a remove handler; anything that selects or opens a list is a Chip.
- Don’t
Don't recolor a badge with classes or hex values. Every color and style pair is measured for AA contrast in light and dark mode.
- Don’t
Don't put two badges on one heading, or a badge on every row of a list. A badge that is everywhere says nothing.
API reference
Badge renders a span, takes its native attributes and can render another element. The counter, indicator and processing badge are spans too, while the chips take only the props below.
A short label in a rounded box, in 12 colors, 6 styles, two sizes (20 or 24 px) and a rounded or pill shape. As a button or link it gains hover, focus and press states.
| Prop | Type | Default | Description |
|---|---|---|---|
| color | "blue" | "green" | "red" | "yellow" | "purple" | "indigo" | "pink" | "orange" | "alternative" | "grey" | "black" | "white" | "blue" | The hue of the badge. The status tones are (neutral), (brand), (info), (success), (warning) and (danger); the others label categories. |
| badgeStyle | "plain" | "light" | "light_border" | "border_color" | "border_grey" | "ghost" | "plain" | The look: is a solid fill, a tinted surface, a tint with a rim, and a white surface with a rim, and text only. In Figma they are Solid, Subtle, Outline and Plain. |
| shape | "rounded" | "pill" | "rounded" | has an 8 px radius, is fully round. |
| size | "sm" | "md" | "sm" | is 20 px high with 12 px text, is 24 px high with 14 px text. |
| dot | boolean | — | Draws a 6 px dot in the color of the label before it. |
| onRemove | () => void | — | Draws a remove button after the label and calls this function when it is pressed. Ignored when the badge is rendered through . |
| removeLabel | string | "Remove" | The accessible name of the remove button. Name the tag in it: . |
| render | ReactElement | (props, state) => ReactElement | — | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render. |
A Badge for a table cell, made from a label string, with the light border style by default.
| Prop | Type | Default | Description |
|---|---|---|---|
| label required | string | — | The text of the badge. |
| color | "blue" | "green" | "red" | "yellow" | "purple" | "indigo" | "pink" | "orange" | "alternative" | "grey" | "black" | "white" | "blue" | The hue of the badge. |
| badgeStyle | "plain" | "light" | "light_border" | "border_color" | "border_grey" | "ghost" | "light_border" | The look of the badge. Defaults to , the style of a status in a table. |
A count next to a label, or on the corner of an icon button, in neutral, brand or danger tones. Counts above 99 read 99+, and an overlay counter hides itself at zero.
| Prop | Type | Default | Description |
|---|---|---|---|
| count required | number | — | The number to show. Negative values and fractions are treated as 0 and cut to a whole number. |
| tone | "neutral" | "brand" | "danger" | "neutral" | is a grey pill, the primary color and red. |
| overlay | boolean | false | Positions the counter on the top right corner of its parent and gives it a ring in the card color. An overlay counter is hidden at zero. |
| max | number | 99 | The largest number shown. Above it the counter reads , or for another value. |
| hideZero | boolean | — | Hides the counter at zero. Defaults to for an overlay and for an inline counter. |
A small signal: unread, presence (online, away, busy, offline) or a symbol (check, warning, lock). Each kind has its own shape, not only its own color, and carries an accessible name.
| Prop | Type | Default | Description |
|---|---|---|---|
| kind required | "unread" | "online" | "away" | "busy" | "offline" | "check" | "warning" | "lock" | — | What the indicator stands for. Each kind has its own shape: a dot, a ring, a moon, a bar, a check, a triangle or a lock. |
| size | "sm" | "md" | "sm" | is 8 px for a dot and 16 px for a symbol; is 10 px and 20 px. |
| label | string | — | The accessible name. Defaults to the name of the kind, such as or ; give it more detail when it helps, such as . |
| overlay | boolean | false | Positions the indicator on the top right corner of its parent, with a ring in the card color. |
A running operation and its result: pending (a turning spinner), success or error. The label always names the state.
| Prop | Type | Default | Description |
|---|---|---|---|
| state required | "pending" | "success" | "error" | — | shows a turning spinner on a blue tint, a check on green and a warning sign on red. |
| size | "sm" | "md" | — | is 20 px high, is 24 px high. The badge is always a pill with the style. |
| removeLabel | string | — | No effect The processing badge has no remove button. |
An interactive pill that filters, selects or opens a list. Selection shows as the indigo tint and a mark, never as color alone.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "filter" | — | (default) is the filter chip: a pill that selects, filters or opens a list. is a rounded pill with a mark in and a name, for a person, team or workspace. is an input token with a , for an entry inside a multi-value field. EntityChip and TokenChip are deprecated aliases of the last two. |
| leading | ReactNode | — | Variant only. The mark before the name, 24 px: an , an image, a flag. |
| state | "default" | "focused" | "invalid" | "removing" | — | Variant only. adds a warning icon and the red tint, shows the focus ring of the field, fills the remove button while it is pressed. |
| children required | ReactNode | — | The label of the chip. |
| selected | boolean | — | Shows the chip as selected: the indigo tint and rim. With a check appears before the label. |
| mark | "none" | "check" | "radio" | "checkbox" | "suggest" | — | The mark before the label: a check when selected, a radio or a checkbox, or a dashed circle for a suggestion. |
| trailing | "none" | "chevron" | "remove" | — | What follows the label: nothing, a chevron for a chip that opens a list, or a remove button for an applied filter. |
| open | boolean | — | Shows a chip with a chevron as open: the tint, and the chevron points up. It also sets . |
| role | "radio" | "checkbox" | — | Use for one choice out of a group and for a multi-select. It sets from . |
| onClick | () => void | — | Called when the chip is pressed. The chip keeps no state: change or here. |
| onRemove | () => void | — | Called when the remove button of a chip with is pressed. |
| removeLabel | string | — | The accessible name of the remove button. Name the filter in it: . |
A person, team or workspace as a pill: a 24 px mark (an avatar, an image, a flag) before the name, and an optional remove button. Written ; EntityChip is a deprecated alias.
| Prop | Type | Default | Description |
|---|---|---|---|
| leading required | ReactNode | — | The mark before the name, 24 px: an , an image, a flag. |
| children required | ReactNode | — | The name of the person, team or workspace. |
| onRemove | () => void | — | Draws a remove button after the name and calls this function when it is pressed. |
| removeLabel | string | — | The accessible name of the remove button. Name the entity in it: . |
One entry inside a multi-value field, such as an email address. An invalid token gets a warning icon and the red tint; the field names the error. Written ; TokenChip is a deprecated alias.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The entry, such as an email address. |
| state | "default" | "focused" | "invalid" | "removing" | — | adds a warning icon and the red tint, shows the focus ring of the field, fills the remove button while it is pressed. |
| onRemove | () => void | — | Draws a remove button after the entry and calls this function when it is pressed. |
| removeLabel | string | — | The accessible name of the remove button. Name the entry in it: . |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("badge")npx wunderui-cli add badgeThe full library index for assistants is at /llms.txt.