Capítulo 30 de 108

Switch

Core Idea

Controle que alterna entre marcado e não marcado, com aparência de toggle. Use para configurações binárias ativadas/desativadas imediatamente (ex: modo avião, notificações), diferente do Checkbox que sugere seleção em formulário/lista.

Key Concepts

  • checked / onCheckedChange: par controlado; onCheckedChange recebe o novo boolean.
  • defaultChecked: estado inicial não controlado.
  • disabled: desabilita interação; combine com data-disabled no Field para estilo.
  • aria-invalid: indica estado inválido; combine com data-invalid no Field.
  • size: controla o tamanho do switch, aceita "sm" e "default".
  • Base: construído sobre @base-ui/react (Base UI Switch).

Code Examples

import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"

export function SwitchDemo() {
  return (
    <div className="flex items-center space-x-2">
      <Switch id="airplane-mode" />
      <Label htmlFor="airplane-mode">Airplane Mode</Label>
    </div>
  )
}
  • O que demonstra: uso mínimo com Label simples.
<FieldLabel htmlFor="switch-share">
  <Field orientation="horizontal">
    <FieldContent>
      <FieldTitle>Share across devices</FieldTitle>
      <FieldDescription>
        Focus is shared across devices, and turns off when you leave the app.
      </FieldDescription>
    </FieldContent>
    <Switch id="switch-share" />
  </Field>
</FieldLabel>
  • O que demonstra: padrão "choice card" - FieldLabel envolve o Field inteiro para tornar toda a área clicável, com Switch alinhado à direita.
<Switch id="switch-size-sm" size="sm" />
<Switch id="switch-size-default" size="default" />
  • O que demonstra: variação de tamanho via prop size.

Anti-patterns

  • Usar Switch para seleção em lista/formulário com múltiplas opções: nesse caso Checkbox é a escolha semântica correta (Switch é para ação imediata on/off, não para "marcar antes de enviar").

Key Takeaways

  1. Switch e Checkbox compartilham a mesma API de estado (checked/onCheckedChange/defaultChecked), mas diferem semanticamente: Switch = ação imediata, Checkbox = seleção em formulário.
  2. Estado inválido e desabilitado seguem o padrão duplo já visto em Checkbox/RadioGroup/Select: prop no componente + atributo data-* no Field pai.
  3. size="sm" é útil em listas densas de configurações onde o switch padrão ocupa espaço demais.
  4. Em card clicável, Switch fica como último filho do Field, com FieldContent (título + descrição) à esquerda.
  5. RTL funciona propagando dir para Field e Switch.

Connects To

  • Checkbox: componente irmão com API idêntica, mas semântica de seleção em vez de toggle imediato.
  • Field: fornece label, descrição, choice-card e estados (disabled/invalid) ao redor do Switch.
  • Select: em exemplos da doc de Select, Switch é usado para alternar opções de configuração (ex: alignItemWithTrigger).
AnteriorNative SelectPróximoSlider