Skip to content
WunderUI

Icon Button

Free

Run a compact action with one icon, in a square or a round button.

npx wunderui-cli add icon-button

Playground

Installation

bash
npx wunderui-cli add icon-button

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

Then use it:

tsx
import { Plus } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"

export function AddMember() {
  return (
    <IconButton variant="plain" aria-label="Add member">
      <Plus />
    </IconButton>
  )
}

Expected result: You see one 36 px square button with a white fill, a thin border and a plus icon.

When to use

Use Icon Button for

  • A frequent action whose icon is unmistakable: close, edit, copy, more options
  • Dense places such as toolbars, table rows, card headers and dialog corners
  • A floating or round action, with the circle shape

Use something else for

  • Button for an action that needs a text label, or whose icon could be misread
  • Toggle for an icon button that stays on or off, such as Favorite
  • Button Group for several related icon buttons joined into one control
  • Dropdown Menu for many actions behind one More button

Appearance

Plain is the ordinary icon button with a box, Ghost belongs in toolbars and rows, and Primary or Gradient is the one main action.

Shape

Rounded is the default. Use the circle for a floating action or next to other fully rounded controls.

Sizes

Five squares, small to 2xl. The icon is 16, 18, 20, 22 and 24 px, and the hit area is the whole square.

Size

States

Hover, pressed and focus are forced here to show what the pointer and keyboard produce. Loading shows the spinner in the same square.

The expanded state marks the button whose menu or panel is open. It sets aria-expanded and the pressed surface.

Async feedback

The result shows in the same square, so the size never changes. Change the accessible name with the phase.

Name and tooltip

An icon-only button always has an accessible name. The tooltip repeats it on hover and focus and never replaces it.

Keyboard interactions

Icon Button is a native button, so the browser handles focus and activation. In a Toolbar the arrow keys move between buttons.

TaborShiftTab
Moves focus to or away from the button. A disabled button is skipped; a pending one keeps the focus.
EnterorSpace
Presses the button. While it is pending, the press is ignored.

Behavior and motion

What the icon button does with state, content, the DOM and motion.

Name
The icon is decorative, so the name comes from aria-label, which you can change with the phase. A tooltip repeats the name on hover and focus but never replaces it.
Variants and shapes
Nine variants in a rounded or circle shape; the default is primary, so pick plain for secondary actions and ghost for icon-only controls inside a row, toolbar, field or card.
Size
Size sets the square (32, 36, 40, 44 or 48 px) and the icon with it (16 to 24 px). Never resize an icon button with classes.
States
Hover fills with the page tone, pressed with the subtle tone and scales the button to 0.97. Focus draws an indigo border and a 2 px ring; disabled dims to 40 % and ignores the pointer.
Pending and phase
Pending and phase swap the icon for a spinner, a check or a retry icon in the same square. The size never changes, presses are ignored while it runs, and the button stays focusable.
Expanded
Expanded sets aria-expanded and the pressed look on the quiet variants while a menu or panel is open. Leave it unset when the button controls no popup.
Motion
Fill and border change quickly. A press scales the button to 0.97 and the pending spinner turns continuously.
Reduced motion
With reduced motion the press scale and spinner rotation are off; the fills still change at the same speed.

Anatomy

Icon Button is one element with one icon inside. The icon is simply the child you pass.

  • data-slot="icon-button"

    A native button with one icon in a square or circle, named by aria-label since it has no text. Pending and phase show async feedback in the same square; expanded marks an open trigger.

  • The child: a Lucide icon with a 1.5 stroke, sized 16, 18, 20, 22 or 24 px by button size, in the text colour. The whole square is the hit area.

  • Optional

    A table cell with a small plain icon button beside a label. The label becomes the button's name and falls back to Action.

Best practices

  • Do

    Give every IconButton an aria-label that names the action: Delete invoice, not Trash. A tooltip is extra help, not the name.

  • Do

    Use plain for a secondary icon action with its own box and ghost for an icon-only control inside a row, toolbar, field or card. The default is primary, and a view has one primary action.

  • Do

    Pass a label to IconButtonTextCell. Without it every row's button is announced as Action.

  • Do

    Show a running action with pending or phase instead of swapping the icon yourself. Change the aria-label with the phase: Copy link, Copying link, Link copied.

  • Do

    Put the badge count in the name: Notifications, 3 unread. Draw the counter on a relative wrapper and hide it from assistive technology; the badge is not a second button.

  • Do

    Use expanded on a trigger that opens a menu or panel, and a Toggle with one stable name for a state that stays on, such as Favorite. Pressed (the click) and selected look different.

  • Don’t

    Don't use the small sizes as the only control on a touch screen. Pick the two largest, which reach the 44 px hit area touch needs.

API reference

Every part also takes the props of the primitive it wraps. Icon Button wraps the Base UI button, so it accepts all native button attributes, render and nativeButton.

A native button with one icon in a square or circle, named by aria-label since it has no text. Pending and phase show async feedback in the same square; expanded marks an open trigger.

PropTypeDefaultDescription
variant"plain" | "gradient" | "outline" | "primary" | "destructive" | "light" | "ghost" | "brand" | "dark""primary"The look. is the ordinary icon button with its own box, has no box and no fill until hover and belongs in toolbars, rows, fields and cards, and are for the main action, is the brand fill, and are for surfaces of the opposite tone, is an indigo-rimmed accent and is red.
size"lg" | "xl" | "sm" | "md" | "2xl""md"The side of the square: is 32 px, 36, 40, 44 and 48. The icon is 16, 18, 20, 22 and 24 px.
shape"circle" | "rounded""rounded" has a medium corner radius, is fully rounded.
pendingboolean—Shows a spinner in place of the icon, in the same square, and ignores presses. The button stays focusable and keeps its colour.
phase"error" | "success" | "pending" | "idle"—Async feedback in the same square: shows a spinner, a check, a retry icon and turns a filled button red. Change the with the phase.
expandedboolean—Marks a trigger whose menu or panel is open: sets and the pressed surface on the quiet variants. Leave it undefined when the button does not control a popup.
nativeButtonbooleantrueWhether the component renders a native . Set it to together with when the element is not a button, such as an anchor.
focusableWhenDisabledbooleanfalseKeeps a disabled button in the tab order, so a screen reader user can find it and read why it is disabled.

A table cell with a small plain icon button beside a label. The label becomes the button's name and falls back to Action.

PropTypeDefaultDescription
icon requiredReactNode—The icon of the small plain button.
labelstring—The accessible name of the button, such as . Without it the name is on every row.
children requiredReactNode—The text beside the button.
onClick() => void—Runs when the icon button is pressed.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("icon-button")
Installnpx wunderui-cli add icon-button

The full library index for assistants is at /llms.txt.