Toggle

Componentes/Entrada e seleção

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

Adapter React independente em que Ark UI fornece as parts e Zag mantém on/off, foco, teclado e formulário.

DesignUsoImplementaçãoAcessibilidade

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

Design

Preview funcional

Executado pelo adapter independente Ark UI com comportamento Zag.

Carregando preview funcional…

Abrir playground Ark/Zag

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.

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/toggle.jsx

import {
  Switch,
  SwitchContent,
  SwitchControl,
  SwitchHiddenInput,
  SwitchThumb,
  SwitchTitle,
} from '@tis/react/ark/toggle'

Beta de workspace

Este caminho é um contrato de workspace, não um pacote público. Ainda não se anuncia instalação por package manager.

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 de switch Ark/Zag e valide Space, estado ligado/desligado, disabled, label acessível estável, 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.

Abrir referência estável