Toggle

Componentes/Entrada e seleção

ImplementaçãoHTML/CSS/JSArk/ZagReact · shadcn/Base UIAngular

Liga ou desliga uma configuração com efeito imediato e estado persistente.

DesignUsoImplementaçãoAcessibilidade

Seção da documentaçãoDesignUsoImplementaçãoAcessibilidade

Design

Preview funcional

Executado com HTML e CSS estáveis do DS, sem runtime JavaScript do componente.

Carregando preview funcional…

Abrir playground HTML/CSS/JS

Anatomia

Label text 1 2 3 4

1 Input (.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.

Padrão

Notifications

Com descrição e texto auxiliar

Automatic updates Keep your software up to date with the latest features and security patches. Requires a stable internet connection.

Tamanhos

Small Medium (default) Large

Desabilitado

Disabled off Disabled on

Estados

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

Uso

Quando usar

• A configuração entra em vigor imediatamente ao ser ligada ou desligada.
• O estado atual precisa permanecer visível após a interação.

Quando não usar

• A escolha só será aplicada ao enviar um formulário; use Checkbox.
• A pessoa precisa escolher uma alternativa entre várias; use Radio.

Nota de uso

O label do Toggle não muda entre ligado e desligado; o estado é comunicado pelo próprio controle.

Implementação

Status

Estável

Distribuição

Pacote npm

Instalação

npm

npm install ds-tis

pnpm

pnpm add ds-tis

yarn

yarn add ds-tis

bun

bun add ds-tis

Importações

import 'ds-tis/css'

Markup

<label class="ds-toggle-label">
  <input class="ds-toggle" type="checkbox" role="switch" name="notifications" value="enabled" />
  <span class="ds-toggle__content">
    <span class="ds-toggle__label">Receber notificações</span>
  </span>
</label>

Sem runtime para Toggle

O componente usa um elemento HTML nativo. JavaScript permanece sob responsabilidade da aplicação; o DS entrega anatomia, visual e estados.

Contrato da implementação Web

Mapeamento de tokens

Propriedade	Token Component	Variável CSS
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 CSS

Classe	Descrição
ds-toggle	Switch estilizado (checkbox nativo)
ds-toggle-label	Wrapper do controle (envolve track + conteúdo)
ds-toggle--sm	Tamanho pequeno (28x16px)
ds-toggle--lg	Tamanho grande (56x32px)
ds-toggle__content	Frame vertical com label, description e helper text
ds-toggle__label	Texto do label (label/md)
ds-toggle__description	Texto descritivo multiline (body/sm)
ds-toggle__helper	Texto auxiliar (caption/sm)

Acessibilidade

Interação por teclado

Tecla	Ação
Tab	Move o foco para o toggle
Space	Alterna ligado/desligado
Enter	NÃO alterna (comportamento padrão de switch)

Toggles desabilitados ([disabled]) são removidos da ordem de tabulação automaticamente pelo navegador.

Accessibility

Critério WCAG	Requisito	Status
4.1.2 Name, Role, Value (A)	role="switch" + aria-checked gerenciados pelo checkbox nativo	✓
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 toggle	✓
1.4.1 Use of Color (A)	Posição + cor comunicam o estado (thumb desliza esquerda/direita)	✓

Resumo de atributos ARIA

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.

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.

Abrir referência estável