Pular para o conteúdo
Formulário

Switch

/componentes/switch.mdmarkdown cru, para quem lê com agent em vez de olho

Estados

Com rótulo

Importar
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

PropTipoPadrão
checked0.4.0

Se a chave está ligada agora.

booleansem padrão
classNames0.5.0

Classe por parte: `track` (o trilho, a chave em si), `thumb`, `label`.

Partial<Record<"label" | "thumb" | "track", string>>sem padrão
defaultChecked0.4.0

Se a chave começa ligada.

booleanfalse
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
form0.4.0

Identifica o formulário dono do campo oculto.

stringsem padrão
inputRef0.4.0

Uma ref para o `<input>` oculto.

Ref<HTMLInputElement>sem padrão
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleanfalse
onCheckedChange0.4.0

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

Se o usuário fica impedido de ligar ou desligar a chave.

booleanfalse
render0.4.0

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

Se o usuário precisa ligar a chave antes de enviar o formulário.

booleanfalse
uncheckedValue0.4.0

O valor enviado com o formulário quando a chave está desligada.

stringsem padrão
value0.4.0

O valor enviado com o formulário quando a chave está ligada.

stringsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.