Checkbox

Recipe React distribuída como source, com comportamento Base UI e classes/tokens públicos do Checkbox TIS.

Preview funcional

Executado pela recipe React distribuída via shadcn e baseada em Base UI.

Carregando preview funcional…

Anatomia

Option label 1 2 3 4

1 Label (.ds-checkbox-label) — envolve checkbox + texto, estende área de clique.
2 Input (.ds-checkbox) — <input type="checkbox"> nativo estilizado.
3 Checkmark — pseudo-elemento CSS, visível quando marcado.
4 Traço indeterminado — pseudo-elemento CSS, visível quando indeterminate = true.

Padrão

Unchecked Checked

Indeterminado

Select all

Tamanhos

Small (16px) Medium (20px, default) Large (24px)

Grupo com erro

Select at least one option Option A Option B Please select at least one option.

Desabilitado

Disabled unchecked Disabled checked

Estados

State	CSS trigger	Visual change	Token
Unchecked	---	Neutral box fill and border	`component.checkbox.box.fill.unchecked.default`, `component.checkbox.box.border-color.unchecked.default`
Unchecked hover	`:hover`	Darker neutral box border/fill	`component.checkbox.box.fill.unchecked.hover`, `component.checkbox.box.border-color.unchecked.hover`
Checked	`:checked`	Primary box fill with checkmark	`component.checkbox.box.fill.checked.default`, `component.checkbox.mark.fill.checked.default`
Checked hover	`:checked:hover`	Darker primary box fill	`component.checkbox.box.fill.checked.hover`, `component.checkbox.mark.fill.checked.hover`
Indeterminate	`:indeterminate`	Primary box fill with indeterminate mark	`component.checkbox.box.fill.indeterminate.default`, `component.checkbox.mark.fill.indeterminate.default`
Focus	`:focus-visible`	2px outline ring	`component.checkbox.focus-ring.radius.default + component.focus-ring.*`
Error group	`.ds-checkbox-group--error`	Error border on controls and message below group	`component.checkbox.box.border-color.unchecked.error`, `semantic.feedback.error.content-default`
Disabled	`[disabled]`	Muted box, mark and label	`component.checkbox.box.fill.*.disabled`, `semantic.content.disabled`

Propriedades Figma

Propriedade	Tipo	Padrão	Descrição
`Show Label`	Boolean	`true`	Exibe ou oculta o label do controle
`Label`	Text	"Rótulo"	Texto do label (label/md)
`Show Description`	Boolean	`false`	Exibe texto descritivo abaixo do label
`Description`	Text	"Texto descritivo"	Texto multiline de descrição (body/sm)
`Show Helper Text`	Boolean	`false`	Exibe texto auxiliar abaixo da description
`Helper Text`	Text	"Texto auxiliar"	Anotação em caption/sm (content/secondary)

Quando usar

Zero, uma ou várias opções independentes podem ser selecionadas.
Uma opção binária possui label visível e será confirmada em formulário.

Quando não usar

Somente uma opção do grupo pode ser escolhida; use Radio.
A mudança liga ou desliga uma configuração imediatamente; use Toggle.

Composição React

import {
  Checkbox,
  CheckboxContent,
  CheckboxLabel,
  CheckboxTitle,
} from "@/components/ui/checkbox"

<CheckboxLabel>
  <Checkbox name="summary" />
  <CheckboxContent>
    <CheckboxTitle>Receber resumo semanal</CheckboxTitle>
  </CheckboxContent>
</CheckboxLabel>

Status: Beta
Distribuição: Source via shadcn

Instalação

Configure o namespace uma única vez na integração React.

npx shadcn@latest add @tis/checkbox

pnpm dlx shadcn@latest add @tis/checkbox

yarn dlx shadcn@latest add @tis/checkbox

bunx --bun shadcn@latest add @tis/checkbox

Contrato público

Item do registry: @tis/checkbox
Provider: Base UI
Distribuição: Source copiado para a aplicação
Status: Beta

Arquitetura técnica

Abrir JSON do registry

Inspecionar source distribuído

Interação por teclado

Tecla	Ação
`Tab`	Move o foco para o próximo checkbox
`Space`	Alterna o estado marcado

Accessibility

Critério WCAG	Requisito	Status
1.3.1 Info and Relationships (A)	Agrupe checkboxes relacionados em `<fieldset>` + `<legend>`	✓
2.4.11 Focus Appearance (AA)	Focus ring visível via `:focus-visible`	✓
2.5.8 Target Size min (AA)	Label estende a área de clique além do checkbox	✓
4.1.2 Name, Role, Value (A)	`<input type="checkbox">` nativo fornece role + estado automaticamente	✓
3.3.1 Error Identification (A)	Erro do grupo comunicado via `ds-checkbox-group--error`	✓

Notas de implementação

Usa <input type="checkbox"> nativo para suporte integrado a teclado e leitores de tela. O estado indeterminate deve ser definido via JavaScript (el.indeterminate = true). Sempre envolva checkboxes relacionados em um <fieldset> com um <legend> para fornecer contexto de grupo à tecnologia assistiva.

Label invisível — exige ARIA explícito

Quando Show Label = false e Show Description = true, vincule o <input> à descrição via aria-labelledby="id-da-description". Se nenhum dos dois estiver visível, use aria-label diretamente no <input>. O Helper Text deve sempre ser vinculado via aria-describedby="id-do-helper".

Responsabilidade da saída

Preserve a semântica da Base UI e teste conteúdo real, foco visível e nomes acessíveis na aplicação consumidora.

Evidência de validação

Coberta pelo Storybook da saída independente e por verificações de browser, responsividade, teclado, Axe e bundle.

Abrir referência estável