A badge is the smallest component with the most rules, because it is the one place an interface routinely encodes meaning in colour alone. Everything else in a screen has a label. A green dot has whatever the reader guesses.
59 public components on 21st have "badge" in the name. They do three different jobs, and mixing them is what makes a table hard to read.
Status
The most common and the one with real requirements. Status Badge and Badge Delta are the Tremor-shaped versions - a state, and a change with a direction - and Status Badge by Arihant jain is another take.
Three rules make a status system readable.
Never colour alone. Around one in twelve men has some form of colour vision deficiency, and red and green are the pair most often confused, which is exactly the pair every status system reaches for first. Pair the colour with a word, an icon or a shape. A green dot beside the word "Active" is fine; a green dot on its own is a guess.
Fix the set early. Four or five states, defined once: neutral, in progress, success, warning, error. The moment a sixth colour appears for one screen, the vocabulary stops being learnable.
Announce changes. A badge that flips from "Processing" to "Failed" without a live region has changed silently for anyone not looking at it.
Count
A number attached to something: unread messages, items in a cart. The rules here are about honesty and truncation. Cap the display at 99+ and keep the exact number in the accessible name. Never show a zero badge, hide the element instead. And the count has to be right, because a notification badge that is wrong twice is a badge people stop seeing.
Label
Category, plan, version, tag. Decorative in the sense that removing it loses a detail rather than a meaning. Marketing Badges by Jatin Yadav is the 3D marketing take, Animated Badge by karthikmudunuri is the customisable animated one, and Product Hunt Badge by tigran tumasov is the award shape, which is the most-bookmarked badge in the catalogue.
Streak Badge by trophyso is the gamification variant, and Globe Live Badge by shuding is the unusual one: a WebGL globe carrying live viewer counts.
The markup
A badge is text, so it should be text. A <span> with a word in it beats a div with a background and an aria-label, because the word is then selectable, translatable and readable by everything.
Two specific cases. A badge that is a filter or removes a tag is a <button>, with a name that says what pressing it does - "Remove Design tag", not "×". And a count badge attached to an icon button belongs inside the button's accessible name: "Notifications, 3 unread" rather than a separate element the reader has to correlate.
Size is the other thing worth deciding once. Badges get small fast, and text below about 12px with low-contrast colours is where design systems quietly fail contrast. The requirement is 4.5:1 for normal-size text; a pale grey badge on a white card is usually nowhere near it.
Where else to look
The honest list of alternatives, because the answer is not always us:
| Source | Best for | Trade-off |
|---|---|---|
| shadcn/ui Badge | The base with variants, in your theme tokens | One shape; status semantics are yours to define |
| Tailwind CSS | Honestly enough for most badges: two classes and a word | Not a component |
| 21st | Status systems, deltas, award badges and animated labels | Quality varies by author, so preview before you take it |
Taking one
Every component page has a live preview and the code. Installing goes through the shadcn CLI against our registry:
That key comes from your 21st account, and installs require a membership. Set API_KEY_21ST once in your shell and the command works for anything in the catalogue. The 21st MCP covers the same ground without leaving the editor: ask Claude, Cursor or Codex for a badge, get the previews inline, and let the agent write the file.
Frequently asked
- Can a status be shown with colour alone?
- No. Around one in twelve men has some form of colour vision deficiency, and red and green are the pair most often confused, which is exactly the pair every status system reaches for. Pair the colour with a word, an icon or a shape: a green dot beside the word Active is fine, a green dot alone is a guess.
- How many status colours should a design system have?
- Four or five, defined once: neutral, in progress, success, warning, error. The moment a sixth appears for one screen the vocabulary stops being learnable, and a reader who has to look up what teal means is reading a legend instead of the data.
- How should a notification count badge behave?
- Cap the display at 99+ while keeping the exact number in the accessible name, hide the badge entirely at zero rather than showing one, and fold the count into the button's accessible name, as in Notifications, 3 unread. And keep it accurate: a count that is wrong twice is a count people stop seeing.
- Do small badges pass contrast requirements?
- Often not. Badges get small fast, and text below about 12px in a pale colour on a white card is usually nowhere near the 4.5:1 required for normal-size text. Check the badge palette at the size you actually render, not at the size in the design file.