ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.
ts
| Guidance | Practices |
|---|---|
| Do | Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example. |
| Do | Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change. |
| Do | Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set. |
| Don't | Don't use a ToggleButton for one-time actions like "Submit" or "Delete"; those are regular Buttons, not toggles. |
| Don't | Don't mix ToggleButtons with regular Buttons inside the same group; use only ToggleButtons in a ToggleButtonGroup. |
| Don't | Don't use a ToggleButton for on/off settings that persist across sessions; use a Switch instead, which better communicates "setting" semantics. |
Toggle buttons with colored icons in the pressed state. Shows accent-colored toolbar formatting and semantic reaction colors (yellow star, red heart, blue bookmark).
Icon-only toggle buttons that swap between outline and solid icons when pressed. Use for actions like favorite, bookmark, or mute where the icon itself communicates the state.
Toggle buttons with visible text labels that show a font weight shift on press. Use when the icon alone is not enough to communicate the action.
Default, pressed, disabled, and loading states of a standalone toggle button. Shows how visual treatment changes across states.