Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
icon-button · base base · style base-lyraOpen under the product theme

A toolbar of icon buttons

A header row where each glyph is one the reader already knows, and each control still carries a distinct label.

Theme
Density
Text
Status
Accent theme
Accent
icon-button-toolbar · base base · style base-lyraOpen under the product theme
icon-button-toolbar.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
icon-button-list-row · base base · style base-lyraOpen under the product theme
icon-button-list-row.tsx
import { 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 button instead.
  • The control turns something on or off, where a glyph reads as a state rather than an action.Use switch instead.
  • You were about to explain the icon through a hover tooltip. There is no hover on a phone.Use tooltip instead.

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 label raises 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.
KeyActionNotes
TabMoves focus to the icon buttonOne tab stop for the whole control. The glyph and name are parts, not stops.
Shift+TabMoves focus back out, to whatever precedes itReverse order matches the visual order. The component never moves focus of its own accord.
EnterActivates the buttonPlatform behaviour on a real button element, inherited from Button. Nothing here intercepts it.
SpaceActivates the buttonConsumed by the focused button, so the page does not scroll.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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.