Pular para o conteúdo
Formulário

Checkbox

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

Estados

Selecionar todas

Dentro de campo

Você pode ler os termos completos antes de continuar.

Com rótulo

Importar
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

PropTipoPadrão
checked0.4.0

Se a caixa está marcada agora.

booleansem padrão
classNames0.5.0

Classe por parte: `box`, `indicator`, `label`.

Partial<Record<"box" | "indicator" | "label", string>>sem padrão
defaultChecked0.4.0

Se a caixa começa marcada.

booleanfalse
disabled0.4.0

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

booleanfalse
form0.4.0

Identifica o formulário dono do campo oculto.

stringsem padrão
indeterminate0.4.0

Se a caixa está no estado misto: nem marcada, nem desmarcada.

booleanfalse
inputRef0.4.0

Uma ref para o `<input>` oculto.

Ref<HTMLInputElement>sem padrão
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleanfalse
onCheckedChange0.4.0

Chamado 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.0

Se a caixa controla um grupo de caixas filhas.

booleanfalse
readOnly0.4.0

Se o usuário fica impedido de marcar ou desmarcar a caixa.

booleanfalse
render0.4.0

Troca 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.0

Se o usuário precisa marcar a caixa antes de enviar o formulário.

booleanfalse
uncheckedValue0.4.0

O valor enviado com o formulário quando a caixa está desmarcada.

stringsem padrão
value0.4.0

O valor da caixa.

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