Pular para o conteúdo
Formulário

CheckboxGroup

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

Formas aceitas

Com a caixa de todas

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

Quando usar

Grupo de caixas de marcar que compartilham um valor em lista.

Ganha o que caixas soltas não tem: com allValues, a caixa de "todos" marca e desmarca o grupo inteiro e mostra o estado misto sozinha, sem ninguém contar filho na mão.

<CheckboxGroup defaultValue={['pix', 'boleto']} aria-label="Formas aceitas">
  <Checkbox name="forma" value="pix">Pix</Checkbox>
  <Checkbox name="forma" value="boleto">Boleto</Checkbox>
  <Checkbox name="forma" value="cartao">Cartão</Checkbox>
</CheckboxGroup>

O name é o mesmo em todas, porque é um campo só; o value é o que distingue uma opção da outra e é o que entra na lista do grupo.

O rótulo vai como filho, e nunca num <span> ao lado: com filho a caixa sai dentro de um <label> que ela mesma monta, e clicar no texto marca. Um <label> escrito à mão em volta funciona no navegador e desfaz o trabalho da peça, e é uma das poucas coisas que o contrato lista em "nunca faça".

Para o "selecionar todas", passe allValues com a lista inteira e marque a caixa mestra com parent:

<CheckboxGroup allValues={['pix', 'boleto', 'cartao']} defaultValue={['pix']}>
  <Checkbox parent>Todas</Checkbox>
  <Checkbox name="forma" value="pix">Pix</Checkbox>
  …
</CheckboxGroup>

Sem o parent a caixa de cima vira só mais uma opção: ela não lê o grupo, não mostra o estado misto, e marcar as três não a marca. É o defeito mais fácil de não notar aqui, porque a tela parece certa até alguém marcar metade da lista.

Quando não usar

Para uma opção só entre várias, use RadioGroup: a caixa diz "marque quantas quiser", e um grupo de caixas que aceita uma só ensina errado. Configuração que vale na hora, sem enviar formulário, é Switch.

Lista longa, ou vinda do servidor, não cabe em caixas: escolher sem ver o resto é Combobox com multiple, e montar um conjunto vendo o que ficou de fora é TransferList.

No React Native

Traduz com items na raiz e value: string[], em vez de um Checkbox por filho, e sem o allValues/parent do web: a caixa mestra fica fora do grupo, e é um Checkbox com indeterminate quando parte da lista está marcada.

O label é o aria-label do web com outro nome, pelo mesmo motivo do RadioGroup: a lista de caixas responde uma pergunta, e sem o nome do conjunto cada caixa se apresenta sem dizer qual. Nomear liga junto o papel de lista, porque no React Native não existe papel de group e uma View sem papel nenhum não carrega nome.

API

PropTipoPadrão
allValues0.4.0

Os nomes de todas as caixas do grupo.

string[]sem padrão
defaultValue0.4.0

Os nomes das caixas do grupo que começam marcadas.

string[]sem padrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
onValueChange0.4.0

Chamado quando uma caixa do grupo é marcada ou desmarcada.

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

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

ComponentRenderFn<HTMLProps, CheckboxGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
value0.4.0

Os nomes das caixas do grupo que estão marcadas.

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.