Prepared Docs

Overview

IconToggle expresses a binary state (muted/unmuted, pinned/unpinned, visible/hidden) in a single square control. It belongs in toolbars and inspector chrome where labeled buttons would crowd the layout—similar to platform toggle icons that must still announce their outcome clearly to assistive technology. Because the glyph does the signalling, choose the pattern only when the icon is universally understood or the state lives next to another signal that clarifies it (a persistent sidebar open/closed state, a map visibility toggle shown in the legend).

When to use

Toolbar and inspector toggles with universally understood glyphs (play/pause, pin, visibility, mute).
Settings that take effect immediately—no separate submit step.
State toggles that pair with another visible surface reflecting the state (a panel that opens, a layer that shows on the map).

When not to use

Multi-state mode pickers with more than two values—use SegmentedControl or Select.
Destructive or irreversible actions—use an explicit Button with Modal confirmation.
Cases where operators can't infer meaning from the icon alone—use a labeled Switch or Checkbox.

Types

type={IconToggleType.Secondary} renders a compact toolbar toggle sized for floating toolbars—for example, the four mode toggles inside the staff panel's FAB toolbar. Unchecked uses the Alt icon color with a subtle hover background; checked fills the control with --color-intent-accent-bg and paints the glyph with --color-icon-base.

Shape

IconToggle ships with the standard icon-toggle corner radius by default across every IconToggleType. Pass the boolean pill prop to opt in to a fully rounded (pill / circular) border radius for floating toolbars and FAB-style controls (e.g. the staff panel FAB toolbar). pill composes with any IconToggleType; combine it with type={IconToggleType.Secondary} to reproduce the FAB-toolbar variant, which pairs naturally with IconButton's pill prop.

Content guidelines

title and tooltip describe the result of clicking, not the glyph: "Mute microphone", not "Microphone icon". Localize with formatMessage.
Keep the pressed-state label consistent with the product's vocabulary. A toggle that says "Mute" when unpressed and "Unmute" when pressed makes the state switch part of the label.

Behavior and states

Pressed vs. unpressed. Pressed styling must be obvious in both themes; never rely on color alone.
Controlled state. Reflect the source of truth from the parent store; desync between the toggle and the underlying feature is a top source of confusion.
Disabled. Surface the blocker in the tooltip when non-obvious.

Best practices

Reserve IconToggle for toolbars and compact contexts in dispatch overlays.
Keep one toggle per concern. Don't overload a single icon with long-press extras unless the pattern is trained across the product.
Ensure the pressed glyph or fill reads clearly at the toggle's smallest size.

Don't

Hide safety-critical state exclusively behind an ambiguous icon.
Nest toggles inside toggles.
Allow the pressed and unpressed glyphs to collapse visually when viewed quickly.

Accessibility

Keyboard operable with a visible focus ring, the correct aria-pressed state for the button's toggle semantics, and announced state changes. See Accessibility for the full contract.

Icon button for one-shot actions.
Switch for labeled binary settings in forms.
Toolbar for grouping toggles with related actions.
Toggle group for a cluster of exclusive or multi-state toggles.

Icon Button / Accessibility

Icon Toggle / API and Development

Overview

When to use

Toolbar and inspector toggles with universally understood glyphs (play/pause, pin, visibility, mute).
Settings that take effect immediately—no separate submit step.
State toggles that pair with another visible surface reflecting the state (a panel that opens, a layer that shows on the map).

When not to use

Multi-state mode pickers with more than two values—use SegmentedControl or Select.
Destructive or irreversible actions—use an explicit Button with Modal confirmation.
Cases where operators can't infer meaning from the icon alone—use a labeled Switch or Checkbox.

Types

Shape

Content guidelines

title and tooltip describe the result of clicking, not the glyph: "Mute microphone", not "Microphone icon". Localize with formatMessage.
Keep the pressed-state label consistent with the product's vocabulary. A toggle that says "Mute" when unpressed and "Unmute" when pressed makes the state switch part of the label.

Behavior and states

Pressed vs. unpressed. Pressed styling must be obvious in both themes; never rely on color alone.
Controlled state. Reflect the source of truth from the parent store; desync between the toggle and the underlying feature is a top source of confusion.
Disabled. Surface the blocker in the tooltip when non-obvious.

Best practices

Reserve IconToggle for toolbars and compact contexts in dispatch overlays.
Keep one toggle per concern. Don't overload a single icon with long-press extras unless the pattern is trained across the product.
Ensure the pressed glyph or fill reads clearly at the toggle's smallest size.

Don't

Hide safety-critical state exclusively behind an ambiguous icon.
Nest toggles inside toggles.
Allow the pressed and unpressed glyphs to collapse visually when viewed quickly.

Accessibility

Keyboard operable with a visible focus ring, the correct aria-pressed state for the button's toggle semantics, and announced state changes. See Accessibility for the full contract.

Icon button for one-shot actions.
Switch for labeled binary settings in forms.
Toolbar for grouping toggles with related actions.
Toggle group for a cluster of exclusive or multi-state toggles.

Icon Button / Accessibility

Icon Toggle / API and Development