Toggle group

v1.0.0 | View in Storybook

​

When to use

• 2–4 options that are mutually exclusive and always visible.
• The current selection needs to be immediately obvious.

​

When to use something else

• More than ~4–5 options: use Select or Menu.
• Options fire one-off commands: use Button or grouped buttons, not a Toggle group.
• Multi-select filters: use Checkbox or filter chips (Badge / closeable patterns).
• Single-select filter of a small set: use Segmented control.
• Page navigation: use Tabs or routing, not Toggle group.

​

Dos and don’ts

• Do keep labels short — one or two words per option or use icons only.
• Don’t mix icons and text labels across options in the same group — be consistent.

​

Behavior

• Selection updates immediately; supports single or multi-select per configuration. Do not use for destructive one-shot actions without confirmation.

​

Often used with

Toolbar formatting tools; Tooltip when icon-only; mutually exclusive or multi-select state next to the canvas or preview it affects.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Outline

Use the outline variant when toggle buttons should read as distinct, bordered controls—for example, formatting tools in a toolbar or view options in a compact row.

​

All variants

Compare toggle group variants to choose the style that best matches surrounding controls—default, outline, and ghost each suit different density and emphasis levels.

​

Composed content

Combine icons and labels within toggle items when both improve clarity—for example, text formatting options where the icon reinforces the label.

​

Sizes

Choose the size that matches surrounding controls—use smaller toggles in dense toolbars and larger toggles when the group is a primary control.

​

Controlled

Use a controlled toggle group when selection must follow application logic—for example, syncing with canvas state, URL parameters, or a parent settings panel.

​

Accessibility

Ensure toggle items expose pressed state to assistive technologies, support keyboard navigation between options, and provide accessible names for icon-only toggles.

​

Disabled

Disable individual toggles or the entire group when options are temporarily unavailable, and explain why in a tooltip or helper text.

​

Edge cases

Review edge cases—such as single-item groups, all-disabled states, or overflow—to ensure the toggle group remains usable in constrained layouts.