Componentes
Switch
betaLiga e desliga com efeito imediato. Se a mudança só vale ao salvar, o componente é o Checkbox.
Ainda não é estável porque Rota não varrida pelo sensor. Ausência de medição não é aprovação. O contrato de maturidade explica o que cada requisito exige.
@voxmente/ui/components/ui/switch
Orientação
Liga e desliga com efeito imediato. Não existe “salvar” depois de um Switch: se existe, o componente era outro.
Quando usar
- A mudança vale no instante do clique e o sistema já reflete o novo estado.
- É uma configuração binária de uma preferência ou de um recurso.
- O usuário precisa ver o estado atual sem abrir nada.
Quando não usar
- Quando a mudança só vale ao salvar o formulário — isso é Checkbox.
- Para escolher entre duas alternativas nomeadas (mensal / anual): Toggle Group deixa as duas visíveis.
- Quando a ação demora e pode falhar sem que o usuário perceba: mostre o estado de envio, ou use um botão com resposta explícita.
Playground
<Switch aria-label="Notificar responsável" />Uso
Liga ou desliga algo na hora — sem botão de salvar. Se a mudança só valer depois de confirmada, use Checkbox.
Tamanhos
`sm` cabe em linhas densas de configuração. O padrão é o resto — telas com poucos controles por vez.
Estados
Ligado, desligado e desabilitado. Desabilitado ainda mostra a posição atual — só não deixa mudar.
Inválido
`aria-invalid` marca o erro visualmente e para o leitor de tela ao mesmo tempo — não separe as duas coisas.
Com rótulo
O rótulo descreve o efeito de ligar, não o controle em si. "Notificações" diz menos que "Notificar a família".
Com descrição
`Field` em `orientation="horizontal"` alinha título, descrição e switch na mesma linha — use quando o rótulo sozinho não basta para explicar o efeito.
Lembrete de sessão
Avisa a família uma hora antes da aula marcada.
Lista de preferências
Cada linha aplica sozinha. É por isso que switch não pertence a um formulário com botão de salvar.
Acessibilidade
O que o componente já garante, e o que continua sendo responsabilidade da tela.
- Precisa de rótulo. O sensor registrou
aria-toggle-field-namenesta página: sem nome acessível, o controle não diz o que está ligando. - Cor não basta para comunicar o estado; a posição do polegar e o rótulo precisam bastar em escala de cinza.
- Se a ação pode falhar, o retorno ao estado anterior tem que ser visível — o usuário confia no que vê.
Componentes relacionados
Vizinhos que resolvem o problema parecido. Os links são resolvidos contra o registro.
Referência da API
Extraída do TypeScript de @voxmente/ui a cada build. Se divergir do código, o código mudou.
Switch
| Prop | Tipo | Padrão |
|---|---|---|
| size | "md" | "sm" | "md" |
Também aceita as props de Base UI e React, incluindo className e os atributos de DOM.
Pendência editorial: exemplo em contexto de produto. A lacuna aparece aqui em vez de ser preenchida com orientação inventada.
Origem do dado
- Orientação, acessibilidade e relacionados: documentação
- Demonstrações e playground: componente real de @voxmente/ui
- Referência da API: TypeScript do pacote
- Cor, espaçamento e raio das demonstrações: tokens de theme.css