Checkbox
Estados
Selecionar todas
Dentro de campo
Você pode ler os termos completos antes de continuar.
Com rótulo
import { Checkbox } from '@rivocode/ui'Quando usar
Caixa de marcar.
indeterminate é o estado misto: alguns itens marcados, nem todos. É o que a
caixa de "selecionar todas" mostra quando parte da lista está selecionada.
Sem rótulo visível ao lado, passe aria-label.
O rótulo
Passe o texto como filho e a caixa sai dentro de um <label>, então clicar no
texto também marca:
<Checkbox defaultChecked>Avisar por e-mail quando um pedido sair</Checkbox>
Sem filho, sai só a caixa, e o arranjo fica com quem monta a tela. Use assim
quando o rótulo tiver estrutura própria: um título com descrição embaixo, um
link no meio da frase. Nesse caso, o <label> em volta é seu, e é ele que faz
o clique no texto valer.
O className veste a raiz: com texto, o <label> que leva a caixa e o texto,
e é ele que posiciona a peça inteira; sem texto, a própria caixa. A caixa tem a
parte dela, classNames.box.
A caixa marcada
A caixa marcada pinta accent-text, e não accent, com o tique em
surface-raised. É a mesma troca do trilho do Switch, e pelo mesmo motivo:
com a lima cheia o preenchimento media 1,21:1 sobre a página no tema claro e
1,26:1 sobre o cartão, abaixo dos 3:1 que a WCAG 1.4.11 pede para controle sem
texto. Com accent-text a fronteira da caixa mede 5,55:1 sobre a página e
5,75:1 sobre o cartão, e o tique mede 5,75:1 dentro do preenchimento. O estado
misto usa o mesmo par de tokens.
Quem escreve tema de cliente herda a garantia sem fazer nada: accent-text já
precisa de 4,5:1 sobre bg, surface e surface-raised, e contraste é
simétrico - é a mesma medida que a fronteira e o tique usam.
Desabilitado
Desabilitado se pinta com token, e não com opacidade: o fundo passa a
surface-raised e o visto vai para fg-disabled. Vale marcada, desmarcada e no
estado misto: o desabilitado vence o indeterminate.
A borda desce um degrau, para border-disabled. Os dois vizinhos não serviam:
border dá 1,3:1 contra o próprio preenchimento e a caixa travada sumiria, e
border-strong (a fronteira de controle nos 3:1 da WCAG 1.4.11) deixaria
travada igual a viva. O token do meio existe para esta faixa, e é o único par da
casa com teto além de piso: pelo menos 1,6:1 contra o fundo, e a fronteira viva
pesando 1,4 vez mais. A 1.4.11 dispensa controle inativo dos 3:1, e é essa folga
que ele ocupa.
Isso importa mais onde não há rótulo. Numa coluna de seleção do DataTable, uma
caixa desmarcada e travada não tem texto apagado ao lado para dizer o estado. E
surface e surface-raised são a mesma branca no tema claro, então o
preenchimento também não diz nada. Sobrava a borda, e ela não dizia.
Quando não usar
Para o ajuste que vale na hora (notificação que liga, modo escuro, recurso que
a conta passa a ter), use Switch. A caixa promete um Salvar depois; a chave
promete que já valeu. Uma caixa de marcar numa tela de preferências sem botão
de salvar deixa a pessoa esperando por um botão que não existe.
Para escolher uma opção entre várias que se excluem, é RadioGroup: caixa que
desmarca a irmã ao ser marcada é um rádio malfeito.
No React Native
Traduz, com um porém que morde na primeira linha: no nativo o Checkbox é sempre controlado. checked e onCheckedChange são obrigatórios e não há defaultChecked. Copiar <Checkbox defaultChecked>Receber novidades</Checkbox> do web não compila.
O terceiro estado atravessa. indeterminate desenha um traço na caixa cheia e anuncia mixed ao leitor de tela; ele vence o checked no desenho, e o toque marca tudo. A caixa de selecionar-todas se monta à mão, porque o parent do web não existe lá: indeterminate quando parte da lista está marcada, checked quando toda.
O nome falado é label, no lugar do aria-label do web, o mesmo nome que as outras peças nativas usam. Com children ele é opcional e troca o texto que o leitor de tela lê; sem children ele é obrigatório, e o tipo recusa a caixa sem os dois - a de marcar uma linha de lista seria anunciada só como "caixa de seleção, marcado". Dentro do FormField, o forChecked já entrega o label.
As partes vestem pelo mesmo classNames do web: box, indicator (o tique ou o traço) e label.
API
| Prop | Tipo | Padrão |
|---|---|---|
checked0.4.0Se a caixa está marcada agora. | boolean | sem padrão |
classNames0.5.0Classe por parte: `box`, `indicator`, `label`. | Partial<Record<"box" | "indicator" | "label", string>> | sem padrão |
defaultChecked0.4.0Se a caixa começa marcada. | boolean | false |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
form0.4.0Identifica o formulário dono do campo oculto. | string | sem padrão |
indeterminate0.4.0Se a caixa está no estado misto: nem marcada, nem desmarcada. | boolean | false |
inputRef0.4.0Uma ref para o `<input>` oculto. | Ref<HTMLInputElement> | sem padrão |
name0.4.0Identifica o campo quando o formulário é enviado. | string | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
onCheckedChange0.4.0Chamado quando a caixa é marcada ou desmarcada. | ((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void) | sem padrão |
parent0.4.0Se a caixa controla um grupo de caixas filhas. | boolean | false |
readOnly0.4.0Se o usuário fica impedido de marcar ou desmarcar a caixa. | boolean | false |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, CheckboxRootState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
required0.4.0Se o usuário precisa marcar a caixa antes de enviar o formulário. | boolean | false |
uncheckedValue0.4.0O valor enviado com o formulário quando a caixa está desmarcada. | string | sem padrão |
value0.4.0O valor da caixa. | string | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.