Toggle Button

A Toggle Button can be used to group related options.

To emphasize groups of related Toggle buttons, a group should share a common container. The ToggleButtonGroup controls the selected state of its child buttons when given its own value prop.

Exclusive selection

With exclusive selection, selecting one option deselects any other.

In this example, text justification toggle buttons present options for left, center, right, and fully justified text (disabled), with only one item available for selection at a time.

Note: Exclusive selection does not enforce that a button must be active. For that effect see enforce value set.

Multiple selection

Multiple selection allows for logically-grouped options, like bold, italic, and underline, to have multiple options selected.

Size

For larger or smaller buttons, use the size prop.

<ToggleButtonGroup size="small" {...control} aria-label="Small sizes">
  {children}
</ToggleButtonGroup>
<ToggleButtonGroup {...control} aria-label="Medium sizes">
  {children}
</ToggleButtonGroup>
<ToggleButtonGroup size="large" {...control} aria-label="Large sizes">
  {children}
</ToggleButtonGroup>

<ToggleButtonGroup size="small" {...control} aria-label="Small sizes">
  {children}
</ToggleButtonGroup>
<ToggleButtonGroup {...control} aria-label="Medium sizes">
  {children}
</ToggleButtonGroup>
<ToggleButtonGroup size="large" {...control} aria-label="Large sizes">
  {children}
</ToggleButtonGroup>

Press Enter to start editing

Color

<ToggleButtonGroup
  color="primary"
  value={alignment}
  exclusive
  onChange={handleChange}
  aria-label="Platform"
>
  <ToggleButton value="web">Web</ToggleButton>
  <ToggleButton value="android">Android</ToggleButton>
  <ToggleButton value="ios">iOS</ToggleButton>
</ToggleButtonGroup>

<ToggleButtonGroup
  color="primary"
  value={alignment}
  exclusive
  onChange={handleChange}
  aria-label="Platform"
>
  <ToggleButton value="web">Web</ToggleButton>
  <ToggleButton value="android">Android</ToggleButton>
  <ToggleButton value="ios">iOS</ToggleButton>
</ToggleButtonGroup>

Press Enter to start editing

Vertical buttons

The buttons can be stacked vertically with the orientation prop set to "vertical".

<ToggleButtonGroup
  orientation="vertical"
  value={view}
  exclusive
  onChange={handleChange}
>
  <ToggleButton value="list" aria-label="list">
    <ViewListIcon />
  </ToggleButton>
  <ToggleButton value="module" aria-label="module">
    <ViewModuleIcon />
  </ToggleButton>
  <ToggleButton value="quilt" aria-label="quilt">
    <ViewQuiltIcon />
  </ToggleButton>
</ToggleButtonGroup>

<ToggleButtonGroup
  orientation="vertical"
  value={view}
  exclusive
  onChange={handleChange}
>
  <ToggleButton value="list" aria-label="list">
    <ViewListIcon />
  </ToggleButton>
  <ToggleButton value="module" aria-label="module">
    <ViewModuleIcon />
  </ToggleButton>
  <ToggleButton value="quilt" aria-label="quilt">
    <ViewQuiltIcon />
  </ToggleButton>
</ToggleButtonGroup>

Press Enter to start editing

Enforce value set

If you want to enforce that at least one button must be active, you can adapt your handleChange function.

<span class="token keyword">const</span> <span class="token function-variable function">handleAlignment</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">event<span class="token punctuation">,</span> newAlignment</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
  <span class="token keyword">if</span> <span class="token punctuation">(</span>newAlignment <span class="token operator">!==</span> <span class="token keyword">null</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token function">setAlignment</span><span class="token punctuation">(</span>newAlignment<span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> <span class="token function-variable function">handleDevices</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">event<span class="token punctuation">,</span> newDevices</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
  <span class="token keyword">if</span> <span class="token punctuation">(</span>newDevices<span class="token punctuation">.</span>length<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    <span class="token function">setDevices</span><span class="token punctuation">(</span>newDevices<span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>

Standalone toggle button

<ToggleButton
  value="check"
  selected={selected}
  onChange={() => {
    setSelected(!selected);
  }}
>
  <CheckIcon />
</ToggleButton>

<ToggleButton
  value="check"
  selected={selected}
  onChange={() => {
    setSelected(!selected);
  }}
>
  <CheckIcon />
</ToggleButton>

Press Enter to start editing

Customization

Here is an example of customizing the component. You can learn more about this in the overrides documentation page.

Accessibility

ARIA

ToggleButtonGroup has role="group". You should provide an accessible label with aria-label="label", aria-labelledby="id" or <label>.
ToggleButton sets aria-pressed="<bool>" according to the button state. You should label each button with aria-label.

Keyboard

At present, toggle buttons are in DOM order. Navigate between them with the tab key. The button behavior follows standard keyboard semantics.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.