CheckboxGroup
Formas aceitas
Com a caixa de todas
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
| Prop | Tipo | Padrão |
|---|---|---|
allValues0.4.0Os nomes de todas as caixas do grupo. | string[] | sem padrão |
defaultValue0.4.0Os nomes das caixas do grupo que começam marcadas. | string[] | sem padrão |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
onValueChange0.4.0Chamado 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.0Troca 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.0Os 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.