Components
Badge
A small neutral label attached to something else, like a count on a tab or a word on a list row. It takes no colour axis and never stands in for status.
Usage
pnpm dlx shadcn@latest add @opsinjs/badge
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Badge } from "@/components/ui/badge"<span className="inline-flex items-center gap-2">
Messages
<Badge srLabel="3 unread">3</Badge>
</span>Examples
badge · base base · style base-lyraOpen under the product themeA count on a label
Each badge attaches a fictional count to the label beside it. srLabel names
that count, so a screen reader hears "5 waiting" rather than a lone "5".
badge-a-count-on-a-label · base base · style base-lyraOpen under the product themeimport { Badge } from "@/components/ui/badge"
export default function BadgeACountOnALabel() {
return (
<div className="flex flex-col gap-opsin-3 text-opsin-body [color:var(--foreground)]">
<span className="inline-flex items-center gap-opsin-2">
Reminders
<Badge srLabel="5 waiting">5</Badge>
</span>
<span className="inline-flex items-center gap-opsin-2">
Shared with you
<Badge srLabel="2 new">2</Badge>
</span>
</div>
)
}The two weights
variant chooses soft or outline, and both are neutral. Read in greyscale
they are two quiet chips, and a status pill beside them would still be the only
thing carrying a level.
badge-the-two-weights · base base · style base-lyraOpen under the product themeimport { Badge } from "@/components/ui/badge"
export default function BadgeTheTwoWeights() {
return (
<div className="flex items-center gap-opsin-4">
<Badge>Soft</Badge>
<Badge variant="outline">Outline</Badge>
</div>
)
}When to use it
Use it when
- A small neutral count attached to a label, such as an unread count on a tab, where the number carries no clinical meaning.
- A short neutral word on a list row or a heading, such as a category name the product owns, that is not a status.
- A compact chip of neutral chrome that reads more calmly than a full sentence, as long as it carries content rather than urgency.
Do not use it when
- The label says what a reading means or how urgent it is. A badge would carry that as colour alone.Use
status-pillinstead. - You are showing a measurement and its unit rather than a count or a word.Use
valueinstead. - The chip has to be tapped to do something. A badge is content, not a control, and takes no focus.Use
buttoninstead.
Accessibility
pnpm run check:a11y confirms on every commit that the badge draws only
neutral chrome roles, carries no data-status and sets its text at the
caption1 step rather than a px size. The audit fixed one defect: aria-label
on a bare span, whose implicit role is generic, does not reliably carry an
author-supplied name, so a non-empty srLabel now adds role="img", the
pairing Avatar uses. Nothing else changed.
Argued from the source, not measured. srLabel="" sets aria-hidden, so a
count already spoken beside the badge is not read twice. Nothing takes focus,
answers a key or animates, so there is no keyboard contract and nothing for
prefers-reduced-motion to reduce. At 200% text and under a wider text-spacing
override the chip grows rather than clipping, because nothing fixes its height
or hides its overflow.
Residual items.
- No contrast pair in either weight has been measured against real token values, so the figures below are whatever the generator has produced so far.
- Nothing checks that
srLabeltextually contains the visible content, so a caller can still write a disjoint label. That is a documented usage contract, not enforced behaviour. - Nobody has listened to a labelled badge in a screen reader in the flow of its host, so how it reads there is reasoned from the roles.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the badge | A badge is content, not a control. Nothing here is focusable. |
| Shift+Tab | Skips the badge | Same in reverse. A badge never appears in the focus order. |
| Arrow keys | Nothing | There is nothing to select, move or expand. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from BadgeProps in registry/bases/base/badge.tsx.
variant defaults to soft and chooses a neutral weight only. There is no
colour prop, because a badge is on neither axis, and colour passed through
className is the caller's to keep off both. srLabel names a bare count, and
an empty string hides a decorative badge from the accessibility tree.