Checkbox

Visão geral

Checkbox é construído sobre @radix-ui/react-checkbox. Ele suporta os três estados canônicos - unchecked, checked e indeterminate - via a prop checked do Radix, que aceita true | false | "indeterminate". O indicador renderiza um CheckIcon do lucide.

Use o Checkbox quando o valor faz parte de um envio de formulário (aceite de termos, filtros multi-select, seleção de linhas de tabela). Prefira o Switch quando a mudança tem efeito imediato, sem envio (notificações on / off, dark mode).

Preview

'use client';import { Checkbox, Label } from '@gremorie/rx-forms';export function CheckboxPreview() {  return (    <div className="flex items-center gap-2">      <Checkbox id="cb-demo" defaultChecked />      <Label htmlFor="cb-demo">Subscribe to the changelog</Label>    </div>  );}

Anatomia

Checkbox   4×4 rounded box; renders the check glyph when checked

Instalação

Uso

import { Checkbox, Label } from "@gremorie/rx-forms";

export function Example() {
  return (
    <div className="flex items-center gap-2">
      <Checkbox id="terms" />
      <Label htmlFor="terms">Accept terms and conditions</Label>
    </div>
  );
}

API

<Checkbox>

Encaminha todas as props para CheckboxPrimitive.Root e renderiza um CheckboxPrimitive.Indicator com um CheckIcon dentro. O atributo data-state (unchecked, checked, indeterminate) guia a superfície visual.

Composição

1. Sempre pareie com um <Label> via htmlFor correspondendo ao id do checkbox. O label é o affordance que a maioria dos usuários clica.
2. Dentro de um <Form>, use <FormField> com <FormControl> para que o wiring de ARIA aconteça automaticamente.
3. Para padrões de "select all", leve o checkbox mestre para indeterminate quando alguns (mas não todos) os filhos estão checked.

Variações

Com label e descrição

O padrão canônico de formulário: checkbox, label e uma linha de helper opcional. Clicar no label alterna o controle.

'use client';import { Checkbox, Label } from '@gremorie/rx-forms';export function CheckboxWithLabelPreview() {  return (    <div className="flex items-start gap-3">      <Checkbox id="cb-terms" defaultChecked />      <div className="grid gap-1.5 leading-none">        <Label htmlFor="cb-terms">Accept terms and conditions</Label>        <p className="text-sm text-muted-foreground">          You agree to our Terms of Service and Privacy Policy.        </p>      </div>    </div>  );}

States

Os três estados canônicos - unchecked, checked e indeterminate - lado a lado. Indeterminate renderiza o indicador de traço e anuncia como "mixed".

'use client';import { Checkbox, Label } from '@gremorie/rx-forms';export function CheckboxStatesPreview() {  return (    <div className="flex flex-col gap-3">      <div className="flex items-center gap-2">        <Checkbox id="cb-unchecked" />        <Label htmlFor="cb-unchecked">Unchecked</Label>      </div>      <div className="flex items-center gap-2">        <Checkbox id="cb-checked" defaultChecked />        <Label htmlFor="cb-checked">Checked</Label>      </div>      <div className="flex items-center gap-2">        <Checkbox id="cb-indeterminate" defaultChecked="indeterminate" />        <Label htmlFor="cb-indeterminate">Indeterminate</Label>      </div>    </div>  );}

"Select all" indeterminate

O checkbox mestre vira indeterminate quando alguns filhos estão selecionados. Clicá-lo deve limpar todos quando indeterminate / checked, e selecionar todos quando unchecked.

function SelectAll({ items, selected, onChange }) {
  const allSelected = selected.length === items.length;
  const someSelected = selected.length > 0 && !allSelected;

  return (
    <div className="flex items-center gap-2">
      <Checkbox
        id="select-all"
        checked={allSelected ? true : someSelected ? 'indeterminate' : false}
        onCheckedChange={(value) => {
          onChange(value === true ? items.map((i) => i.id) : []);
        }}
      />
      <Label htmlFor="select-all">Select all</Label>
    </div>
  );
}

Disabled

Label lê peer-disabled e esmaece automaticamente quando o checkbox irmão marcado com peer está disabled. O Checkbox.Root do Radix inclui a classe peer, então tanto o estado travado unchecked quanto o checked permanecem legíveis.

'use client';import { Checkbox, Label } from '@gremorie/rx-forms';export function CheckboxDisabledPreview() {  return (    <div className="flex flex-col gap-3">      <div className="flex items-center gap-2">        <Checkbox id="cb-disabled-off" disabled />        <Label htmlFor="cb-disabled-off">Disabled, unchecked</Label>      </div>      <div className="flex items-center gap-2">        <Checkbox id="cb-disabled-on" disabled defaultChecked />        <Label htmlFor="cb-disabled-on">Disabled, checked</Label>      </div>    </div>  );}

Acessibilidade

• Semântica nativa: o Radix renderiza role="checkbox" com aria-checked refletindo o estado (true, false, mixed para indeterminate).
• Teclado: Space alterna o checkbox; Tab / Shift+Tab movem o foco.
• Associação de label: clicar no <Label> alterna o checkbox via o mecanismo padrão htmlFor.
• Indeterminate: aria-checked="mixed" é anunciado como "mixed" pelos leitores de tela, sinalizando seleção parcial.
• Required + invalid: combine required com aria-invalid="true" e uma mensagem de erro; o ring destructive entra automaticamente.

Relacionados

• Switch - toggle de efeito imediato (vs seleção de envio de formulário)
• Radio Group - primo de single-select
• Label - o companheiro canônico
• Form - conecte o Checkbox no react-hook-form