Skip to Content
ComponentsAtomsSwitch

Switch

Atom

Switch altera um comportamento reversível com efeito imediato. Use quando a mudança acontece agora.

Use Checkbox quando a decisão faz parte de um formulário, seleção em lote ou confirmação aplicada depois. Switch deve deixar explícito o que liga, o que desliga e qual consequência operacional muda.

Exemplos copiáveis

React

import * as React from "react"
 
type PulsoSwitchProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> & {
  label: string
  description?: string
}
 
export function PulsoSwitch({
  id,
  label,
  description,
  checked,
  defaultChecked,
  onChange,
  ...props
}: PulsoSwitchProps) {
  const reactId = React.useId()
  const switchId = id ?? reactId
  const descriptionId = description ? `${switchId}-description` : undefined
 
  return (
    <label className="flex cursor-pointer select-none items-start justify-between gap-6">
      <span className="grid gap-0.5">
        <span className="text-sm font-medium text-[var(--fg-strong)]">{label}</span>
        {description ? (
          <span id={descriptionId} className="text-xs text-[var(--fg-muted)]">
            {description}
          </span>
        ) : null}
      </span>
 
      <input
        id={switchId}
        type="checkbox"
        role="switch"
        checked={checked}
        defaultChecked={defaultChecked}
        onChange={onChange}
        aria-describedby={descriptionId}
        className="peer sr-only"
        {...props}
      />
 
      <span
        aria-hidden="true"
        className={[
          "relative mt-0.5 h-[18px] w-8 shrink-0 rounded-full bg-[var(--border-strong)] transition-colors duration-[var(--motion-duration-default)] ease-[var(--motion-easing)]",
          "after:absolute after:left-0.5 after:top-0.5 after:h-3.5 after:w-3.5 after:rounded-full after:bg-white after:shadow-sm after:transition-transform after:duration-[var(--motion-duration-default)] after:ease-[var(--motion-easing)]",
          "peer-checked:bg-[var(--primary)] peer-checked:after:translate-x-3.5",
          "peer-focus-visible:outline peer-focus-visible:outline-[var(--ring-width)] peer-focus-visible:outline-offset-2 peer-focus-visible:outline-[var(--ring)]",
          "peer-disabled:cursor-not-allowed peer-disabled:opacity-60",
        ].join(" ")}
      />
    </label>
  )
}
<PulsoSwitch
  label="Alertas críticos por e-mail"
  description="Dispara quando um sinal cruza o nível critical."
  defaultChecked
/>

Quando usar

  • Preferência pessoal com efeito imediato.
  • Ativar/desativar automação reversível.
  • Modo de visualização ou atualização automática.
  • Notificação que pode ser ligada ou desligada sem submissão.

Quando não usar

  • Para aceitar termos; use Checkbox.
  • Para selecionar múltiplos itens.
  • Para ação destrutiva sem confirmação.
  • Para opção cujo efeito só acontece após salvar formulário.

Acessibilidade

  • Use role="switch" quando implementar com checkbox customizado.
  • O estado precisa ser programaticamente legível.
  • Explique consequência no texto auxiliar quando houver impacto operacional.
  • Movimento do thumb deve ser curto e respeitar tokens de motion.

Regras

  1. Switch muda algo agora.
  2. O label deve descrever o estado ligado.
  3. Descrição deve explicar efeito, não repetir o label.
  4. Mudança crítica pode exigir confirmação além do switch.
  5. Não use Switch para decisões irreversíveis.
Last updated on
SpinnerTextarea