Switch

Liga ou desliga uma configuração, com efeito imediato.

O Switch é para uma configuração binária que vale na hora: ligar e-mails ao Cliente, ativar a Página pública. Se a escolha só vale depois de enviar um formulário, use Checkbox.

import { Switch } from "@rastreio-x/ui";

Padrão

O rótulo vai dentro de Switch.Content, ao lado do controle. Clicar no texto também alterna.

E-mails ao Cliente

Playground

Ajuste tamanho e estados do interruptor e copie o código gerado.

E-mails ao Cliente

Controles

size

isDisabled

isReadOnly

Conteúdo

import { Switch } from "@rastreio-x/ui";

<Switch>
  <Switch.Content>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    E-mails ao Cliente
  </Switch.Content>
</Switch>

Tamanhos

Três tamanhos, sm, md (padrão) e lg. Use sm em listas densas.

Controlado

Com isSelected e onChange você guarda o valor no estado. Mostre o efeito da escolha em texto, para não depender só da posição do botão.

Aviso de entrega

Nenhum aviso é enviado.

Com descrição

Description explica a consequência de ligar. Fica abaixo do rótulo e é lida junto com ele.

Página públicaO Cliente acompanha a Jornada pelo link do e-mail.

Sem rótulo visível

Quando o contexto já nomeia o controle, informe aria-label.

Estados

Desabilitado mantém a posição (ligado ou desligado) mas não responde. Explique o motivo no texto próximo.

Desligado

Ligado

No Admin

Na preparação dos e-mails, uma chave geral controla um grupo de chaves de etapa. Desligar a geral desabilita as demais, sem mudar a escolha de cada uma.

Anatomia

Switch
├── Switch.Content
├── Switch.Control
├── Switch.Icon
└── Switch.Thumb

Switch.Content: agrupa controle e rótulo; é a área clicável.
Switch.Control: o trilho.
Switch.Thumb: o botão que desliza.
Switch.Icon: ícone opcional dentro do botão.

Propriedades

Switch
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<SwitchFieldRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<SwitchFieldRenderProps>`	`'react-aria-SwitchField'`	Classes CSS aplicadas ao elemento.
`defaultSelected`	`boolean`	-	Estado selecionado inicial (não controlado).
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`id`	`string`	-	Identificador único do elemento.
`inputRef`	`React.Ref<HTMLInputElement \| null>`	-	Referência ao elemento `input`.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`isSelected`	`boolean`	-	Estado selecionado (controlado).
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((isSelected: boolean) => void)`	-	Chamada quando o valor ou a seleção muda.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`render`	`DOMRenderFunction<'div', SwitchFieldRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`size`	`'lg' \| 'md' \| 'sm'`	-	Tamanho do interruptor: `sm`, `md` ou `lg`.
`style`	`StyleOrFunction<SwitchFieldRenderProps>`	-	Estilos em linha aplicados ao elemento.
`validate`	`((value: boolean) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.

Animações

CSS
indicativo

O botão desliza e o trilho muda de cor em transição CSS curta. Com prefers-reduced-motion, a folha global da fachada reduz a transição a 0,01 ms: o estado muda sem deslizar.

Acessibilidade

Papel switch (React Aria), com estado ligado/desligado anunciado.
Tab foca; Espaço alterna. O anel de foco azul aparece só com o teclado.
O nome acessível vem do texto em Switch.Content ou de aria-label.
O estado não depende só da cor: a posição do botão também muda.

Boas práticas

Faça

Rótulo que nomeia a configuração e descreve o resultado ligado: E-mails ao Cliente.

Evite

Rótulos como Ativar/Desativar, que obrigam a adivinhar o estado atual.

Use para efeito imediato; para formulários com envio, prefira Checkbox.
Um rótulo estável: não troque o texto entre ligado e desligado.
Mostre o resultado da mudança (toast ou texto) quando o efeito não for visível.
Agrupe chaves relacionadas e desabilite as filhas quando a mãe estiver desligada.

Relacionados

Checkbox para escolhas que só valem ao enviar.
Tooltip para explicar uma configuração.
Alert para avisar sobre efeitos de ligar ou desligar.