Pill
Hero example
When to use
Pill is the canonical small inline tag. Reach for it when text needs a
quiet visual container — a status, a version, an entity ID rendered next
to display copy. Tones carry meaning: neutral for identifiers, green
for live / verified states, orange for warnings / Matter brand
emphasis, indigo for in-progress states, beta for the
announcement-style marketing pill.
tone="neutral" for entity IDs and version strings rendered inside body copy or table rows.Anatomy
A single <span> with a .pill class hook plus one .pill-{tone} modifier.
Optional icon slot renders before the children with a 4px gap.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| tone | PillTone | "neutral" | — |
| icon | React.ReactNode | — | — |
| shimmer | boolean | — | — |
| chip | React.ReactNode | — | Inner-chip label when `tone="beta"`. Defaults to "Beta". Ignored for every other tone. |
| children | React.ReactNode | — | — |
Also accepts Omit<React.HTMLAttributes<HTMLSpanElement>, "children">.
Tone matrix
The four mono-chip-style tones (neutral, green, orange, indigo)
match the V1 <MonoChip> palette exactly — 20px tall, mono font, V1
token references — so the MonoChip → Pill consumer migration in action
9 of the design-system plan is a straight swap with pixel parity.
tone="beta" is the announcement-pill shape used in marketing surfaces.
| Tone | Foreground (CSS var) | Background (CSS var) | Replaces |
|---|---|---|---|
neutral | --stone-700 | --stone-100 | <MonoChip tone="neutral"> |
green | --matter-green-dk | --matter-green-bg | <MonoChip tone="green"> |
orange | --matter-orange | --matter-orange-bg | <MonoChip tone="orange"> |
indigo | --matter-indigo | --matter-indigo-bg | <MonoChip tone="indigo"> |
beta | (announcement shape — see below) | <BetaPill> |
tone="beta" — announcement structure
The beta tone is structurally distinct: a 32px-tall outer chip wraps a
green inner chip (with pulsing dot + label) + a main text span + a
chevron. Mirrors V1 <BetaPill> exactly — pixel-parity migration.
<Pill tone="beta">Beta feature now available</Pill>
<Pill tone="beta" /> {/* empty text span — inline Beta badge */}
<Pill tone="beta" chip="New">Look at this</Pill> {/* inner chip override */}The chip prop only takes effect when tone="beta". The pulsing dot
and float animation collapse under prefers-reduced-motion: reduce.
Shimmer · live-status sweep
<Pill shimmer> clips a sweeping gradient across the children — the
live-status moment V1 <StatusPill> carried. Stacks with any tone.
Collapses to a static gradient under prefers-reduced-motion: reduce.
<Pill shimmer tone="green">LIVE · indexing</Pill>When action 9 migrates <StatusPill> consumers, the V1 444×48 glass
panel decomposes into <Glass> + an avatar + <Pill shimmer> rather
than a single primitive — Pill's mono-chip frame is the wrong shape for
the StatusPill role, but the shimmer behaviour itself transfers cleanly.
States
Density
Themes
Light / dark / forced-colors side-by-side.
Tokens consumed
Accessibility
- Keyboard interactions
- ARIA roles
- Focus ring uses the canonical peach ring
prefers-reduced-motioncollapses motion to opacity
Do / Don't
Recipes
Where this component shows up in real screens — link to /recipes/* pages.