# Icon button

A button that shows a familiar glyph in place of words, named by a required label.

* Kind: component
* Name: IconButton
* Page: https://design.werklist.com/components/icon-button
* Version: 2.1.2

## When to use it

* An action whose glyph people read at once: close, search, copy, download, more actions, menu, the theme switch.
* Toolbars, headers and table rows where words would crowd the space.
* Quiet by default. Secondary for an action that must be found without pointing, such as copy beside a field.
* Toggle: a quiet icon button with aria-pressed, such as a details panel shown or hidden.
* A row action: one small More actions button that opens the row menu.

## When not to use it

* A glyph people would have to guess: use a button with words.
* A destructive action as a glyph alone, or a red glyph: use a confirmation or Undo.
* A glyph with a visible text label next to it: use a button with an icon before its label.
* Changing the label when a toggle turns on.
* A native title attribute as the tooltip.

## Anatomy

* Box: 32, 40 or 44 px square, radius 8 px (--radius-lg)
* Glyph: 16 px in the small box, 20 px in the medium and large boxes, stroke 1.75 on a 24 unit grid, currentColor, aria-hidden
* Space from glyph to edge: 8, 10 or 12 px
* Tooltip: The label, 8 px below the box, after 500 ms of pointer rest or at once on keyboard focus, never on touch. Hidden from screen readers, which read aria-label.
* Focus ring: outline 2 px, offset 2 px (--focus-ring, --focus-ring-width, --focus-ring-offset)
* Touch target: 44 px on coarse pointers. Neighbors keep their centers at least 44 px apart and their boxes at least 4 px apart
* Counter: drawn by the Counter component at the top trailing corner, digits aria-hidden, the count joined to the name

## Variants

* quiet: The default: no fill until hover, glyph in muted ink. The only variant that toggles.
* secondary: A gray fill, for an action that must be visible without pointing.

## Sizes

* sm: height 32 px, padding 8 px around a 16 px glyph
* md: height 40 px, padding 10 px around a 20 px glyph
* lg: height 44 px, padding 12 px around a 20 px glyph

## States

* rest: Quiet: no fill, glyph in muted ink. Secondary: gray fill, glyph in text ink. (--text-muted, --surface-control, --text)
* hover: The hover fill over the ground or the gray fill, glyph in text ink. Only on a pointer that can hover. (--glass-fill-hover, --text)
* pressed: The hover fill, on touch too, and a scale of 0.94 unless motion is reduced. (--duration-fast, --ease-standard)
* focus-visible: Outline 2 px at offset 2 px in the focus ring color, and the tooltip shows. (--focus-ring, --focus-ring-width, --focus-ring-offset)
* disabled: aria-disabled true, focusable, presses canceled, drawn at opacity 0.5 in the colors of its variant.
* toggle on: aria-pressed true: --seg-selected fill, glyph in text ink. On hover --glass-fill-hover lies over it. (--seg-selected, --text, --glass-fill-hover)

## Keyboard

* Tab, Shift+Tab: Move focus in document order, disabled icon buttons included.
* Enter, Space: Press, or flip aria-pressed on a toggle.
* Down arrow, Up arrow: On an icon button with aria-haspopup menu, open the menu at its first or last item.

## Accessibility

* A native button whose accessible name is its label.
* The glyph is aria-hidden. No title attribute is added.
* Glyph on fill at 3 to 1 and focus ring at 3 to 1 in every enabled state and both themes.
* The name does not change with the toggle state. aria-pressed carries the state.
* Targets of 44 px on coarse pointers.
* Forced colors: the glyph takes ButtonText, the toggle on state Highlight, focus an outline in Highlight.

## Content

* The label is a verb and its object: Close panel, Copy link, More actions.
* The tooltip repeats the label word for word.
* A count joins the name: Notifications, 3 unread.

## Tokens

* --text
* --text-muted
* --surface-control
* --glass-fill-hover
* --seg-selected
* --focus-ring
* --focus-ring-width
* --focus-ring-offset
* --radius-lg
* --duration-fast
* --ease-standard