Toggle Group

Toggle Group lets you present a set of related toggle controls that can be arranged horizontally or vertically and optionally enforce single‑ or multiple‑selection behavior.

When to use

• Use a Toggle Group when you need to let users switch one or more options on or off within a clearly related set.
• Choose the Toggle type for on/off switches that represent a binary state; choose Action when the toggles trigger an immediate action without representing state.
• Use Single selection mode for mutually exclusive choices, and Multiple when any combination of toggles may be active.
• Prefer a horizontal layout for space‑constrained interfaces and a vertical layout when you have longer labels.

When not to use

• Don’t use a Toggle Group for unrelated actions; separate them into independent buttons or controls.
• Don’t use it when you only need a single binary option—use a standalone Toggle instead.
• Avoid the None selection mode if the toggles represent state that users must see reflected; in that case, treat them as independent actions.
• Don’t disable the entire group unless the whole set is unavailable; disable individual toggles instead when only some options are inapplicable.

Anatomy

Variant	Description	When to use
type	Determines whether each item behaves as a stateful toggle (Toggle) or as an immediate action (Action).	Use Toggle for on/off state, Action for one‑off commands.
selectionMode	Controls how many items can be active at once.	Single for mutually exclusive choices, Multiple for combinable selections, None when items act independently.
orientation	Arranges the items in a row (Horizontal) or a column (Vertical).	Choose based on layout constraints and label length.
size	Sets the visual size of each toggle item.	Use Large for prominent controls, Medium or Small for tighter spaces.
isDisabled	Disables the entire group, preventing interaction.	Apply when the whole set is not applicable in the current context.

Props

Prop	Type	Default	Description
type	"Action" | "Toggle"	"Action"	Determines the behavior of each toggle item.
selectionMode	"None" | "Single" | "Multiple"	"None"	Sets how many items can be selected simultaneously.
orientation	"Horizontal" | "Vertical"	"Horizontal"	Aligns the toggle items horizontally or vertically.
size	"Large" | "Medium" | "Small"	"Large"	Defines the size of each toggle control.
isDisabled	"No" | "Yes"	"No"	Disables all interaction with the group when set to Yes.

Accessibility

• Use role="group" on the container and provide a clear aria-label or aria-labelledby that describes the purpose of the group.
• Each toggle item should have role="button" and an aria-pressed attribute that reflects its current on/off state.
• When isDisabled is Yes, set aria-disabled="true" on the group and ensure focus cannot move into its members.
• Support keyboard navigation: arrow keys move focus between toggles, and Space or Enter toggles the focused item’s state.
• Ensure sufficient contrast for all toggle states in both enabled and disabled appearances.

Changelog

• 2026-06-29 — Initial doc generated from Figma.