# Checkbox

Controle para consentimento, seleção múltipla e opções submetidas em formulário.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Forms
- Status: stable
- Relacionados: /componentes/switch.md, /componentes/field.md

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componentes padrão do shadcn (`checkbox`) com o tema Sinapse: cores, fonte e raio vêm do tema, e as variantes `itps-*` desta página existem só no HTML.

**React/Next (shadcn/ui)**

```tsx
import { Checkbox } from '@/components/ui/checkbox'

export function CheckboxExample() {
  return (
    <div className="flex items-center gap-2">
      <Checkbox id="terms" />
      <label
        htmlFor="terms"
        className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
      >
        Aceito os termos de uso
      </label>
    </div>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import { Checkbox } from '@/components/ui/checkbox'
</script>

<template>
  <div class="flex items-center gap-2">
    <Checkbox id="terms" />
    <label
      for="terms"
      class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
    >
      Aceito os termos de uso
    </label>
  </div>
</template>
```

**HTML (copy-first)**

```html
<label class="itps-checkbox">
  <input
    id="terms"
    name="terms"
    type="checkbox"
    class="itps-checkbox__input"
  />
  <span class="itps-checkbox__box" aria-hidden="true">
    <i class="itps-checkbox__check ti ti-check" aria-hidden="true"></i>
  </span>
  <span class="itps-checkbox__label">Aceito os termos de uso</span>
</label>
```

## Instalação

O comando instala o Checkbox da sua stack com o tema Sinapse. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/checkbox
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/checkbox.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use o `Checkbox` instalado pela stack. O tema Sinapse vem dos tokens instalados pelo CLI do shadcn ou do shadcn-vue, então o exemplo deve continuar simples e próximo da documentação oficial.

Use `itps-checkbox` quando precisar do contrato copy-first em HTML ou wrappers finos. O input continua nativo; a caixa visual só reflete foco, seleção, erro e desabilitado.

## Exemplos

### Estados

| Estado | React/Next e Vue 3/Nuxt 4 | HTML |
|--------|--------------------------|------|
| Selecionado inicial | `defaultChecked` ou valor controlado | `checked` no input |
| Desabilitado | `disabled` | `disabled` no input |
| Inválido | `aria-invalid="true"` | `is-invalid` no label e `aria-invalid="true"` no input |

Associe mensagens de ajuda ou erro com `aria-describedby`. Para valor controlado em React/Vue, siga o padrão da stack em vez de copiar as classes `.itps-checkbox`.

### Grupo

Use `fieldset` e `legend` quando a lista tiver um rótulo coletivo. Em formulário HTML, cada checkbox do grupo deve ter o mesmo `name` e um `value` próprio; no shadcn, controle a lista selecionada pelo estado da aplicação.

| Peça | Uso copy-first |
|------|----------------|
| `itps-checkbox-group` | Wrapper vertical para um grupo de opções. |
| `itps-checkbox-group__legend` | Título do grupo dentro do `fieldset`. |
| `name` | Mesmo nome para opções da mesma lista. |
| `value` | Valor enviado quando aquela opção está marcada. |

### Validação

Quando o checkbox for obrigatório, mostre a mensagem com `itps-field__error` e conecte a mensagem pelo `aria-describedby`.

**HTML (copy-first)**

```html
<div class="itps-field">
  <label class="itps-checkbox is-invalid">
    <input
      id="terms-required"
      name="terms-required"
      type="checkbox"
      required
      aria-invalid="true"
      aria-describedby="terms-required-error"
      class="itps-checkbox__input"
    />
    <span class="itps-checkbox__box" aria-hidden="true">
      <i class="itps-checkbox__check ti ti-check" aria-hidden="true"></i>
    </span>
    <span class="itps-checkbox__label">Aceito os termos de uso</span>
  </label>
  <p id="terms-required-error" class="itps-field__error">
    <i class="ti ti-alert-circle" aria-hidden="true"></i>
    <span>Você precisa aceitar os termos para continuar.</span>
  </p>
</div>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-checkbox` | Label clicável que envolve input, caixa visual e texto. |
| `itps-checkbox__input` | Input nativo visualmente oculto. |
| `itps-checkbox__box` | Caixa visual sincronizada com o input. |
| `itps-checkbox__check` | Ícone decorativo de seleção. |
| `itps-checkbox__label` | Texto visível da opção. |
| `itps-checkbox-group` | Wrapper vertical para listas de opções. |
| `itps-checkbox-group__legend` | Título do grupo dentro do `fieldset`. |
| `is-invalid` | Estado inválido aplicado ao label. |
| `checked` | Estado selecionado inicial do input nativo. |
| `disabled` | Bloqueia interação. |
| `aria-invalid="true"` | Comunica erro quando há mensagem conectada. |
| `aria-describedby` | Liga o input à mensagem de erro ou apoio. |

## Acessibilidade

Mantenha o `<input type="checkbox">` no DOM para preservar foco, teclado e envio em formulário. Use `Space` para alternar, `disabled` para bloquear interação e `aria-invalid` apenas quando houver uma mensagem de erro conectada. Para preferência com efeito imediato, use `Switch`; para seleção submetida em formulário, use `Checkbox`.