Icon button
StableA round button that holds a single icon, for compact actions in the header, toolbars and rows. It always carries a label: screen readers read it as the button's name, and a tooltip shows it to everyone else.
Playground
Change the props and watch the button. The playground starts on secondary so the circle shows at rest; the component's default is ghost, only a glyph until the pointer arrives.
<IconButton label="Notifications" variant="secondary"><BellIcon /></IconButton>Variants
The same six materials as Button, on a circle. ghost is the default, because icon buttons usually sit in groups where filled circles would crowd each other.
When to use each
| Variant | Use it for |
|---|---|
ghost | The default. Header and toolbar actions, row actions, anything that repeats. Quiet until hovered. |
secondary | Beside secondary pills, so the group reads as one set, e.g. More actions at the end of a row of buttons. |
soft | A toggle that is on, such as Bold in a formatting toolbar. Also quiet filled actions in dense toolbars. |
primary | Rarely: the view's one primary action where there is no room for words, such as Add product on a phone. |
inverse | Over photos and busy surfaces, e.g. removing an image from a product gallery. |
critical | A destructive action standing on its own. In a list of rows a ghost bin is calmer. Confirm first either way. |
In both themes
Every variant, light and dark side by side. Hover the ghost button to see its tint.
Sizes
The control scale shared with every control in the kit, so an icon button lines up with the pills and fields beside it. The button is always a circle: its width is its height.
| Size | Button | Icon | Use it for |
|---|---|---|---|
lg | 44px | 18px | Touch-first screens, where a finger needs the room. |
md | 36px | 16px | The default: the app header and page toolbars. |
sm | 30px | 15px | Table toolbars, card headers and panels. |
xs | 24px | 13px | Inside dense rows only, e.g. copying an order number. The smallest target WCAG 2.2 allows. |
In a table toolbar
Small icon buttons beside a small search field and a small pill: one height, one line.
With a tooltip
The label names the button for screen readers, but sighted people only see the icon. Wrap the button in a Tooltip that repeats the label, so hovering or tabbing to it says what it does. When the action has a keyboard shortcut, pass shortcut and the keys appear beside the words.
A tooltip opens after a short hover and straight away on keyboard focus. Once one is open, its neighbours open instantly, so moving along a toolbar is quick. Hover the header actions below.
In a toolbar
Group related icon buttons 4px apart and split the groups with a vertical Separator. For a button that switches something on and off, pass aria-pressed and switch it to soft while it is on. Try the formatting buttons.
Loading
While the action runs, a comet circles the button (teal on every material but primary), presses are ignored and focus stays put. Press the refresh button to see it.
Disabled
Drops to 45% and can no longer be focused, so a keyboard user never reaches its tooltip. Undo and redo are the fair use: when there is nothing to undo, the reason is obvious. Otherwise leave it enabled and explain the problem when it is pressed.
Guidelines
- Label with a verb and the thing it acts on: "Delete product", "Copy order number", "Print packing slip". Name the action, not the picture.
- One icon, one meaning across Orbit: a bin always deletes and a pencil always edits.
- Tooltips go where there is room: below in the top bar, above in rows and footers.
- Keep icon buttons in a group 4px apart and split groups with a vertical separator.
Accessibility
labelis required and becomes the button'saria-label. The icon is hidden from assistive tech.- A tooltip is not the name. While it is open it is linked to the button as a description, so keep it the same as the label, plus the shortcut if there is one.
- Toggles take
aria-pressed, so screen readers announce them as on or off. - Renders a native button, so Enter and Space press it. The teal focus ring is 2px, offset from the circle, and shows for keyboard focus only.
- While loading it uses
aria-busyandaria-disabled, notdisabled, so focus is not lost mid-action. xsis 24px, the smallest target WCAG 2.2 allows. Leave space around it.
Props
Also accepts every native button attribute, such as aria-pressed and type.
| Prop | Type | Default | Description |
|---|---|---|---|
labelRequired | string | None | The button's accessible name, set as aria-label. Name the action. |
childrenRequired | ReactNode | None | The icon. The button sizes it: 13, 15, 16 or 18px. |
variant | ButtonVariant | 'ghost' | The material, as on Button: primary, secondary, soft, ghost, inverse or critical. |
size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | A circle 24, 30, 36 or 44px across. |
loading | boolean | false | Comet in orbit, the spinner in the icon's place, presses ignored, focus kept. |
disabled | boolean | None | Native disabled. It can no longer be focused. |
asChild | boolean | false | Render your element (a router link) as the round button. Put the icon inside it: <IconButton asChild label="Help"><Link to="/help"><QuestionIcon /></Link></IconButton>. |