Checkbox
Checkboxes permitem que usuários selecionem uma ou mais opções de um conjunto. Construído com <input type="checkbox"> nativo para acessibilidade completa.Checkboxes allow users to select one or more options from a set. Built with native <input type="checkbox"> for full accessibility.
Quando usarWhen to use
Use checkboxes quandoUse checkboxes when
Zero, uma ou múltiplas opções podem ser selecionadas de um conjunto. Ou para uma escolha binária com label visível: "Eu concordo com os termos", "Lembrar de mim".Zero, one, or multiple options can be selected from a set. Or for a single binary choice with a visible label: "I agree to the terms", "Remember me".
Não use checkboxes quandoDon't use checkboxes when
Apenas uma opção pode ser selecionada de um grupo (use Radio), um toggle rápido liga/desliga com efeito imediato é necessário (use Toggle), ou ao exibir uma longa lista de opções (use Select).Only one option can be selected from a group (use Radio), a quick on/off toggle with immediate effect is needed (use Toggle), or when displaying a long list of options (use Select).
| ComponenteComponent | SeleçãoSelection | ContextoContext |
|---|---|---|
| Checkbox | Múltiplas seleções permitidasMultiple selections allowed | Contexto de formulário, submit explícitoForm context, explicit submit |
| Toggle | Liga/desliga únicoSingle on/off | Efeito imediato, sem necessidade de submitImmediate effect, no submit needed |
| Radio | Mutuamente exclusivo, um deve ser selecionadoMutually exclusive, one must be selected | Form context, explicit submit |
AnatomiaAnatomy
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
2 Input (
3 Checkmark — CSS pseudo-element, visible when checked.
4 Indeterminate dash — CSS pseudo-element, visible when
.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.1 Label (.ds-checkbox-label) — wraps checkbox + text, extends click target.2 Input (
.ds-checkbox) — styled native <input type="checkbox">.3 Checkmark — CSS pseudo-element, visible when checked.
4 Indeterminate dash — CSS pseudo-element, visible when
indeterminate = true.
PadrãoDefault
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox">
Unchecked
</label>
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox" checked>
Checked
</label>IndeterminadoIndeterminate
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox" id="select-all">
Select all
</label>
<script>
// Indeterminate must be set via JavaScript
document.getElementById('select-all').indeterminate = true;
</script>TamanhosSizes
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox ds-checkbox--sm">
Small (16px)
</label>
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox">
Medium (20px, default)
</label>
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox ds-checkbox--lg">
Large (24px)
</label>Grupo com erroError Group
<fieldset class="ds-checkbox-group--error">
<legend>Select at least one option</legend>
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox">
Option A
</label>
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox">
Option B
</label>
<span class="ds-checkbox-group__error">Please select at least one option.</span>
</fieldset>DesabilitadoDisabled
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox" disabled>
Disabled unchecked
</label>
<label class="ds-checkbox-label">
<input type="checkbox" class="ds-checkbox" checked disabled>
Disabled checked
</label>Boas práticasBest practices
Faça
Envolva em
<fieldset> com <legend> para contexto de leitores de tela.Wrap in <fieldset> with <legend> for screen reader context.Não faça
Usar checkboxes sem labels. Todo checkbox precisa de um label de texto visível.Use checkboxes without labels. Every checkbox needs a visible text label.
Faça
Use indeterminate para "selecionar todos" quando alguns filhos estão marcados.Use indeterminate for "select all" when some children are checked.
Não faça
Usar indeterminate como um terceiro estado voltado ao usuário. É um estado apenas programático.Use indeterminate as a third user-facing state. It is a programmatic state only.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Use declarações afirmativasUse affirmative statements | "Receive marketing emails" — not "Don't send me emails" |
| A legend do grupo deve ser uma pergunta ou instruçãoGroup legend should be a question or instruction | "Select your interests" — not "Interests list" |
| Mantenha labels concisosKeep labels concise | "Remember me" — not "Keep me logged in on this device for future sessions" |
| Use sentence caseUse sentence case | "Receive notifications" — not "Receive Notifications" |
Mapeamento de tokensToken mapping
| PropriedadeProperty | Token (semantic) | Variável CSSCSS variable |
|---|---|---|
| border (unchecked) | semantic.border.default | --ds-border-default |
| background (checked) | semantic.primary.background.default | --ds-primary-background-default |
| checkmark color | semantic.primary.content-default | --ds-primary-content-default |
| border (error) | semantic.feedback.error.border-default | --ds-feedback-error-border-default |
| focus ring | semantic.focus.ring.* | --ds-focus-ring-width, --ds-focus-ring-offset, --ds-focus-ring-color |
| border-radius | foundation.radius.4 | --ds-radius-4 |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-checkbox | Checkbox nativo estilizadoCustom styled native checkbox |
ds-checkbox-label | Wrapper do label (envolve checkbox + texto)Label wrapper (wraps checkbox + text) |
ds-checkbox--sm | Tamanho pequeno (16px)Small size (16px) |
ds-checkbox--lg | Tamanho grande (24px)Large size (24px) |
ds-checkbox-group--error | Estado de erro para um grupo de checkboxesError state for a group of checkboxes |
ds-checkbox-group__error | Texto de mensagem de erro do grupoError message text for the group |
ds-checkbox__content | Frame vertical com label, description e helper textVertical frame stacking label, description, and helper text |
ds-checkbox__label | Texto do label dentro do content frame (label/md)Label text inside content frame (label/md) |
ds-checkbox__description | Texto descritivo multiline (body/sm, content/default)Multiline description text (body/sm, content/default) |
ds-checkbox__helper | Texto auxiliar (caption/sm, content/secondary)Helper annotation (caption/sm, content/secondary) |
Propriedades FigmaFigma properties
| PropriedadeProperty | TipoType | PadrãoDefault | DescriçãoDescription |
|---|---|---|---|
Show Label | Boolean | true | Exibe ou oculta o label do controleShows or hides the control label |
Label | Text | "Rótulo" | Texto do label (label/md)Label text (label/md) |
Show Description | Boolean | false | Exibe texto descritivo abaixo do labelShows descriptive text below the label |
Description | Text | "Texto descritivo" | Texto multiline de descrição (body/sm)Multiline description text (body/sm) |
Show Helper Text | Boolean | false | Exibe texto auxiliar abaixo da descriptionShows helper text below the description |
Helper Text | Text | "Texto auxiliar" | Anotação em caption/sm (content/secondary)Caption/sm annotation (content/secondary) |
Interação por tecladoKeyboard interaction
| TeclaKey | AçãoAction |
|---|---|
Tab | Move o foco para o próximo checkboxMoves focus to the next checkbox |
Space | Alterna o estado marcadoToggles the checked state |
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | Agrupe checkboxes relacionados em <fieldset> + <legend>Group related checkboxes in <fieldset> + <legend> | ✓ |
| 2.4.11 Focus Appearance (AA) | Focus ring visível via :focus-visibleFocus ring visible via :focus-visible | ✓ |
| 2.5.8 Target Size min (AA) | Label estende a área de clique além do checkboxLabel extends click target beyond the checkbox itself | ✓ |
| 4.1.2 Name, Role, Value (A) | <input type="checkbox"> nativo fornece role + estado automaticamenteNative <input type="checkbox"> provides role + state automatically | ✓ |
| 3.3.1 Error Identification (A) | Erro do grupo comunicado via ds-checkbox-group--errorGroup error communicated via ds-checkbox-group--error | ✓ |
Notas de implementaçãoImplementation notes
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.Uses native <input type="checkbox"> for built-in keyboard and screen reader support. The indeterminate state must be set via JavaScript (el.indeterminate = true). Always wrap related checkboxes in a <fieldset> with a <legend> to provide group context to assistive technology.
Label invisível — exige ARIA explícitoInvisible label — requires explicit ARIA
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".When Show Label = false and Show Description = true, link the <input> to the description via aria-labelledby="description-id". If neither is visible, use aria-label directly on the <input>. Helper Text should always be linked via aria-describedby="helper-id".