# Icon Button

A square or circular button for a single icon action.

- Category: Core Elements
- Page: https://wunderui.com/components/icon-button
- Tier: Free

## Install

```bash
npx wunderui-cli add icon-button
```

## Import

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

## Minimal usage

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.

## Usage

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

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

## 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

- [Button](https://wunderui.com/components/button) for an action that needs a text label, or whose icon could be misread
- [Toggle](https://wunderui.com/components/toggle) for an icon button that stays on or off, such as Favorite
- [Button Group](https://wunderui.com/components/button-group) for several related icon buttons joined into one control
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for many actions behind one More button

## Keyboard

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

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to or away from the button. A disabled button is skipped; a pending one keeps the focus. |
| `Enter` or `Space` | Presses the button. While it is pending, the press is ignored. |

## Behavior

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

- `IconButton`: 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.
- `Icon`: 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.
- `IconButtonTextCell`: 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

### When to use

- Use an IconButton for a frequent action with an unmistakable icon: close, edit, more options. When the icon alone could be misread, use a Button with a text label.

### Do

- Give every IconButton an aria-label that names the action: Delete invoice, not Trash. A tooltip is extra help, not the name.
- 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.
- Pass a label to IconButtonTextCell. Without it every row's button is announced as Action.
- 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.
- 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.
- 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

### IconButton

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with its own, or a function that returns them from the state of the button. Use it for a one-off colour, not for the size. |
| expanded | boolean |  | Marks a trigger whose menu or panel is open: sets `aria-expanded` and the pressed surface on the quiet variants. Leave it undefined when the button does not control a popup. |
| focusableWhenDisabled | boolean | false | Keeps a disabled button in the tab order, so a screen reader user can find it and read why it is disabled. |
| nativeButton | boolean | true | Whether the component renders a native `<button>`. Set it to `false` together with `render` when the element is not a button, such as an anchor. |
| pending | boolean |  | 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: `pending` shows a spinner, `success` a check, `error` a retry icon and turns a filled button red. Change the `aria-label` with the phase. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element, for example with a link: `render={<a href="/settings" />}` together with `nativeButton={false}`. Accepts an element or a function that returns one. |
| shape | "circle" \| "rounded" | "rounded" | `rounded` has a medium corner radius, `circle` is fully rounded. |
| size | "lg" \| "xl" \| "sm" \| "md" \| "2xl" | "md" | The side of the square: `sm` is 32 px, `md` 36, `lg` 40, `xl` 44 and `2xl` 48. The icon is 16, 18, 20, 22 and 24 px. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles, or a function that returns them from the state of the button. |
| variant | "plain" \| "gradient" \| "outline" \| "primary" \| "destructive" \| "light" \| "ghost" \| "brand" \| "dark" | "primary" | The look. `plain` is the ordinary icon button with its own box, `ghost` has no box and no fill until hover and belongs in toolbars, rows, fields and cards, `primary` and `gradient` are for the main action, `brand` is the brand fill, `dark` and `light` are for surfaces of the opposite tone, `outline` is an indigo-rimmed accent and `destructive` is red. |

Also accepts React.ButtonHTMLAttributes attributes.

### IconButtonTextCell

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The text beside the button. |
| icon* | ReactNode |  | The icon of the small plain button. |
| label | string |  | The accessible name of the button, such as `Edit Atlas redesign`. Without it the name is `Action` on every row. |
| onClick | () => void |  | Runs when the icon button is pressed. |

## Examples

### Appearance: nine variants

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

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

### Shape: rounded or circle

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

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

### Size: 32, 36, 40, 44 and 48 px

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

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

### States: default, hover, pressed, focus, disabled and loading

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

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

### Menu trigger: collapsed or expanded

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

export function Example() {
  return (
    <IconButton variant="plain" expanded={false} aria-label="More actions">
      <MoreHorizontal />
    </IconButton>
  )
}
```

### Async feedback: idle, pending, success and error

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

export function Example() {
  return (
    <IconButton variant="plain" aria-label="Copy link">
      <Link2 />
    </IconButton>
  )
}
```

### Name and tooltip: above, below or at the end

```tsx
import { Plus } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export function Example() {
  return (
    <Tooltip>
      <TooltipTrigger render={<IconButton variant="ghost" aria-label="Add member" />}>
        <Plus />
      </TooltipTrigger>
      <TooltipContent side="top">Add member</TooltipContent>
    </Tooltip>
  )
}
```

## In context

### Editor toolbar: ghost icon buttons in a bar

Every button has a name. Arrow keys move between the buttons, and Tab leaves the bar.

```tsx
import { AlignCenter, AlignLeft, AlignRight, Redo2, Undo2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"
import { Toolbar, ToolbarButton, ToolbarSeparator } from "@/components/ui/toolbar"

export function Example() {
  return (
    // 8 px buttons with 8 px of air sit in a 16 px bar
    <Toolbar aria-label="Editor" className="rounded-xl p-2">
      <ToolbarButton aria-label="Undo" className="size-9" render={<IconButton variant="ghost" />}>
        <Undo2 />
      </ToolbarButton>
      <ToolbarButton aria-label="Redo" className="size-9" render={<IconButton variant="ghost" />}>
        <Redo2 />
      </ToolbarButton>
      <ToolbarSeparator />
      <ToolbarButton aria-label="Align left" className="size-9" render={<IconButton variant="ghost" />}>
        <AlignLeft />
      </ToolbarButton>
      <ToolbarButton aria-label="Align center" className="size-9" render={<IconButton variant="ghost" />}>
        <AlignCenter />
      </ToolbarButton>
      <ToolbarButton aria-label="Align right" className="size-9" render={<IconButton variant="ghost" />}>
        <AlignRight />
      </ToolbarButton>
    </Toolbar>
  )
}
```

### Row actions: the name carries the row

The same three actions repeat on every row, so each name says what it acts on, such as Edit Atlas redesign.

```tsx
import { Pencil, Pin, Trash2 } from "lucide-react"
import { IconButton } from "@/components/ui/icon-button"

const ROWS = [
  { title: "Atlas redesign", person: "Nora Lindgren" },
  { title: "Q3 roadmap", person: "Daniel Okafor" },
  { title: "Onboarding flow", person: "Priya Raman" },
]

export function Example() {
  return (
    <ul className="divide-y divide-border overflow-hidden rounded-xl border border-border bg-card">
      {ROWS.map((row) => (
        <li key={row.title} className="flex items-center gap-4 py-2 pr-2 pl-4">
          <span className="text-sm font-medium">{row.title}</span>
          <span className="flex-1 text-sm text-text-secondary">{row.person}</span>
          {/* Every row repeats the same three actions, so the name carries the row. */}
          <IconButton variant="ghost" aria-label={`Edit ${row.title}`}>
            <Pencil />
          </IconButton>
          <IconButton variant="ghost" aria-label={`Pin ${row.title}`}>
            <Pin />
          </IconButton>
          <IconButton variant="ghost" aria-label={`Delete ${row.title}`}>
            <Trash2 />
          </IconButton>
        </li>
      ))}
    </ul>
  )
}
```

### Copy link: the button confirms itself

A check replaces the icon for two seconds, and the name and a status message say that the link was copied.

```tsx
import { useEffect, useRef, useState } from "react"
import { Link2 } from "lucide-react"
import { IconButton, type IconButtonPhase } from "@/components/ui/icon-button"

const NAME: Record<IconButtonPhase, string> = {
  idle: "Copy link",
  pending: "Copying link",
  success: "Link copied",
  error: "Copy failed, try again",
}

export function Example() {
  const [phase, setPhase] = useState<IconButtonPhase>("idle")
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined)

  useEffect(() => () => clearTimeout(timer.current), [])

  async function copy() {
    try {
      await navigator.clipboard.writeText("https://wunderui.com/s/q3-roadmap")
      setPhase("success")
      timer.current = setTimeout(() => setPhase("idle"), 2000)
    } catch {
      setPhase("error")
    }
  }

  return (
    <div className="flex items-center gap-2 rounded-xl border border-border-control bg-card p-2">
      <span className="min-w-0 flex-1 truncate px-2 text-sm text-text-secondary">wunderui.com/s/q3-roadmap</span>
      {/* The name changes with the phase and a status region tells screen readers the result. */}
      <IconButton variant="plain" size="sm" phase={phase === "idle" ? undefined : phase} aria-label={NAME[phase]} onClick={copy}>
        <Link2 />
      </IconButton>
      <span role="status" className="sr-only">
        {phase === "success" ? "Link copied" : ""}
      </span>
    </div>
  )
}
```

### Notifications: a counter or a dot on the corner

The badge sits on the corner and is hidden from screen readers, so the name carries the count.

```tsx
import { Bell } from "lucide-react"
import { BadgeCounter } from "@/components/ui/badge"
import { IconButton } from "@/components/ui/icon-button"

export function Example() {
  return (
    <span className="relative inline-flex">
      {/* The count is part of the name, because the badge is hidden from screen readers. */}
      <IconButton variant="plain" aria-label="Notifications, 3 unread">
        <Bell />
      </IconButton>
      <BadgeCounter overlay tone="danger" count={3} aria-hidden />
    </span>
  )
}
```

### Disclosure trigger: show and hide details

The expanded state sets aria-expanded and the pressed surface while the panel is open, and the chevron turns with it.

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

export function Example() {
  const [open, setOpen] = useState(false)

  return (
    <div className="rounded-xl border border-border bg-card p-2">
      <div className="flex items-center justify-between pl-2">
        <span className="text-sm font-medium">Atlas redesign</span>
        <IconButton
          variant="ghost"
          size="sm"
          aria-label="Project details"
          aria-controls="project-details"
          expanded={open}
          onClick={() => setOpen(!open)}
        >
          <ChevronDown className={open ? "rotate-180" : ""} />
        </IconButton>
      </div>
      <div id="project-details" hidden={!open} className="px-2 pt-2 pb-1 text-sm text-text-secondary">
        Owner Nora Lindgren, 12 tasks open, due Nov 30.
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("icon-button")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
