Checkbox

Marca ou desmarca uma opção, sozinha ou em lista.

O Checkbox registra uma escolha que vale ao enviar um formulário ou uma seleção em lista, como aceitar os termos ou escolher etapas. Para efeito imediato, use Switch.

import { Checkbox } from "@rastreio-x/ui";

Padrão

O rótulo vai dentro de Checkbox.Content, depois de Checkbox.Control. Clicar no texto também marca.

Li e aceito os termos

Variantes

primary é o padrão; secondary tem menos ênfase e funciona melhor sobre superfícies como cartões.

Primária

Secundária

Com descrição

Description acrescenta uma linha de apoio abaixo do rótulo.

Avisar quando o Pedido atrasarVocê recebe um e-mail por Pedido atrasado.

Estados

Desabilitada

Marcada e desabilitada

Inválida

Combine isInvalid e isRequired com FieldError. A mensagem diz o que fazer, não só que há erro.

Li e aceito os termosMarque a caixa para aceitar os termos.

Indeterminada

Use isIndeterminate na caixa-mãe quando só parte dos filhos está marcada.

Todas as etapas

Pedido Recebido

Em Trânsito

Entregue

Anatomia

Checkbox
├── Checkbox.Content
├── Checkbox.Control
└── Checkbox.Indicator

Checkbox.Content: a área clicável com o rótulo.
Checkbox.Control: a caixa.
Checkbox.Indicator: o traço de marcado ou indeterminado.

Propriedades

Checkbox
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<CheckboxFieldRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<CheckboxFieldRenderProps>`	`'react-aria-CheckboxField'`	Classes CSS aplicadas ao elemento.
`defaultSelected`	`boolean`	-	Estado selecionado inicial (não controlado).
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`id`	`string`	-	Identificador único do elemento.
`inputRef`	`React.Ref<HTMLInputElement \| null>`	-	Referência ao elemento `input`.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isIndeterminate`	`boolean`	-	Mostra o estado indeterminado, quando o progresso ou a seleção não é conhecido.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`isSelected`	`boolean`	-	Estado selecionado (controlado).
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((isSelected: boolean) => void)`	-	Chamada quando o valor ou a seleção muda.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`render`	`DOMRenderFunction<'div', CheckboxFieldRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<CheckboxFieldRenderProps>`	-	Estilos em linha aplicados ao elemento.
`validate`	`((value: boolean) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'primary' \| 'secondary'`	-	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).

Animações

CSS
indicativo

A caixa troca de cor e o traço é desenhado em cerca de 150 a 200 ms. Com prefers-reduced-motion (motion-reduce do tema e a folha global da fachada) o traço aparece sem animar.

Acessibilidade

Papel checkbox nativo com estado marcado, desmarcado ou misto (aria-checked="mixed").
Tab foca; Espaço alterna.
isRequired e isInvalid expõem aria-required e aria-invalid; FieldError vira a descrição do erro.
O nome acessível é o texto do rótulo; com rótulo externo, ligue por htmlFor.

Boas práticas

Faça

Rótulo afirmativo e específico: Avisar quando o Pedido atrasar.

Evite

Rótulo negativo ou duplo, como Não desejo deixar de receber avisos.

Escreva o rótulo de forma que marcado signifique ligado.
Não pré-marque aceite de termos; a pessoa precisa decidir.
Em listas longas, ofereça a caixa-mãe com estado indeterminado.
Para efeito imediato, prefira Switch.

Relacionados

Switch para configurações com efeito imediato.
RadioButtonGroup para escolha única.
TextField para outros campos de formulário.