Checkbox
Permite selecionar opções independentes e comunica seleção parcial quando necessário.
Design
Preview funcional
Executado com HTML e CSS estáveis do DS, sem runtime JavaScript do componente.
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.
Implementação
- Status
- Estável
- Distribuição
- Pacote npm
Instalação
npm install ds-tispnpm add ds-tisyarn add ds-tisbun add ds-tisImportações
import 'ds-tis/css'Markup
<label class="ds-checkbox-label">
<input class="ds-checkbox" type="checkbox" name="notifications" value="enabled" />
<span class="ds-checkbox__content">
<span class="ds-checkbox__label">Receber novidades</span>
</span>
</label>Contrato da implementação Web
Mapeamento de tokens
| Propriedade | Token Component | Variável CSS |
|---|---|---|
| box size (sm/md/lg) | component.checkbox.box.size.* | --ds-checkbox-box-size-* |
| box fill | component.checkbox.box.fill.*.* | --ds-checkbox-box-fill-* |
| box border | component.checkbox.box.border-color.*.* | --ds-checkbox-box-border-color-* |
| mark fill | component.checkbox.mark.fill.*.* | --ds-checkbox-mark-fill-* |
| target height | component.checkbox.target.height.* | --ds-checkbox-target-height-* |
| focus ring | component.checkbox.focus-ring.radius.default + component.focus-ring.* | --ds-focus-ring-* + --ds-checkbox-focus-ring-radius-default |
| label/helper/description/error | component.form-field.* | --ds-form-field-* |
Classes CSS
| Classe | Descrição |
|---|---|
ds-checkbox | Checkbox nativo estilizado |
ds-checkbox-label | Wrapper do label (envolve checkbox + texto) |
ds-checkbox--sm | Tamanho pequeno (16px) |
ds-checkbox--lg | Tamanho grande (24px) |
ds-checkbox-group--error | Estado de erro para um grupo de checkboxes |
ds-checkbox-group__error | Texto de mensagem de erro do grupo |
ds-checkbox__content | Frame vertical com label, description e helper text |
ds-checkbox__label | Texto do label dentro do content frame (label/md) |
ds-checkbox__description | Texto descritivo multiline (body/sm, content/default) |
ds-checkbox__helper | Texto auxiliar (caption/sm, content/secondary) |
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 do elemento nativo, nomes acessíveis, comportamento de teclado e foco visível.
Evidência de validação
Coberta pelo Storybook estável, testes do runtime público quando aplicável, cenários de teclado, responsividade e Axe.