# IconButton

- Page: https://jiguang132.com/resources/astryx/docs/icon-button
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Icon Button

A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.

| Prop | Type | Default | Description |
|---|---|---|---|
| label * | string |  | Accessible label. Used as aria-label (not rendered as visible text). |
| icon * | ReactNode |  | Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons. |
| variant | 'primary' \| 'secondary' \| 'ghost' \| 'destructive' | 'secondary' | Visual style variant. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Size variant. |
| elevation | 'none' \| 'low' \| 'med' \| 'high' | 'none' | Resting shadow depth. The most common FAB shape is an icon-only button, so raise it with `low`/`med`/`high` for a floating action button. `none` is the default flat button. |
| isLoading | boolean | false | Shows a loading spinner and disables interaction. |
| isDisabled | boolean | false | Disables the button. |
| tooltip | string |  | Tooltip text shown on hover. |
| onClick | (e: MouseEvent) => void |  | Standard click handler. |
| clickAction | (e: MouseEvent) => void \| Promise<void> |  | Async click handler with automatic loading state. |

### Usage guidance

- Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.
- Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.
- Use ghost in toolbars and dense areas to reduce visual clutter.
- Avoid: Use IconButton if the action isn't obvious from the icon alone; use Button with text.
- Avoid: Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.

### Accessibility

- **Essential icon or spinner arc**: IconButton has no visible label. Its icon must have at least 3:1 contrast with the button background in Rest, Hover, and Pointer down. The moving spinner arc must also meet 3:1 while loading. — 3:1
- **Visible control boundary**: The button edge needs 3:1 contrast only when users need it to see the control. — 3:1 if needed
- **Keyboard focus indicator**: The focus outline must have at least 3:1 contrast with the area around the button. Check the red outline on destructive buttons too. — 3:1
- **Disabled appearance**: Disabled controls do not need to meet these contrast ratios. — Not required


## Examples

- Icon Button: An icon button with a wrench icon.
- IconButton — Action Bar: Row of ghost icon buttons for a compact action toolbar
- IconButton — Floating: A floating action button (FAB). The most common floating-button shape is icon-only. Raised here with `elevation="high"`.
- IconButton — Loading State: Icon buttons that show a loading spinner on click for async feedback
- IconButton — With Tooltips: Icon buttons with tooltips that explain each action on hover

## Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

```bash
npm install @heroicons/react@2.2.0
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt