Data display
Badge & Tag
Small, high-density labels that carry meaning at a glance — status, priority, labels, counts. A semantic color system keeps them consistent everywhere they appear.
npx shadcn@latest add @orbit/badgeOverview
Eight tones, four variants, status and priority presets, counts, and removable tags.
Variants
The same tone in four weights of emphasis. soft is the everyday default.
Sizes
md 22px for standalone use, sm 18px for inline-with-text and dense tables.
Tones
Eight tones, each with a meaning. Use them consistently — green is always success, red always a problem.
| Tone | Soft | Solid | Outline |
|---|---|---|---|
| Neutral | Default | Default | Default |
| Blue | Info | Info | Info |
| Green | Success | Success | Success |
| Amber | Warning | Warning | Warning |
| Red | Danger | Danger | Danger |
| Purple | Special | Special | Special |
| Teal | Accent | Accent | Accent |
| Pink | Accent | Accent | Accent |
Status & priority presets
Named presets bake in the right tone, label, and glyph — so a task reads the same in a dropdown and on a card.
Counts & indicators
Numeric badges for tallies and unread counts (clamped at 99+); a bare dot for a subtle “something changed”.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| label | ReactNode | — | Badge text. children works too and wins over label. |
| tone | "neutral" | "blue" | "green" | "amber" | "red" | "purple" | "teal" | "pink" | "blue" | Semantic color. Count mode defaults to neutral. Overrides a preset's tone. |
| variant | "soft" | "solid" | "outline" | "dot" | "soft" | Visual treatment. dot forces the leading dot on a neutral chip. |
| status | "todo" | "inprogress" | "review" | "done" | "canceled" | "blocked" | — | Status preset — bakes in tone, label, and a leading dot. |
| priority | "none" | "low" | "medium" | "high" | "urgent" | — | Priority preset — bakes in tone, label, and a bars/urgent glyph. |
| size | "sm" | "md" | "md" | Height: 18 / 22px. |
| icon | "tag" | "check" | "clock" | "flag" | "star" | "sparkle" | — | Leading glyph, tinted with the tone accent. |
| dot | boolean | false | Leading status dot. Defaults on for status presets. |
| count | number | string | — | Count mode — renders a numeric pill instead; values over 99 clamp to 99+. |
| removable | boolean | false | Renders a × button, turning the badge into a dismissible tag. |
| uppercase | boolean | false | Uppercase micro-label treatment (font −1px, weight 600, tracked). |
| value | string | — | Identifier passed to onRemove. |
| onRemove | (value?: string) => void | — | Called on × click. Without it the tag removes itself (uncontrolled). |
| …rest | HTMLAttributes<HTMLSpanElement> | — | Everything else is forwarded to the root <span>, including ref. |
Usage
Badges inform; they rarely act.
Keep tone meanings fixed
Green = success, red = danger, everywhere. Consistent color is what makes badges scannable.
Use a badge as a button
If it triggers an action, it should be a Button. Badges are for reading, not clicking.
Keep labels to a word or two
“In progress”, “Urgent”, “Bug”. Long text defeats the at-a-glance purpose.
Rely on color alone
Pair tone with a label or glyph so meaning survives for color-blind users.
Keyboard & accessibility
Text meets AA contrast on every tone. Add role='status' where the value updates live. The × on a removable tag is a real <button> named “Remove {label}” — Tab reaches it, Enter and Space activate it.