Toggle Button

Overview

A toggle button is a button that stays pressed. Use it for a single binary choice that the user can turn on and off — like pinning an item, toggling a filter, or enabling an option. It shares the Button's geometry and interaction model, with five styles (filled, tonal, outlined, elevated, glass) and a selected state.

When the toggle carries an icon, show the outline form while unselected and the filled form once selected — pass them as icon and selectedIcon and the component swaps automatically.

Examples

Variants

Each style has a low-emphasis unselected state (top row) and a high-emphasis selected state (bottom row).

With icon

Pass an outline icon for the unselected state and a filled selectedIcon for the selected state; the toggle swaps between them. Use an icon size with an aria-label for icon-only toggles.

Sizes

Five sizes scale padding and label together — xs, sm (default), md, lg, xl, shared with the Button.

Radius

Four shapes via the shape prop: full (pill, default), rounded (12px), squared whose corner radius grows with the size, and none.

Installation

API Reference

Accessibility

• Renders a native <button type="button"> with aria-pressed reflecting the selected state.
• Control selected from your own state and flip it on onClick (see the demo above).
• Icon-only toggles (any icon size) must provide an aria-label describing the action.
• Reinforce the state beyond color: pass an outline icon and a filled selectedIcon so the change reads without relying on the fill alone.
• A visible focus ring (3px accent with a 2px offset) is provided via focus-visible.
• Shares the Button's size (xs–xl) and shape (full/rounded/squared) props.