Toggle

At a glance

• A single bistable button — think of the B / I / U buttons in a rich-text toolbar.
• Cluster several with <Toggle.Group> for shared selection semantics (toolbar-multiple, alignment-single).
• ARIA: role="button" + aria-pressed per item. <Toggle.Group> adds role="group" (multiple) or role="radiogroup" (single).

Standalone Toggle

pressed and defaultPressed

Controlled mode: pass pressed and pair with onChange. Uncontrolled mode: pass defaultPressed and let the Toggle track state.

// Controlled
const [bold, setBold] = useState(false);
<Toggle pressed={bold} onChange={setBold}>B</Toggle>
 
// Uncontrolled
<Toggle defaultPressed>I</Toggle>

variant

Visual treatment of the toggle when off and on.

<Toggle variant="outline">Pin</Toggle>

size

Density. Aligned with Button's scale.

<Toggle size="sm">B</Toggle>

disabled

Greys the toggle out and blocks press handling. Forwarded as aria-disabled.

<Toggle disabled>Locked</Toggle>

aria-label / accessibilityLabel

When the visible content is just an icon, pass aria-label (web) or accessibilityLabel (native) so screen readers say something meaningful.

<Toggle aria-label="Bold"><BoldIcon /></Toggle>

<Toggle.Group>

Clusters several Toggle items with shared selection semantics. Roving-tabindex keyboard nav follows the WAI-ARIA radiogroup pattern: arrow keys move focus, Home / End jump to the ends, Space / Enter toggles the focused item. Default-variant grouped items share borders so the cluster reads as one segmented chip — first item rounds the left, last rounds the right.

type — multiple vs single

The shape of value follows from type:

Multiple selection (formatting toolbar)

type="multiple" — value is string[]. Clicking adds or removes an item from the array.

Single selection (alignment)

type="single" — value is string | undefined. Clicking sets it; clicking the active item again clears it.

value and defaultValue

Controlled (value + onChange) vs uncontrolled (defaultValue). Their shapes follow type.

<Toggle.Group type="multiple" value={['bold', 'italic']} onChange={setMarks}>
    <Toggle.Item value="bold">B</Toggle.Item>
    <Toggle.Item value="italic">I</Toggle.Item>
</Toggle.Group>
 
<Toggle.Group type="single" defaultValue="left">
    <Toggle.Item value="left">L</Toggle.Item>
    <Toggle.Item value="center">C</Toggle.Item>
    <Toggle.Item value="right">R</Toggle.Item>
</Toggle.Group>

onChange

Fires with the next value whenever the user toggles an item. Pair with value for controlled, omit for uncontrolled.

<Toggle.Group type="multiple" onChange={(marks) => editor.setMarks(marks)}>
    {/* … */}
</Toggle.Group>

disabled

Disables every item in the group. Individual items can still set their own disabled.

<Toggle.Group disabled type="single" defaultValue="bold">{/* … */}</Toggle.Group>

variant and size (group-level)

Forwarded to every item by default — set the cluster's look once and items inherit. Per-item variant / size overrides the group value.

<Toggle.Group variant="outline" size="sm" type="single">{/* … */}</Toggle.Group>

aria-label / accessibilityLabel

The group's accessible name. Required for assistive tech to announce the cluster ("Text formatting, group"). For icon-only items inside, give each item its own aria-label too.

<Toggle.Group aria-label="Text formatting" type="multiple">
    <Toggle.Item value="bold" aria-label="Bold">B</Toggle.Item>
    <Toggle.Item value="italic" aria-label="Italic">I</Toggle.Item>
</Toggle.Group>

Props

<Toggle>

<Toggle.Group>

<Toggle.Item>