Pular para o conteúdo

Toggle button

Os botões de alternância podem ser usados para agrupar opções relacionadas.

Para enfatizar grupos de botões de alternância relacionados, o grupo deve ter um contêiner em comum. O ToggleButtonGroup controla o estado selecionado de seus botões filhos através de sua propriedade value.

Seleção exclusiva

Com seleção exclusiva, selecionar uma opção desseleciona qualquer outra.

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.

Seleção múltipla

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

Tamanho

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>

Cor

<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>

Botões verticais

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>

Forçar valor definido

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

const handleFormat = (event, newFormats) => {
  if (newFormats.length) {
    setFormats(newFormats);
  }
};

const handleAlignment = (event, newAlignment) => {
  if (newAlignment !== null) {
    setAlignment(newAlignment);
  }
};

Botão de alternância autônomo

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

Botão de alternância customizado

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


Acessibilidade

ARIA

  • ToggleButtonGroup possui role="group". Você deve fornecer um rótulo acessível com aria-label="label", aria-labelledby="id" ou <label>.
  • ToggleButton define aria-pressed="<bool>" de acordo com o estado do botão. Você deve rotular cada botão com aria-label.

Teclado

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