Pular para o conteúdo

Botões de alternância

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

Neste exemplo de justificativa de texto, temos opções de alternar os botões para a esquerda, centralizada, direita e texto totalmente justificado (desativado), com apenas um item disponível para seleção de cada vez.

Seleção múltipla

Múltipla seleção permite que opções logicamente agrupadas, como negrito, itálico e sublinhado, tenham várias opções selecionadas.

Tamanhos

Gosta de botões maiores ou menores? Use a propriedade size.

<ToggleButtonGroup size="small" {...control}>
  {children}
</ToggleButtonGroup>
<ToggleButtonGroup {...control}>{children}</ToggleButtonGroup>
<ToggleButtonGroup size="large" {...control}>
  {children}
</ToggleButtonGroup>

Botões verticais

Os botões podem ser empilhados verticalmente com a propriedade orientation definida para "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

Se você deseja forçar que pelo menos um botão esteja ativo, você pode adaptar sua função handleChange.

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

Aqui está um exemplo de customização do componente. Você pode aprender mais sobre isso na página de documentação de sobrescritas.


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é o momento, os botões de alternância estão na ordem DOM. Navegue entre eles com a tecla tab. O comportamento dos botões segue a semântica padrão do teclado.