All components (204)
Icon button
Actions · IconButton
What it is and when to use it
A button that carries only an icon: the three dots of a row, the X of a panel, the plus of "add". It is a square native <button> (as wide as it is tall) and, unless told otherwise, ghost and neutral. It accepts the look of Button (variant, tone, size) and shape (default, pill or circle), but not startIcon, endIcon or fullWidth: the icon is the content and the button is square.
When to use it
- Actions that repeat a lot and are recognized by their icon, where text would eat up the space: close, copy, more actions.
- Several in a row inside a
Toolbar, which leaves them as a single Tab stop.
When not to
- If the icon is not understood on its own, use text:
ButtonwithstartIcon. - If it leads to another page, it is a link:
ButtonLink. - To open an actions menu:
ActionMenu, which already comes with its three-dot button.
Keyboard: Tab reaches it; Enter and Space press it. With disabled it leaves the Tab order.
Accessibility: aria-label is required by the types: with no visible text, it is the button's only name for the screen reader and for voice control. It should say the action and on what ("Close the order panel"), not the drawing ("X"). With a finger, it is never smaller than 44 × 44 px.
Fine-tuning: the --amset-button-* variables of Button; --amset-button-icon is the size of the icon and --amset-button-height, that of the button.
What it looks like
<IconButton aria-label="View cart"><CartIcon /></IconButton>
<IconButton aria-label="New product" variant="solid" shape="circle"><MoreIcon /></IconButton>
<IconButton aria-label="Remove from order" tone="error" variant="soft"><CrossIcon /></IconButton>Props
Import it with import { IconButton } from '@amset/ui'. Required props are marked.
| Prop | Type | What it does |
|---|---|---|
aria-labelrequired | string | Required: without visible text, this provides the name. |
childrenrequired | ReactNode | The icon. It is the only thing that is seen. |
className | string | — |
disabled | boolean | Out of play: it cannot be pressed, cannot be focused and is not in the tab order. |
excludeFromTabOrder | boolean | Out of the tab order but pressable. For a button that duplicates something already in it: the one that opens the list of a search field, which does nothing the down arrow does not. |
fullWidth | boolean | Takes the whole available width, with the icon in the center. |
onClick | MouseEventHandler<HTMLButtonElement> | — |
onPress | PressHandler | — |
shape | "circle" | "default" | "pill" | The shape: `default` (default), `pill` or `circle`, the round icon-only button. |
size | "sm" | "md" | "lg" | — |
style | CSSProperties | Inline style. The stable look goes in the `--amset-button-*` CSS variables, which is what is maintained; this is for what is only known at run time: a colour chosen by whoever uses the application, a calculated position, a height that depends on the content. It used to be forbidden and had to be opened: a real front end used it on 40 buttons to calculate their halo from an arbitrary colour (AMS-735), and without it the only way out was to write CSS by hand against our classes. |
tone | "neutral" | "accent" | "secondary" | "tertiary" | "info" | "success" | "warning" | "error" | What it means. Without it, a solid or soft button is `accent` (the main action) and an outline or ghost one is `neutral`. `error` is the one for deleting or cancelling an account. |
variant | "solid" | "soft" | "outline" | "ghost" | How it is drawn: `ghost` (the default), `solid`, `soft` or `outline`. |
It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.
In the test bench
Every state and variant, to try one at a time, on its page at ui.amset.tech: