Icon button

Anatomy

Variants

• ghost (default): a bare icon with no container. Use it in toolbars, headers, and rows. Unlike a ghost Button, its icon and hover tint are neutral, not accent.
• secondary: a filled square, for an icon action that needs the weight of a visible control.
• outline: a bordered square, for a visible edge on a busy surface or in a joined Button group. Its border is light, so don't place it on a sunken surface such as a neutral Banner or Section message; use ghost or secondary there.
• primary: the main quick action of a bar. Use at most one filled icon button per bar.

Danger

tone="danger" marks an action that deletes or removes something. It has one look, a red square with a red icon, whatever variant you set.

An icon gives no words at the moment of the click, so a danger icon button must open a confirmation, such as a confirm Dialog that names what will be deleted. Never delete on the first click.

Shape

shape="round" makes a circle. It works with every variant, tone, and size. A joined button group or a Split button sets the corners itself.

Sizes

The squares match Button's heights, so mixed rows line up. small is exactly the 24px minimum target size, so don't scale it, give it a negative margin, or let anything overlap it. The button sizes the icon to 16px at every size.

States

Hover, press, and focus need no props. Keyboard focus shows a ring on every icon button.

• disabled: the button can't be focused or clicked, and a danger button turns gray. Prefer keeping the button active.
• loading: a spinner replaces the icon, the square stays the same, and repeat clicks are ignored. The button stays focusable, keeps its label, and tells screen readers it's busy. If you also set disabled, the button is disabled.
• pressed: the on state of a toggle; see below.

Toggle

For on and off actions, such as bookmark, favorite, mute, or pin, set pressed. Put the filled twin of the icon in the pressed slot and the button swaps them.

• pressed sets aria-pressed. A button without the prop is not announced as a toggle.
• The label names the action, never the state: "Mute", not "Muted". Screen readers add "pressed" themselves, so a label that flips reads backwards.
• You control pressed. The button never flips it and fires no change event. Listen for click and set it, or wrap the button in Toggle button, which does it for you.
• Every variant except primary adds a tint while pressed. Without a pressed icon, the tint alone shows the state.
• Don't combine pressed with tone="danger".

Tooltip

Wrap an icon button in a label Tooltip so sighted users see its name on hover and focus. Leave out the tooltip's text: it shows the button's label, so the two never disagree.

Do it for any icon that isn't obvious. A bare icon button with a label is still accessible.

When to use

• Use an icon button for an action whose icon everyone knows: close, search, settings, more, favorite. Check that with your users, not only your team.
• Use it where space is tight: toolbars, headers, table rows, card corners.
• Use a Button with a text label otherwise. People learn text faster than icons.
• To open a menu, use a Menu with an icon button as its trigger.

Content

label is required. It is the accessible name, and the button warns in the console when it is missing.

• Name the action: "Search", "Rename", "Copy link". Not the icon ("Pencil") and not the state ("Muted").
• Follow Button's label rules: a verb, sentence case, no articles, no end punctuation.
• Use one label per icon across the product. The same icon shouldn't mean "Pin" in one place and "Save" in another.
• In a danger label, name what is deleted: "Delete file".
• Don't use title for the name. Keyboard and touch users never see it.

More in Action labels.

Do / Don't

Related

• Button: the same button with a visible label.
• Toggle button: wraps an icon button and flips pressed for you.
• Tooltip: shows the label on hover and focus.
• Menu: uses an icon button as its trigger.
• Spinner: the indicator loading shows.
• Icon: what the slots take.

API

Attributes

Slots

Events

No custom events. Listen for click; disabled and loading block it.

CSS

• ::part(button): the native <button>.
• --tk-button-radius: sets the corners; it overrides shape. For components that join buttons, such as Button group.

Tokens

state/* tokens are translucent tints laid over the button's rest color. Pressed buttons use state/on (state/on-hover under the pointer) with an icon/default glyph, plus border/selected on outline. The focus ring is border/accent/focus on every button. Values per theme: Color.

Accessibility

Built in:

• A native <button>: Tab reaches it, Space and Enter activate it, forms see it.
• label becomes the accessible name; slotted icons are hidden from screen readers.
• pressed sets aria-pressed, which stays under disabled and loading.
• loading sets aria-busy and keeps the name.
• A focus ring for keyboard users that is never hidden.
• Every size is at least 24×24px.

Your part:

• Check that people understand the icon; if in doubt, use a Button with text.
• Write the label as the action, and keep it the same when pressed changes.
• Open a confirmation before a danger action runs.
• Wrap icons that aren't obvious in a label Tooltip.

Contrast limits

• Outline border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. With no label or fill, the border is all that shows the button. On a sunken surface in light, it disappears.
• Pressed toggle: in light and dark, on looks the same as hover; high contrast tells them apart. Screen readers always hear the state; the pressed icon makes it visible.