Components
IconButton
A button whose only visible content is an icon, so it always needs an accessible name you supply. Prefer a labelled button where there is room for a word.
Usage
pnpm dlx shadcn@latest add @opsinjs/icon-button
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 { IconButton } from "@/components/ui/icon-button"import { Search } from "lucide-react"
<IconButton
icon={<Search />}
label="Search readings"
onClick={openSearch}
/>Examples
icon-button · base base · style base-lyraOpen under the product themeA toolbar of icon buttons
A header row where each glyph is one the reader already knows, and each control still
carries a distinct label.
icon-button-toolbar · base base · style base-lyraOpen under the product themeimport { Bell, MoreHorizontal, Search } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
export default function IconButtonToolbar() {
return (
<div className="flex items-center gap-opsin-1">
<IconButton variant="quiet" icon={<Search />} label="Search example readings" />
<IconButton variant="quiet" icon={<Bell />} label="Example reminders" />
<IconButton
variant="quiet"
icon={<MoreHorizontal />}
label="More actions for this example"
/>
</div>
)
}Icon buttons in a list row
Edit and Remove repeat on every row as icon buttons. Each label carries its row's
context, so a voice-control user reaches one control.
icon-button-list-row · base base · style base-lyraOpen under the product themeimport { Pencil, X } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
export default function IconButtonListRow() {
return (
<ul className="flex w-full max-w-sm flex-col gap-opsin-1">
<li className="flex items-center justify-between gap-opsin-2 rounded-opsin-md border border-border bg-card px-opsin-3 py-opsin-2">
<span className="text-opsin-body [color:var(--foreground)]">
Morning example reading
</span>
<span className="flex items-center gap-opsin-0-5">
<IconButton
variant="quiet"
size="sm"
icon={<Pencil />}
label="Edit the morning example reading"
/>
<IconButton
variant="quiet"
size="sm"
icon={<X />}
label="Remove the morning example reading"
/>
</span>
</li>
<li className="flex items-center justify-between gap-opsin-2 rounded-opsin-md border border-border bg-card px-opsin-3 py-opsin-2">
<span className="text-opsin-body [color:var(--foreground)]">
Evening example reading
</span>
<span className="flex items-center gap-opsin-0-5">
<IconButton
variant="quiet"
size="sm"
icon={<Pencil />}
label="Edit the evening example reading"
/>
<IconButton
variant="quiet"
size="sm"
icon={<X />}
label="Remove the evening example reading"
/>
</span>
</li>
</ul>
)
}When to use it
Use it when
- A dense toolbar or card header where a universally understood glyph, such as a close cross, stands in for a word that would not fit.
- A repeated action in a list or table row, where a labelled button on every row would crowd the content out.
- A secondary control beside a labelled primary, where the reader has already taken in the row's context.
Do not use it when
- There is room for a word. A short verb beats a glyph almost everywhere.Use
buttoninstead. - The control turns something on or off, where a glyph reads as a state rather than an action.Use
switchinstead. - You were about to explain the icon through a hover tooltip. There is no hover on a phone.Use
tooltipinstead.
Accessibility
A real button element through Button supplies Return, Space, the role
and the tab stop. The control is icon-only by design, so aria-label plus a visually
hidden text node is its correct and complete name route rather than a persistent visible
label, and the glyph is aria-hidden, never announced as a second, pictorial name. The
audit found no critical, serious or moderate defect in the source, and
pnpm run check:a11y confirms on every commit that every colour is a role token, no
type size is in px, and no banned word appears anywhere.
Residual items.
- A missing or whitespace-only
labelraises a development warning. - The target is a 44pt square in rem with horizontal padding removed, and separation is
left to the caller's
--opsin-target-separation. - Contrast on every variant, the focus ring, and forced colours are not measured, and all are inherited from Button.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the icon button | One tab stop for the whole control. The glyph and name are parts, not stops. |
| Shift+Tab | Moves focus back out, to whatever precedes it | Reverse order matches the visual order. The component never moves focus of its own accord. |
| Enter | Activates the button | Platform behaviour on a real button element, inherited from Button. Nothing here intercepts it. |
| Space | Activates the button | Consumed by the focused button, so the page does not scroll. |
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 IconButtonProps in registry/bases/base/icon-button.tsx.
icon and label are both required. variant defaults to secondary over
quiet, since a bordered control is easier to recognise without a word inside
it. There is no busy, busyLabel, fullWidth, iconPosition or type.
className must never resolve a --opsin-status-* or --opsin-category-*
role; an IconButton carries no clinical axis.