IconButton
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
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.
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:
npm install @heroicons/react@2.2.0