componentes / checkbox

Checkbox

Checkbox acessível com rótulo, texto de ajuda e de erro, estado indeterminado e cores.

Como usar

Um `<input type="checkbox">` nativo (então formulários, `ref` e teclado funcionam) com visual próprio. Passe `label` para a linha inteira ser clicável e `indeterminate` para um pai com só alguns filhos marcados.

preview

Aceito os termos

NewsletterUm e-mail por semana

Selecionar tudo

Checkbox.tsx

import { Checkbox } from "vaiperui";
 
<Checkbox label="Aceito os termos" />
<Checkbox
  defaultChecked
  label="Newsletter"
  helperText="Um e-mail por semana"
/>
<Checkbox indeterminate label="Selecionar tudo" />

Cores

preview

primary

success

warning

danger

cores.tsx

<Checkbox defaultChecked variantColor="primary" label="primary" />
<Checkbox defaultChecked variantColor="success" label="success" />
<Checkbox defaultChecked variantColor="warning" label="warning" />
<Checkbox defaultChecked variantColor="danger" label="danger" />

Tamanhos

preview

tamanhos.tsx

<Checkbox defaultChecked size="sm" label="sm" />
<Checkbox defaultChecked size="md" label="md" />
<Checkbox defaultChecked size="lg" label="lg" />

Indeterminado

`indeterminate` mostra um traço, para um checkbox pai com só alguns filhos marcados.

preview

Selecionar tudo

indeterminate

indeterminado.tsx

<Checkbox indeterminate label="Selecionar tudo" />

Estados

preview

ajudaDetalhe extra

ajuda

erroIsto é obrigatório

erro

desabilitado

desabilitado ✓

estados.tsx

<Checkbox label="ajuda" helperText="..." />
<Checkbox label="erro" errorMessage="..." />
<Checkbox label="desabilitado" disabled />
<Checkbox label="desabilitado" disabled defaultChecked />

Cor personalizada

`customColor` aceita qualquer cor CSS, ou um par `{ light, dark }`.

preview

Laranja

Violeta

cor-personalizada.tsx

<Checkbox defaultChecked customColor="#ff6600" label="Laranja" />
<Checkbox defaultChecked customColor={{ light: "#7c3aed", dark: "#a78bfa" }} label="Violeta" />

Props

Prop	Valores	Padrão	Descrição
variantColor	primary \| success \| warning \| danger	primary	Cor do estado marcado e do anel de foco
customColor	string \| { light, dark }	nenhum	Qualquer cor CSS (ou um par por tema). Substitui o variantColor
size	sm \| md \| lg	md	Tamanho do controle e do texto
radius	none \| sm \| md \| lg \| full	sm	Arredondamento dos cantos da caixa
animation	none \| smooth \| fast \| bounce	smooth	Transição ao alternar
label	ReactNode	nenhum	Texto ao lado do controle; clicar nele alterna
helperText	string	nenhum	Linha secundária abaixo do rótulo
errorMessage	string	nenhum	Texto de erro; só a presença dele já força o estado de erro
indeterminate	boolean	false	Mostra um traço no lugar do check
(nativas)	InputHTMLAttributes<HTMLInputElement>	nenhum	checked, defaultChecked, onChange, name, value, disabled, required, aria-*, className, ref etc.

Acessibilidade

Renderiza um `<input type="checkbox">` nativo (oculto visualmente, com a caixa customizada desenhada por cima), então papel, alternância com Space e comportamento em formulários são nativos.
O `<label>` envolve o input, então o texto do rótulo dá o nome e a linha inteira é clicável.
`indeterminate` define a propriedade `indeterminate` do DOM, que tecnologias assistivas leem como "misto".
`errorMessage` define `aria-invalid="true"`; `aria-describedby` aponta para o erro, ou para o `helperText` quando não há erro.
Os ícones de check e traço são `aria-hidden`; o estado é exposto só pelo input nativo.

Teclado

Tecla	Ação
Space	Alterna o checkbox.

Tenha em mente

Sem `label`, passe `aria-label`; o controle não tem outro nome.
`indeterminate` é só estado visual: o clique continua resultando em marcado ou desmarcado, e você decide o que isso significa.