Component · 23

Toggle

A button that stays pressed, like bold in an editor. Group several into one strip to pick one option or many. Exposed with aria-pressed; arrow keys move through a group. Built on Base UI.

Toggle

An icon-only toggle needs an aria-label.

tsx

<Toggle>Italic</Toggle>
<Toggle aria-label="Bold" defaultPressed>
  <BoldIcon />
</Toggle>
<Toggle disabled>Disabled</Toggle>

Sizes

tsx

<Toggle size="sm">Small</Toggle>
<Toggle size="md">Medium</Toggle>
<Toggle size="lg">Large</Toggle>

Group: pick one

One toggle is pressed at a time. Name the group with aria-label.

tsx

<ToggleGroup aria-label="Text alignment" defaultValue={["left"]}>
  <Toggle value="left">Left</Toggle>
  <Toggle value="center">Center</Toggle>
  <Toggle value="right">Right</Toggle>
</ToggleGroup>

Group: pick several

tsx

<ToggleGroup multiple aria-label="Text style" defaultValue={["bold"]}>
  <Toggle value="bold">Bold</Toggle>
  <Toggle value="italic">Italic</Toggle>
  <Toggle value="underline">Underline</Toggle>
</ToggleGroup>

Props

Prop	Type	Default	Description
Toggle pressed / defaultPressed / onPressedChange	boolean	false	Press it uncontrolled, or control it from state.
Toggle size	"sm" \| "md" \| "lg"	"md"	2rem, 2.5rem or 3rem tall.
Toggle value	string	-	Required inside a ToggleGroup: it is what the group reports.
Toggle disabled	boolean	false	Cannot be pressed or focused with the mouse.
ToggleGroup value / defaultValue	string[]	[]	The pressed toggles' values.
ToggleGroup onValueChange	(value: string[]) => void	-	Called with the new list of pressed values.
ToggleGroup multiple	boolean	false	Allow several to be pressed at once.
ToggleGroup orientation	"horizontal" \| "vertical"	"horizontal"	Which arrow keys move between toggles.
ToggleGroup disabled	boolean	false	Disable every toggle in the group.

Use a Switch for a setting that applies immediately, and Tabs when the choice swaps a panel of content. A Toggle is for a tool or a view option that is either on or off.