icon button

An icon button is a button that shows only an icon, in the same kinds and sizes. Its label is required: it isn't drawn, but it becomes the button's accessible name.

when to use

• In tight places where a text label doesn't fit: a toolbar, the header of a card or a panel, a table row. In a table row, keep it to one or two; more go into an action menu.
• For actions people recognise from the icon alone: copy, refresh, close, delete.
• Next to a field or a title, for a small action on it, such as copying a value or opening a log.

when to use something else

• When there is room for a label, or for the main action of the screen. Use a button with a label, and the icon before it if it helps. A word is read faster than an icon is worked out.
• For a setting that is on or off. Use a switch. The icon button has no pressed look.
• For more than three or four actions side by side. Put them in a toolbar, and let the rest go into an action menu.
• For several actions on every row of a table. Give each row one action menu, and put the actions for several rows in a selection toolbar. Selection and bulk actions shows how.
• To go somewhere. Use a link. A button that changes the page breaks “open in new tab” and the browser's back button.

anatomy

1. Frame. A square with a thin border, in one of three sizes. The icon sits in its centre.
2. Icon. The picture of the action, sized to match the button. While the button is busy, a spinner takes its place.
3. Label. Not drawn. It is the button's name, and the browser shows it in a small box of its own while the pointer rests on the button.

variants and states

An icon button comes in the same four kinds as a button. Only the emphasized one is filled with colour, because it marks the next step.

Icon buttons come in three sizes, the same three as every other control. The small one suits table rows and dense toolbars, the medium one is the usual choice, and the large one sits beside a large input or button. Match the height of the controls next to it.

While its action runs, an icon button is busy: a spinner takes the icon's place, and further presses are ignored. Its size stays the same. A disabled icon button is dimmed, and the keyboard passes over it.

In a toolbar, keep the actions quiet, with one emphasized action at most.

behaviour

• An icon button acts on the current screen when it is pressed: with a click or a tap, or with enter or space on the keyboard.
• A busy or disabled icon button ignores presses.
• While the mouse pointer rests on it, the browser shows the label in a small box of its own, after a short delay. It never shows on keyboard focus or on touch.

The full keyboard map is on the icon button's React page.

accessibility

• The label is required, and it is the button's whole name. Write it exactly as it should be read.
• The browser shows the same words as its own tooltip. Assistive technology may read them a second time, as a description. That tooltip has none of our styling, and it appears only on mouse hover.
• People who see the screen but use a keyboard or a touch screen never see the label. Use icons whose meaning is not in doubt, or a button with a visible label.
• The icon is decoration, hidden from assistive technology: the label names the action.
• A screen reader may not announce that the button is busy. When the outcome matters, announce it elsewhere, in a toast for instance.
• Keyboard focus shows as the same outline that every control uses. Interaction explains it.

Today:

• A busy icon button is disabled, and a focused button that becomes disabled can lose focus. People who pressed it with a keyboard or a screen reader can be moved off it while it loads.
• There is no pressed state. For on and off, use a switch.
• Don't wrap an icon button in a tooltip. The tooltip's wrapper is a tab stop of its own, so the pair takes two tab stops. The description lands on the wrapper instead of the button, and the browser's own tooltip still appears.

content

• The label is an action, verb first, in lowercase: “restart worker”, “copy link”, “delete volume”. Name the action, not the icon, so not “arrow” or “trash”.
• When the button repeats on every row or card, name the object too: “delete api-7f9c”, not “delete”. Otherwise a screen reader's list of buttons is a column of identical names.
• One icon, one meaning, everywhere. An icon that stands for two actions can no longer be read as either.

do and don't

related

• Button: the same action, with a visible label.
• Toolbar: where icon buttons usually live, with a menu for the rest.
• Action menu: several actions behind one button, such as one menu per table row.
• Iconography: which icons to use, and at what size.

specs

• Frame: square (border-radius: 0), a 1px border, the icon centred.
• Icon: the child you pass, such as <Icon icon={RotateCw} />. The button doesn't size it: Icon is 16px by default, which suits md, and the sizes example passes size={12} at sm and size={20} at lg (see iconography). It is hidden from assistive tech.
• Label: label, required. It becomes aria-label, and the native title that the browser shows as its own tooltip.
• Busy: loading. A spinner in place of the icon, the size unchanged, aria-busy="true". The button is disabled while busy, so it ignores presses and leaves the tab order.
• Disabled: disabled. 45% opacity, a not-allowed cursor, out of the tab order.
• Focus: the 2px --focus-ring outline, 1px outside the frame, on keyboard focus only.
• Motion: background, border and icon colours change in 120ms ease.
• Pressed: no pressed look today.