Pular para o conteúdo
Ações

ToggleGroup

/componentes/toggle-group.mdmarkdown cru, para quem lê com agent em vez de olho

Escolha única

Escolha múltipla

Desabilitado

Importar
import { ToggleGroup } from '@rivocode/ui'

Quando usar

Barra de botões que ficam apertados, para escolha que muda a vista na hora: alinhamento, modo de exibição, filtro rápido.

Com multiple, vira seleção múltipla.

Sempre um apertado: required

Por padrão, clicar no botão que já está apertado o solta, e o grupo fica vazio. Num filtro rápido isso é o "nenhum filtro"; num modo de exibição, é uma tela sem modo. Com required, o único apertado não se solta, e a escolha só muda clicando em outro:

<ToggleGroup defaultValue={['lista']} required>
  <Toggle value="lista">Lista</Toggle>
  <Toggle value="grade">Grade</Toggle>
</ToggleGroup>

Comece com um valor em value ou defaultValue: o required segura o que está apertado, e não escolhe por você. Com multiple, ele segura só o último.

Quando não usar

Para ações irmãs que não guardam estado (salvar, duplicar, excluir lado a lado), use ButtonGroup: o grupo daqui diz no aria que um botão ficou apertado, e uma ação não fica. Um modo isolado, que liga e desliga sem irmãos, é Toggle sozinho.

Quando cada opção mostra um painel de conteúdo próprio, use Tabs, que liga cada aba ao seu painel para o leitor de tela. Configuração que vale na hora e fica gravada é Switch, e a escolha de formulário que só vale ao enviar é RadioGroup ou Select.

No React Native

Traduz: o @rivocode/ui-native exporta ToggleGroup - items na raiz, cada um com icon (e iconOnly para o botão só de ícone); multiple para vários e required para nunca ficar vazio, os mesmos nomes e o mesmo sentido do web; label dá nome ao grupo e classNames.item veste cada botão. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.

API

PropTipoPadrão
defaultValue0.4.0

Os botões pressionados do grupo, como a lista dos valores deles.

readonly string[]sem padrão
disabled0.4.0

Se o grupo ignora a interação do usuário.

booleanfalse
loopFocus0.4.0

Se o foco do teclado volta ao primeiro item ao chegar no fim da lista pelas setas.

booleantrue
multiple0.4.0

Com `false`, só um item do grupo fica pressionado.

booleanfalse
onValueChange0.4.0

Chamado quando os botões pressionados do grupo mudam.

((groupValue: string[], eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)sem padrão
orientation0.4.0Orientation"horizontal"
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, ToggleGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
required

Exige um apertado: clicar no unico que esta apertado nao o solta, e o grupo nunca fica vazio.

booleansem padrão
value0.4.0

Os botões pressionados do grupo, como a lista dos valores deles.

readonly string[]sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.