Switch

Quando usar

Use o switch para ligar ou desligar uma preferencia com efeito imediato: notificacoes, modo escuro, um recurso experimental. Ele e a metafora de uma chave liga/desliga, diferente do checkbox dentro de um formulario que so aplica a mudanca ao confirmar.

Quando nao usar

Nao use switch dentro de um formulario que so aplica a mudanca ao confirmar: use Checkbox. Nao use switch para selecao unica entre tres ou mais opcoes: isso e toggle-group (quando existir) ou radio-group.

Anatomia

• Switch (data-slot="switch"): a raiz interativa, com role="switch" herdado do Radix.
• switch-thumb (data-slot="switch-thumb"): o circulo que desliza entre os dois lados da trilha.
• switch-mixed-indicator (data-slot="switch-mixed-indicator"): so existe quando mixed esta ativo, um traco central que substitui o thumb, replicando o icone do Switch legado.

Rotulo nao faz parte do componente, assim como no Checkbox. Componha com um <label> ou use aria-label quando nao houver texto visivel.

Decisao sobre o estado misto

O Switch legado do Hub tinha tres estados (on, off, mixed), com um icone de traco no misto. O Switch do Radix, ao contrario do Checkbox, so modela checked como booleano: nao existe um terceiro estado nativo equivalente ao indeterminate do checkbox.

Duas saidas eram possiveis: reportar que o misto nao sobrevive a migracao, ou reconstruir o misto por cima do primitivo sem abrir mao do Radix como base. Escolhemos a segunda. A prop mixed e puramente visual: quando verdadeira, o componente inclui aria-checked="mixed" no conjunto de props passado ao Root (o Radix monta o proprio aria-checked antes de espalhar o restante das props recebidas, entao a chave so existe quando mixed for verdadeiro, nunca como undefined, senao apagaria o valor correto do Radix quando o switch nao esta misto) e troca o thumb pelo traco central. O estado interno on/off do Radix continua existindo por baixo do misto: assim que o usuario interage, o Switch resolve para um dos dois lados, o mesmo comportamento que o Checkbox ja tem quando sai do indeterminado.

Acessibilidade

role="switch" e aria-checked (incluindo "mixed") chegam corretos ao leitor de tela sem configuracao adicional. O componente funciona por teclado: Tab foca, Espaco alterna. Estado desabilitado usa o atributo disabled nativo, nunca so opacidade. Todo Switch sem texto visivel ao lado precisa de aria-label.