Skip to content
WunderUI

Badge

Free

Label a row, card or control with a short status or category.

npx wunderui-cli add badge

Playground

Approved

Installation

bash
npx wunderui-cli add badge

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Badge,
  BadgeCounter,
  BadgeIndicator,
  BadgeProcessing,
} from "@/components/ui/badge"
import type {
  BadgeColor,
  BadgeCounterTone,
  BadgeIndicatorKind,
  BadgeProcessingState,
  BadgeStyle,
} from "@/components/ui/badge"

Then use it:

tsx
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.

Active

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.

Design

Shape

A pill reads as a status, a rounded badge as a tag. Pick one shape per list.

Beta

Size

Small is 20 px high and fits tables and lists. Medium is 24 px and sits beside a heading.

Beta

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.

Approved

Counter

A count next to a label, or on the corner of an icon button. Counts above 99 read 99+.

Inbox3

Indicator

A small signal on an object. Each kind has its own shape, so presence never depends on colour alone.

Online

Processing

A running operation and its result. The spinner turns only while the work runs.

Syncing

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

NLNora Lindgren

Input token

info@wunderui.com

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.

TaborShiftTab
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.

Approved
  • 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.

  • Optional

    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.

  • 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.

  • data-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.

PropTypeDefaultDescription
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.
dotboolean—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 .
removeLabelstring"Remove"The accessible name of the remove button. Name the tag in it: .
renderReactElement | (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.

PropTypeDefaultDescription
label requiredstring—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.

PropTypeDefaultDescription
count requirednumber—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.
overlaybooleanfalsePositions 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.
maxnumber99The largest number shown. Above it the counter reads , or for another value.
hideZeroboolean—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.

PropTypeDefaultDescription
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.
labelstring—The accessible name. Defaults to the name of the kind, such as or ; give it more detail when it helps, such as .
overlaybooleanfalsePositions 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.

PropTypeDefaultDescription
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.
removeLabelstring—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.

PropTypeDefaultDescription
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.
leadingReactNode—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 requiredReactNode—The label of the chip.
selectedboolean—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.
openboolean—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.
removeLabelstring—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.

PropTypeDefaultDescription
leading requiredReactNode—The mark before the name, 24 px: an , an image, a flag.
children requiredReactNode—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.
removeLabelstring—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.

PropTypeDefaultDescription
children requiredReactNode—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.
removeLabelstring—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.

MCPget_component("badge")
Installnpx wunderui-cli add badge

The full library index for assistants is at /llms.txt.