# IconButton

> A compact button that shows only an icon and always carries an accessible label.

Category: Actions · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/icon-button

Use IconButton for frequent, well-understood actions where space is tight: close, copy, more options, row actions in tables. The label prop is required and becomes both the accessible name and the native tooltip. If the meaning of the icon is not obvious, use a Button with text instead.

## Import

```tsx
import { IconButton, Icon } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Icon, IconButton } from '@bindshq/stance-react';

export function Basic() {
  return <IconButton label="Copy signature HTML" icon={<Icon name="copy" />} variant="outline" />;
}
```

### Variants

```tsx
import { Icon, IconButton } from '@bindshq/stance-react';

export function Variants() {
  return (
    <div style={{ display: 'flex', gap: 12 }}>
      <IconButton variant="primary" label="Add user" icon={<Icon name="plus" />} />
      <IconButton variant="secondary" label="Filter" icon={<Icon name="filter" />} />
      <IconButton variant="outline" label="Download" icon={<Icon name="download" />} />
      <IconButton variant="ghost" label="More options" icon={<Icon name="more-horizontal" />} />
      <IconButton variant="danger" label="Delete" icon={<Icon name="trash" />} />
    </div>
  );
}
```

### Sizes

```tsx
import { Icon, IconButton } from '@bindshq/stance-react';

export function Sizes() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
      <IconButton size="xs" variant="outline" label="Edit" icon={<Icon name="pencil" />} />
      <IconButton size="sm" variant="outline" label="Edit" icon={<Icon name="pencil" />} />
      <IconButton size="md" variant="outline" label="Edit" icon={<Icon name="pencil" />} />
      <IconButton size="lg" variant="outline" label="Edit" icon={<Icon name="pencil" />} />
    </div>
  );
}
```

### Circle shape

```tsx
import { Icon, IconButton } from '@bindshq/stance-react';

export function Shapes() {
  return (
    <div style={{ display: 'flex', gap: 12 }}>
      <IconButton
        shape="circle"
        variant="secondary"
        label="Previous"
        icon={<Icon name="chevron-left" />}
      />
      <IconButton
        shape="circle"
        variant="secondary"
        label="Next"
        icon={<Icon name="chevron-right" />}
      />
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| IconButton | `label` (required) | `string` | None | Accessible name; also used as the title tooltip. |
| IconButton | `icon` (required) | `ReactNode` | None | The icon to show, usually <Icon name="…" />. |
| IconButton | `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'ghost'` | Visual emphasis. |
| IconButton | `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Square size: 24, 32, 40 or 48px. |
| IconButton | `shape` | `'default' \| 'circle'` | `'default'` | Rounded square or circle. |
| IconButton | `loading` | `boolean` | `false` | Shows a spinner and blocks clicks. |
| IconButton | `hideTitle` | `boolean` | `false` | Drop the native title when wrapped in a Tooltip. |
| IconButton | `...props` | `ButtonHTMLAttributes` | None | Native button attributes. |

## Accessibility

- label is required by the type system, so icon-only buttons can never ship without an accessible name.
- The icon is aria-hidden; the label is announced instead.
- Use the xs size only inside dense layouts with enough spacing to meet the 24px minimum target (WCAG 2.5.8).

## Keyboard

| Keys | Action |
| --- | --- |
| `Enter` | Activates the button. |
| `Space` | Activates the button. |

## Guidelines

**Do**

- Use universally understood icons: close, search, copy, more.
- Pair with a Tooltip for richer hints.

**Don’t**

- Use an icon-only button for a primary, uncommon action.

## Related

- https://stanceui.com/components/button
- https://stanceui.com/components/tooltip
- https://stanceui.com/components/icon