Checkbox
Adapter React independente em que Ark UI fornece as parts e Zag mantém checked, mixed, foco e formulário.
Design
Preview funcional
Executado pelo adapter independente Ark UI com comportamento Zag.
Carregando preview funcional…
Anatomia
1
2
3
4
1 Label (
2 Input (
3 Checkmark — pseudo-elemento CSS, visível quando marcado.
4 Traço indeterminado — pseudo-elemento CSS, visível quando
.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
Indeterminado
Tamanhos
Grupo com erro
Desabilitado
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) |
Uso
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.
Quando escolher esta saída
Adote este adapter em projetos que escolheram Ark UI e Zag como arquitetura comportamental. Não o importe dentro da saída shadcn/Base UI.
Implementação
- Status
- Beta
- Distribuição
- Adapter de source
Source do adapter
packages/react/src/ark/checkbox.jsx
import {
Checkbox,
CheckboxContent,
CheckboxControl,
CheckboxHiddenInput,
CheckboxIndicator,
CheckboxLabel,
} from '@tis/react/ark/checkbox'Acessibilidade
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 Ark/Zag e valide Space, estados checked e mixed, disabled e invalid, foco visível e envio do hidden input no formulário.
Evidência de validação
Coberta pelo Storybook da saída independente e por verificações de browser, responsividade, teclado, Axe e bundle.