BaseSwitch

Liga ou desliga uma opção com efeito imediato, como um aviso ou um modo de trabalho. Para escolher algo que só vale ao salvar o formulário, use uma caixa de seleção.

Avisar vencimento da garantia

Mostrar só obras atrasadas

A lista esconde as obras dentro do prazo enquanto estiver ligado.

Resumo semanal por e-mailDesligado

Uso

• O rótulo diz o que fica ligado: "Avisar vencimento da garantia", não "Avisos: sim/não". Ele não muda com o estado.
• A mudança vale na hora. Se a opção só tem efeito ao salvar, ou se o usuário precisa confirmar, use caixa de seleção.
• Use on-text e off-text quando o estado precisa ficar escrito na tela, por exemplo em configurações revisadas por outra pessoa. Passe os dois juntos: com só um, nenhum texto aparece.
• Use helper-text para explicar o que muda quando está ligado.
• O BaseSwitch já traz rótulo e ajuda. Não coloque dentro de um BaseField.
• Um interruptor desabilitado não recebe foco, então quem navega por teclado ou leitor de tela não ouve a ajuda dele. Quando o motivo do bloqueio importa ("Só o fiscal do contrato pode mudar"), escreva esse motivo em texto visível fora do controle.
• Em tabela, use hide-label para esconder o rótulo da tela sem tirá-lo do leitor de tela. O rótulo continua dizendo o que liga, por exemplo "Avisar vencimento da garantia da obra 12".

Anatomia

1. Trilho: o fundo que muda de cor quando está ligado.
2. Botão: o círculo que passa para a direita ao ligar.
3. Rótulo: de label. Com hide-label, sai da tela.
4. Texto de estado: de on-text e off-text, depois do rótulo.
5. Ajuda: de helper-text, abaixo.

Estados

Desligado

Ligado

Desabilitado e desligado

Desabilitado e ligado

Tamanhos

Pequeno · 28 × 16 px

Pequeno com estado escritoDesligado

Médio · 32 × 18 px

Use sm em tabelas e filtros densos.

Rótulo escondido

Obra	Garantia até	Avisar vencimento
Fórum de Linhares	14/03/2027	Avisar vencimento da garantia do Fórum de Linhares
Fórum de Colatina	02/09/2027	Avisar vencimento da garantia do Fórum de Colatina

Com hide-label, a coluna já diz o que o interruptor faz e o rótulo fica só para o leitor de tela, com o nome da obra.

Faça e não faça

Faça	Não faça
Use para o que vale na hora: "Avisar vencimento da garantia".	Use para uma escolha que só conta ao salvar o formulário.
Escreva no rótulo o que fica ligado.	Escreva "Sim/Não" no rótulo ou troque o rótulo com o estado.
Escreva o motivo do bloqueio em texto visível fora do interruptor desabilitado.	Deixe o motivo só na ajuda do interruptor desabilitado, que não recebe foco.

Estilo

Propriedade	Token
Trilho desligado	--tj-field-01, borda --tj-border-strong-02; hover --tj-layer-hover-01; pressionado --tj-layer-accent-01
Trilho ligado	--tj-interactive, hover --tj-interactive-hover, pressionado --tj-interactive-active
Botão desligado / ligado	--tj-border-strong-02 / --tj-text-on-color
Desabilitado	desligado: trilho --tj-field-disabled, borda --tj-border-subtle-02, botão --tj-icon-secondary; ligado: trilho --tj-icon-secondary, botão --tj-field-01; texto --tj-text-helper
Texto do estado	--tj-text-helper, semibold
Foco	em todos os estados: contorno sólido de 2 px --tj-border-interactive, afastado 2 px do trilho; borda --tj-border-interactive
Área de clique	pelo menos 24 px de altura, termina no fim do texto
Movimento	--tj-duration-fast-02, --tj-easing-standard; sem animação com prefers-reduced-motion
Tamanho	32 × 18 px (md), 28 × 16 px (sm)

Todas as cores são tokens de papel e trocam com o botão Tema: no escuro, o trilho desligado usa o --tj-field-01 escuro e o botão, o --tj-border-strong-02 claro. Hover e pressionado aparecem com o ponteiro em qualquer parte do rótulo, porque o rótulo inteiro alterna.

Código

<BaseSwitch v-model="warrantyReminder" label="Avisar vencimento da garantia" />
<BaseSwitch v-model="weeklySummary" label="Resumo semanal por e-mail" on-text="Ligado" off-text="Desligado" size="sm" />

Propriedades

Propriedade	Tipo	Padrão	Descrição
label	string	obrigatória	Rótulo; não muda com o estado
size	'sm' | 'md'	'md'	Tamanho do trilho e do texto
disabled	boolean	false	Desabilita a troca
onText	string	—	Estado escrito ao lado do rótulo quando ligado, como "Ligado"; só aparece junto com offText
offText	string	—	Estado escrito ao lado do rótulo quando desligado, como "Desligado"; só aparece junto com onText
helperText	string	—	Ajuda abaixo do rótulo
hideLabel	boolean	false	Esconde o rótulo da tela e mantém para o leitor de tela; para tabelas
v-model	boolean	false	Ligado ou desligado

Evento: update:modelValue, com o novo valor. Se o pai não aceitar a troca (por exemplo, uma confirmação recusada), o interruptor volta ao valor que o pai manteve.

Outros atributos, como id, name, form e aria-controls, vão para o <input>; class e style ficam no contêiner. Um aria-describedby passado pelo pai é mantido, e a ajuda entra depois dele.

Acessibilidade

• É um <input type="checkbox"> nativo com role="switch": o leitor de tela anuncia "interruptor, ligado" ou "desligado". Segue o padrão Switch do WAI-ARIA APG.
• Tab leva ao interruptor e Espaço alterna (comportamento nativo do <input>). O rótulo inteiro é clicável, numa área de pelo menos 24 px de altura.
• Use aria-controls quando o interruptor mostra ou esconde outra parte da tela.
• O rótulo nomeia o interruptor e não muda com o estado. O texto de on-text e off-text fica escondido do leitor de tela (aria-hidden), que já anuncia o estado.
• A cor nunca é o único sinal: o botão muda de lado no trilho, e o estado pode ficar escrito.
• A ajuda fica em aria-describedby.
• O foco aparece só na navegação por teclado: um contorno sólido --tj-border-interactive de 2 px, afastado 2 px do trilho, ligado ou desligado. O anel translúcido --tj-ring sozinho ficaria fraco demais num trilho tão pequeno.
• No modo de alto contraste do Windows, o interruptor usa as cores do sistema: trilho Highlight quando ligado, contorno CanvasText quando desligado (também com foco), GrayText quando desabilitado e foco em Highlight. O botão continua mudando de lado.
• Testado com axe nos estados desligado, ligado, desabilitado, pequeno, com texto de estado, com ajuda, com aria-controls e com rótulo escondido, inclusive combinados. O nome acessível é conferido no teste: continua sendo o rótulo com texto de estado e com hide-label. A troca por Espaço e o alto contraste dependem do navegador e não entram no teste automático.

Teclado:

Tecla	O que faz
Tab	Leva o foco ao interruptor. Desabilitado, ele sai da ordem do Tab.
Espaço	Liga ou desliga.