Badge
A badge is a static marker for a status, a category, or a small count.
Installation
npx shadcn@latest add @flyingsalmon/badgeUsage
import { Badge, BadgeVariant } from '@/components/ui/badge'
export function TripStatus() {
return <Badge variant={BadgeVariant.Success}>Booked</Badge>
}Examples
Variants
Default marks what is live right now, secondary fills quietly, and outline draws a border only. Success, warning, and error are the status trio: a tinted fill behind coloured text.
Leading icon
The icon prop takes one icon before the label. Pass it bare: the badge sizes it, spaces it, and hides it from screen readers. There is no trailing slot.
Count
A small number reads as a badge beside a label. Keep it to a count the traveller would glance at, not a figure they would compare.
Places to visit12
In a table row
The badge keeps one height, so it sits in a cell without changing the row’s rhythm.
| Trip | Status |
|---|---|
| Hanoi in spring | Booked |
| Da Nang with the family | Needs a passport |
| Kyoto in autumn | Draft |
In a line of text
The badge sits inline after the words it qualifies.
Brian Nguyen invited you to Hanoi in spring Shared
Guidelines
When to use
- To label the state of a thing: a trip is booked, a payment failed, a visa is expiring.
- To tag a category or show a small count beside a label.
When not to use
- Use Button when the marker must do something on press, because a badge takes no focus and nothing inside it is interactive.
- Use Notice to report the result of an action, because a result belongs on the item that changed or in a notice that links back to it.
- Use Avatar to mark a person, because a person has a face and a name.
Do and don’t
- Don’tGive the normal state a badge.An exception reads at a glance only against plain rows. When every item wears a badge, none of them stands out.
- DoName the state in the label, such as Booked or Date clash.Colour only reinforces the word. A reader who cannot tell orange from green still has to learn the state.
- DoKeep the orange badge for what is live right now, such as today or a trip underway.Orange is the loudest colour on the page, so it marks the one thing happening now. A finished state is green, a fact or an absence takes the outline, and quiet metadata takes the grey badge.
- DoPaint a condition that already holds, such as a failed payment, in error red.Error red reports a condition. Destructive red names an action a person can take, such as delete, and belongs to the destructive button.
- DoAdd an icon to a state that needs attention or is done, and leave neutral states as words.The icon gives the states that matter a shape the eye catches before it reads, so a warning stands out from a row of quiet labels.
- Don’tPut more than one state badge on an item.Each badge asks to be read, and a second state means the first is not the one that matters. Put the rest in the item’s details. Category tags are the exception and sit together as a quiet row.
Accessibility
The badge renders a plain span with no role and no tab stop, so a screen reader reads its text inline with the surrounding content. A leading icon is decoration and is hidden, so the label is read once. A link or a button inside a badge is unreachable by keyboard, so a badge holds only its label and icon. Every variant meets WCAG AA contrast. When the badge is the only carrier of a meaning, state that meaning in the surrounding text as well.
API
Badge
Also takes every <span> attribute except tabIndex.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | BadgeVariant | BadgeVariant.Default | Default, Secondary, Outline, Success, Warning, or Error. Error marks a condition that already holds, never an action. |
| icon | ReactNode | – | One leading icon. The badge owns its size and hides it from screen readers. |