---
title: "IconButton"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/icon-button"
source: "https://opsinjs.pensievelabs.org/docs/components/icon-button.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["glyph button", "round button"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="icon-button"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured for the glyph against any variant's fill or for the focus ring, and Button's own unmeasured pairs are inherited.&#x22;,
  &#x22;Nobody has listened to this control in a screen reader, so whether the name set twice reads as one name or two is unheard.&#x22;,
  &#x22;Forced colours and prefers-contrast are unhandled, inherited from Button, and a quiet icon button carrying only ink may not survive a palette that replaces author ink.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="icon-button" unbuilt="false" importPath="@/components/ui/icon-button" dependencies="[&#x22;lucide-react&#x22;]" registryDependencies="[&#x22;button&#x22;]" />

```tsx
import { IconButton } from "@/components/ui/icon-button"
```

```tsx
import { Search } from "lucide-react"

<IconButton
  icon={<Search />}
  label="Search readings"
  onClick={openSearch}
/>
```

## Examples [#examples]

<ComponentPreview name="icon-button" />

### A toolbar of icon buttons [#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`.

<ComponentPreview name="icon-button-toolbar" kind="example" align="start" />

### Icon buttons in a list row [#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.

<ComponentPreview name="icon-button-list-row" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;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.&#x22;,
  &#x22;A repeated action in a list or table row, where a labelled button on every row would crowd the content out.&#x22;,
  &#x22;A secondary control beside a labelled primary, where the reader has already taken in the row's context.&#x22;,
]"
  avoid="[
  { case: &#x22;There is room for a word. A short verb beats a glyph almost everywhere.&#x22;, instead: &#x22;button&#x22; },
  { case: &#x22;The control turns something on or off, where a glyph reads as a state rather than an action.&#x22;, instead: &#x22;switch&#x22; },
  { case: &#x22;You were about to explain the icon through a hover tooltip. There is no hover on a phone.&#x22;, instead: &#x22;tooltip&#x22; },
]"
/>

## Accessibility [#accessibility]

A real `button` element through [Button](./button.mdx) 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.

<KeyboardTable
  name="icon-button"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus to the icon button&#x22;,
    notes: &#x22;One tab stop for the whole control. The glyph and name are parts, not stops.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back out, to whatever precedes it&#x22;,
    notes: &#x22;Reverse order matches the visual order. The component never moves focus of its own accord.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Activates the button&#x22;,
    notes: &#x22;Platform behaviour on a real button element, inherited from Button. Nothing here intercepts it.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Activates the button&#x22;,
    notes: &#x22;Consumed by the focused button, so the page does not scroll.&#x22;,
  },
]"
/>

<ContrastReport component="icon-button" />

## Props interface [#props-interface]

<PropsTable name="IconButtonProps" />

`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.
