Switch — Sinapse Design System

Receber notificações

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>
  )
}

<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>

<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

Instale o Switch da sua stack e rode o comando individual ITpS em seguida. O comando itps add switch é theme-only: ele valida o slug e confirma que o contrato visual vem do tema ITpS, das classes copy-first e dos snippets desta página.

terminal · React/Next

pnpm dlx shadcn@latest add switch
pnpm dlx github:ITPS/sinapse-ui-cli add switch

terminal · Vue3/Nuxt4

pnpm dlx shadcn-vue@latest add switch
pnpm dlx github:ITPS/sinapse-ui-cli add switch

O comando individual adapta só este componente; não instala o catálogo inteiro.

Uso

Em React/Next com shadcn/ui e Vue3/Nuxt4 com shadcn-vue, use o Switch instalado pela stack. O tema ITpS vem dos tokens aplicados pela CLI, 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 Vue3/Nuxt4	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 submit 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.

Alertas de risco Sincronização automática Compartilhar métricas anonimizadas

<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.