Switch
Estados
Com rótulo
import { Switch } from '@rivocode/ui'Quando usar
Chave de liga e desliga, para o que muda na hora.
O alvo tem 44px de altura mesmo com o trilho de 24, por respiro invisível: é a medida do dedo.
O rótulo
Passe o texto como filho e a chave sai dentro de um <label>, então clicar no
texto também liga:
<Switch defaultChecked>Mandar o código de rastreio por SMS</Switch>
Sem filho, sai só a chave. Vale para linha de ajuste onde o texto tem descrição embaixo e a chave fica na ponta direita.
Classe na raiz
O className veste a raiz: com texto, é o <label> que leva a chave e o
texto; sem texto, a própria chave. É ele que posiciona a peça inteira
(basis-full, mt-2). O trilho tem a parte dele, classNames.track, ao lado
de thumb e label. O Checkbox e o Radio seguem a mesma regra, com box
e circle no lugar de track.
<Switch className="basis-full" classNames={{ track: 'h-7 w-12' }}>
Enviar o XML junto com o PDF
</Switch>
O trilho ligado
O trilho ligado pinta accent-text, e não accent: é a mesma cor da marca um
passo mais escura, porque a cor cheia some sobre a página clara (fica abaixo dos
3:1 que a WCAG 1.4.11 pede para controle). Com accent-text o trilho mede 5,55:1
sobre a página e 5,75:1 sobre o cartão. O pino ligado vai em surface-raised e
é o que se lê dentro do trilho.
Quem escreve tema de cliente herda a garantia sem fazer nada: accent-text já
precisa de 4,5:1 sobre os fundos para o texto de acento, e é a mesma medida que
o trilho usa.
Desabilitado
Desabilitado se pinta com token, e não com opacidade, como no Checkbox e no
Radio. O trilho já é a superfície apagada quando a chave está desligada, então
aqui quem diz travado é o pino: ele vai de fg-muted para fg-disabled, e o
trilho perde o acento quando ligado.
Não vale devolver um acento lavado ao trilho ligado-e-travado para o "ligado" continuar óbvio: medido, o pino cai para 2,5:1 sobre ele no tema escuro, abaixo dos 3:1 da WCAG 1.4.11. E o pino é o único lugar onde se lê a chave.
Quando não usar
Dentro de um formulário que tem botão de salvar, use Checkbox. Não é o mesmo
controle de outro formato: a chave age no clique e o efeito é imediato; a
caixa responde uma pergunta que só vale quando o formulário for enviado. Uma
chave em cima de um Salvar deixa a pessoa sem saber se já valeu, e se ela sair
da tela sem salvar, a resposta é não.
No React Native
Traduz: o @rivocode/ui-native exporta Switch - checked e onCheckedChange obrigatórios; o trilho e o pino são desenhados pela casa, iguais no iOS e no Android, e o pino desliza no movimento da casa, parado com reduzir movimento; label é o nome falado, obrigatório sem children; classNames com track, thumb e label, as partes do web. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.
API
| Prop | Tipo | Padrão |
|---|---|---|
checked0.4.0Se a chave está ligada agora. | boolean | sem padrão |
classNames0.5.0Classe por parte: `track` (o trilho, a chave em si), `thumb`, `label`. | Partial<Record<"label" | "thumb" | "track", string>> | sem padrão |
defaultChecked0.4.0Se a chave começa ligada. | boolean | false |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
form0.4.0Identifica o formulário dono do campo oculto. | string | sem padrão |
inputRef0.4.0Uma ref para o `<input>` oculto. | Ref<HTMLInputElement> | sem padrão |
name0.4.0Identifica o campo quando o formulário é enviado. | string | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
onCheckedChange0.4.0Chamado quando a chave liga ou desliga. | ((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void) | sem padrão |
readOnly0.4.0Se o usuário fica impedido de ligar ou desligar a chave. | boolean | false |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, SwitchRootState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
required0.4.0Se o usuário precisa ligar a chave antes de enviar o formulário. | boolean | false |
uncheckedValue0.4.0O valor enviado com o formulário quando a chave está desligada. | string | sem padrão |
value0.4.0O valor enviado com o formulário quando a chave está ligada. | string | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.