componentes / switch

Switch

Alternador liga/desliga com role="switch", rótulo, texto de ajuda e de erro e cores.

Como usar

Um checkbox nativo exposto como `role="switch"`, então funciona em formulários, com `ref` e teclado (Espaço). Use para ajustes que valem na hora; use `Checkbox` para escolhas enviadas depois.

preview

Wi-Fi

NotificaçõesEnviadas por e-mail

Switch.tsx

import { Switch } from "vaiperui";
 
<Switch label="Wi-Fi" />
<Switch
  defaultChecked
  variantColor="success"
  label="Notificações"
  helperText="Enviadas por e-mail"
/>

Cores

preview

primary

success

warning

danger

cores.tsx

<Switch defaultChecked variantColor="primary" label="primary" />
<Switch defaultChecked variantColor="success" label="success" />
<Switch defaultChecked variantColor="warning" label="warning" />
<Switch defaultChecked variantColor="danger" label="danger" />

Tamanhos

preview

tamanhos.tsx

<Switch defaultChecked size="sm" label="sm" />
<Switch defaultChecked size="md" label="md" />
<Switch defaultChecked size="lg" label="lg" />

Estados

preview

ajudaDetalhe extra

ajuda

erroIsto é obrigatório

erro

desabilitado

desabilitado ✓

estados.tsx

<Switch label="ajuda" helperText="..." />
<Switch label="erro" errorMessage="..." />
<Switch label="desabilitado" disabled />
<Switch label="desabilitado" disabled defaultChecked />

Cor personalizada

`customColor` aceita qualquer cor CSS, ou um par `{ light, dark }`.

preview

Laranja

Violeta

cor-personalizada.tsx

<Switch defaultChecked customColor="#ff6600" label="Laranja" />
<Switch defaultChecked customColor={{ light: "#7c3aed", dark: "#a78bfa" }} label="Violeta" />

Props

Prop	Valores	Padrão	Descrição
variantColor	primary \| success \| warning \| danger	primary	Cor do estado marcado e do anel de foco
customColor	string \| { light, dark }	nenhum	Qualquer cor CSS (ou um par por tema). Substitui o variantColor
size	sm \| md \| lg	md	Tamanho do controle e do texto
animation	none \| smooth \| fast \| bounce	smooth	Transição ao alternar
label	ReactNode	nenhum	Texto ao lado do controle; clicar nele alterna
helperText	string	nenhum	Linha secundária abaixo do rótulo
errorMessage	string	nenhum	Texto de erro; só a presença dele já força o estado de erro
(nativas)	InputHTMLAttributes<HTMLInputElement>	nenhum	checked, defaultChecked, onChange, name, value, disabled, required, aria-*, className, ref etc.

Acessibilidade

Renderiza um `<input type="checkbox" role="switch">` nativo (oculto visualmente), então Space alterna e o estado marcado é exposto nativamente.
O `<label>` envolve o input, então o texto do rótulo dá o nome ao switch e a linha inteira é clicável.
`errorMessage` define `aria-invalid="true"`; `aria-describedby` aponta para o erro, ou para o `helperText` quando não há erro.
`disabled` é o atributo nativo: o switch sai da ordem de Tab e a linha fica esmaecida.
A trilha e o thumb são `aria-hidden`; o estado ligado/desligado não depende só da cor para tecnologias assistivas.

Teclado

Tecla	Ação
Space	Alterna o switch.

Tenha em mente

Sem `label`, passe `aria-label`; o controle não tem outro nome.
Use para ajustes que valem na hora; para escolhas enviadas depois num formulário, prefira `Checkbox`.