Toggle
Toggles (switches) permitem que o usuário ative ou desative uma configuração instantaneamente. Construido com um checkbox nativo estilizado e role="switch".Toggles (switches) let users turn a setting on or off instantly. Built with a styled native checkbox and role="switch".
Quando usarWhen to use
Use toggles quandoUse toggles when
O usuário precisa ativar/desativar uma configuração com efeito imediato. Modo escuro, notificações, feature flags, preferencias de salvamento automatico.The user needs to turn an on/off setting that takes effect immediately. Dark mode, notifications, feature flags, auto-save preferences.
AnatomiaAnatomy
1
2
3
4
1 Input (
2 Track — fundo CSS que muda de cor conforme o estado checked.
3 Thumb — pseudo-elemento CSS que desliza esquerda/direita.
4 Content Frame (
2 Track — CSS background that changes color based on checked state.
3 Thumb — CSS pseudo-element that slides left/right.
4 Content Frame (
.ds-toggle) — <input type="checkbox"> estilizado com role="switch".2 Track — fundo CSS que muda de cor conforme o estado checked.
3 Thumb — pseudo-elemento CSS que desliza esquerda/direita.
4 Content Frame (
.ds-toggle__content) — envolve label, description e helper.1 Input (.ds-toggle) — styled <input type="checkbox"> with role="switch".2 Track — CSS background that changes color based on checked state.
3 Thumb — CSS pseudo-element that slides left/right.
4 Content Frame (
.ds-toggle__content) — wraps label, description and helper text.
PadrãoDefault
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch">
<span class="ds-toggle__content">
<span class="ds-toggle__label">Notifications</span>
</span>
</label>Com descrição e texto auxiliarWith description and helper text
<label class="ds-toggle-label">
<input type="checkbox" class="ds-toggle" role="switch" checked>
<span class="ds-toggle__content">
<span class="ds-toggle__label">Automatic updates</span>
<span class="ds-toggle__description">Keep your software up to date...</span>
<span class="ds-toggle__helper">Requires a stable internet connection.</span>
</span>
</label>TamanhosSizes
<!-- Small -->
<input type="checkbox" class="ds-toggle ds-toggle--sm" role="switch">
<!-- Medium -->
<input type="checkbox" class="ds-toggle" role="switch">
<!-- Large -->
<input type="checkbox" class="ds-toggle ds-toggle--lg" role="switch">DesabilitadoDisabled
<input type="checkbox" class="ds-toggle" role="switch" disabled>EstadosStates
| State | CSS trigger | Visual change | Token |
|---|---|---|---|
| Off | --- | Neutral track with dark thumb | component.toggle.track.fill.off.default, component.toggle.thumb.fill.off.default |
| Off hover | :hover | Darker neutral track/thumb | component.toggle.track.fill.off.hover, component.toggle.thumb.fill.off.hover |
| On | :checked | Primary track with light thumb | component.toggle.track.fill.on.default, component.toggle.thumb.fill.on.default |
| On hover | :checked:hover | Darker primary track | component.toggle.track.fill.on.hover, component.toggle.thumb.fill.on.hover |
| Focus | :focus-visible | 2px outline ring | component.toggle.focus-ring.radius.default + component.focus-ring.* |
| Disabled | [disabled] | Muted track, thumb and label | component.toggle.track.fill.*.disabled, semantic.content.disabled |
Boas práticasBest practices
Faça
Labels descrevem a configuração: "Dark mode", "Email notifications".Labels describe the setting: "Dark mode", "Email notifications".
Não faça
"Enable dark mode" e redundante com o estado do toggle."Enable dark mode" is redundant with the toggle state itself.
Faça
Posicione o toggle a esquerda do conteúdo. O alinhamento deve ser ao topo.Place toggle left of content. Alignment should be to the top.
Não faça
Não use toggle para ações que precisam de confirmação. Use um Button + dialog.Don't use toggle for actions needing confirmation. Use a Button + dialog instead.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Use um substantivo para o labelUse a noun phrase for the label | "Dark mode", "Auto-save", "Email notifications" |
| Não use "Enable/Disable"Don't use "Enable/Disable" | "Notifications" — não "Enable notifications""Notifications" — not "Enable notifications" |
| Mantenha labels curtos (1-3 palavras)Keep labels short (1-3 words) | "Auto-save" — não "Automatically save my work every 5 minutes""Auto-save" — not "Automatically save my work every 5 minutes" |
Mapeamento de tokensToken mapping
| PropriedadeProperty | Token Component | Variável CSSCSS variable |
|---|---|---|
| target height/gap | component.toggle.target.{height,gap}.* | --ds-toggle-target-* |
| track size | component.toggle.track.{width,height}.* | --ds-toggle-track-* |
| track fill | component.toggle.track.fill.*.* | --ds-toggle-track-fill-* |
| track border | component.toggle.track.border-color.*.* | --ds-toggle-track-border-color-* |
| thumb size/fill | component.toggle.thumb.{size,fill}.* | --ds-toggle-thumb-* |
| focus ring | component.toggle.focus-ring.radius.default + component.focus-ring.* | --ds-focus-ring-* + --ds-toggle-focus-ring-radius-default |
| label/helper/description | component.form-field.* | --ds-form-field-* |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-toggle | Switch estilizado (checkbox nativo)Custom styled switch (native checkbox) |
ds-toggle-label | Wrapper do controle (envolve track + conteúdo)Control wrapper (wraps track + content) |
ds-toggle--sm | Tamanho pequeno (28x16px)Small size (28x16px) |
ds-toggle--lg | Tamanho grande (56x32px)Large size (56x32px) |
ds-toggle__content | Frame vertical com label, description e helper textVertical frame stacking label, description, and helper text |
ds-toggle__label | Texto do label (label/md)Label text (label/md) |
ds-toggle__description | Texto descritivo multiline (body/sm)Multiline description text (body/sm) |
ds-toggle__helper | Texto auxiliar (caption/sm)Helper annotation (caption/sm) |
Interação por tecladoKeyboard interaction
| TeclaKey | AçãoAction |
|---|---|
Tab | Move o foco para o toggleMoves focus to the toggle |
Space | Alterna ligado/desligadoToggles on/off |
Enter | NÃO alterna (comportamento padrão de switch)Does NOT toggle (standard switch behavior) |
Toggles desabilitados ([disabled]) são removidos da ordem de tabulação automaticamente pelo navegador.Disabled toggles ([disabled]) are removed from tab order automatically by the browser.
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 4.1.2 Name, Role, Value (A) | role="switch" + aria-checked gerenciados pelo checkbox nativorole="switch" + aria-checked managed by native checkbox | ✓ |
| 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 toggleLabel extends click target beyond the toggle itself | ✓ |
| 1.4.1 Use of Color (A) | Posição + cor comunicam o estado (thumb desliza esquerda/direita)Position + color both communicate state (thumb slides left/right) | ✓ |
Resumo de atributos ARIAARIA attributes summary
role="switch" — obrigatório no checkbox para que leitores de tela o anunciem como switch.aria-checked — gerenciado automaticamente pelo <input type="checkbox"> nativo.O conteúdo textual deve estar dentro de
.ds-toggle__content.role="switch" — required on the checkbox so screen readers announce it as a switch.aria-checked — managed automatically by the native <input type="checkbox">.Textual content must be inside
.ds-toggle__content.