# Switch

Controle booleano para preferência com efeito imediato.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Forms
- Status: stable
- Relacionados: /componentes/checkbox.md, /componentes/field.md

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componentes padrão do shadcn (`switch`) com o tema Sinapse: cores, fonte e raio vêm do tema, e as variantes `itps-*` desta página existem só no HTML.

**React/Next (shadcn/ui)**

```tsx
import { Switch } from '@/components/ui/switch'

export function SwitchExample() {
  return (
    <div className="flex items-center gap-2">
      <Switch id="notifications" />
      <label
        htmlFor="notifications"
        className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
      >
        Receber notificações
      </label>
    </div>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import { Switch } from '@/components/ui/switch'
</script>

<template>
  <div class="flex items-center gap-2">
    <Switch id="notifications" />
    <label
      for="notifications"
      class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
    >
      Receber notificações
    </label>
  </div>
</template>
```

**HTML (copy-first)**

```html
<label class="itps-switch">
  <span class="itps-switch__control">
    <input
      type="checkbox"
      role="switch"
      id="notifications"
      name="notifications"
      class="itps-switch__input"
    />
    <span class="itps-switch__track" aria-hidden="true"></span>
    <span class="itps-switch__thumb" aria-hidden="true"></span>
  </span>
  <span class="itps-switch__label">Receber notificações</span>
</label>
```

## Instalação

O comando instala o Switch da sua stack com o tema Sinapse. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/switch
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/switch.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use o `Switch` instalado pela stack. O tema Sinapse vem dos tokens instalados pelo CLI do shadcn ou do shadcn-vue, então o exemplo deve continuar próximo da documentação oficial: componente, `id` e label associado.

Use `itps-switch` quando precisar do contrato copy-first em HTML ou wrappers finos. O input continua sendo `type="checkbox"` com `role="switch"`; track e thumb são apenas a camada visual.

## Exemplos

### Estados

| Estado | React/Next e Vue 3/Nuxt 4 | HTML |
|--------|--------------------------|------|
| Ativado inicial | `defaultChecked` ou valor controlado | `checked` no input |
| Desabilitado | `disabled` | `disabled` no input |
| Controlado | `checked` + `onCheckedChange` | sincronize o atributo/estado no input |

Use `Switch` para preferências de efeito imediato. Quando a escolha depende de envio ou faz parte de seleção múltipla, use `Checkbox`.

### Preferências

Use em listas curtas de configurações independentes. Cada switch deve ter um `name` próprio quando enviado em formulário.

**HTML (copy-first)**

```html
<div class="flex flex-col gap-3">
  <label class="itps-switch">
    <span class="itps-switch__control">
      <input
        type="checkbox"
        role="switch"
        id="pref-alerts"
        name="pref-alerts"
        checked
        class="itps-switch__input"
      />
      <span class="itps-switch__track" aria-hidden="true"></span>
      <span class="itps-switch__thumb" aria-hidden="true"></span>
    </span>
    <span class="itps-switch__label">Alertas de risco</span>
  </label>

  <label class="itps-switch">
    <span class="itps-switch__control">
      <input
        type="checkbox"
        role="switch"
        id="pref-sync"
        name="pref-sync"
        class="itps-switch__input"
      />
      <span class="itps-switch__track" aria-hidden="true"></span>
      <span class="itps-switch__thumb" aria-hidden="true"></span>
    </span>
    <span class="itps-switch__label">Sincronização automática</span>
  </label>

  <label class="itps-switch">
    <span class="itps-switch__control">
      <input
        type="checkbox"
        role="switch"
        id="pref-share"
        name="pref-share"
        class="itps-switch__input"
      />
      <span class="itps-switch__track" aria-hidden="true"></span>
      <span class="itps-switch__thumb" aria-hidden="true"></span>
    </span>
    <span class="itps-switch__label">Compartilhar métricas anonimizadas</span>
  </label>
</div>
```

### Quando usar

| Use Switch | Use Checkbox |
|------------|--------------|
| Ativar notificações, sincronização ou modo compacto. | Aceitar termos, selecionar itens ou marcar opções para salvar depois. |
| A mudança acontece assim que o usuário alterna. | A mudança depende de envio, revisão ou confirmação. |
| A opção é independente das demais. | O usuário pode escolher múltiplas opções em um grupo. |

Evite usar Switch para ações destrutivas, confirmações legais ou decisões que precisam de botão de envio.

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-switch` | Label clicável que envolve controle e texto. |
| `itps-switch__control` | Área visual que contém input, track e thumb. |
| `itps-switch__input` | Checkbox nativo que mantém foco, teclado e formulário. |
| `itps-switch__track` | Trilha visual do switch. |
| `itps-switch__thumb` | Botão visual que se move entre estados. |
| `itps-switch__label` | Texto visível da preferência. |
| `role="switch"` | Comunica semântica de liga/desliga. |
| `checked` | Estado ativado inicial do input nativo. |
| `disabled` | Bloqueia interação. |
| `name` | Valor enviado quando o switch participa de formulário. |

## Acessibilidade

Mantenha o `<input type="checkbox" role="switch">` no DOM para preservar foco, teclado e envio em formulário. O label deve envolver o controle e o texto para aumentar a área clicável. Use `Space` para alternar, `disabled` para bloquear interação e texto claro para indicar a preferência afetada.