Checkbox — Sinapse Design System

Aceito os termos de uso

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>
  )
}

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

<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

Instale o Checkbox da sua stack e rode o comando individual ITpS em seguida. O comando itps add checkbox é theme-only: ele valida o slug e confirma que o contrato visual vem do tema ITpS, das classes copy-first e dos snippets desta página.

terminal · React/Next

pnpm dlx shadcn@latest add checkbox
pnpm dlx github:ITPS/sinapse-ui-cli add checkbox

terminal · Vue3/Nuxt4

pnpm dlx shadcn-vue@latest add checkbox
pnpm dlx github:ITPS/sinapse-ui-cli add checkbox

O comando individual adapta só este componente; não instala o catálogo inteiro.

Uso

Em React/Next com shadcn/ui e Vue3/Nuxt4 com shadcn-vue, use o Checkbox instalado pela stack. O tema ITpS vem dos tokens aplicados pela CLI, 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 Vue3/Nuxt4	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.

Aceito os termos de uso

Você precisa aceitar os termos para continuar.

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