Primitiveselection

Switch

Stable

Controle que faz efeito no instante em que se move. Composto sobre Base UI Switch. A distinção para o Checkbox não é de forma e sim de produto: switch pertence a um ajuste que se aplica na hora, checkbox a um valor enviado com o formulário — uma fileira de switches acima de um botão Salvar é uma promessa que a interface não cumpre. A pista visível é menor que o alvo: um pseudo-elemento estende a área de toque para fora da trilha sem mexer no layout ao redor.

Instalação

npx up-web-ds add switch

Usage

Imports de Switch

import { Switch } from '@/components/ui/switch'
import { useId } from 'react'

Switch

1
2
3
4
5
6
7
8
9
10
11
12function ValidateOnSave() {
  const labelId = useId()

  return (
    <div className="flex items-center gap-3">
      <Switch aria-labelledby={labelId} defaultChecked />
      <span id={labelId} className="type-small font-medium">
        Validar ao salvar
      </span>
    </div>
  )
}

Props

Props de Switch
Prop	Type	Default	Description
size	`"default" \| "sm"`	`'default'`
checked	`boolean`	sem valor padrão	Whether the switch is currently active. To render an uncontrolled switch, use the `defaultChecked` prop instead.
className	`string \| ((state: SwitchRootState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
defaultChecked	`boolean`	`false`	Whether the switch is initially active. To render a controlled switch, use the `checked` prop instead.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
form	`string`	sem valor padrão	Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
id	`string`	sem valor padrão	The id of the hidden input element. When `nativeButton` is `true`, the id is applied to the root element.
inputRef	`React.Ref<HTMLInputElement>`	sem valor padrão	A ref to access the hidden `<input>` element.
name	`string`	sem valor padrão	Identifies the field when a form is submitted.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
onCheckedChange	`((checked: boolean, eventDetails: SwitchRoot.ChangeEventDetails) => void)`	sem valor padrão	Event handler called when the switch is activated or deactivated.
readOnly	`boolean`	`false`	Whether the user should be unable to activate or deactivate the switch.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, SwitchRootState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
required	`boolean`	`false`	Whether the user must activate the switch before submitting a form.
style	`React.CSSProperties \| ((state: SwitchRootState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.
uncheckedValue	`string`	sem valor padrão	The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
value	`string`	sem valor padrão	The value submitted with the form when the switch is on. By default, switch submits the "on" value, matching native checkbox behavior.

Estende SwitchPrimitive.Root.Props. Aceita também os atributos padrão de um elemento React (273 não listados).

Metadata

Notas de acessibilidade

Teclado verificado por teste: alcançável por Tab, Space e Enter alternam, e um switch desabilitado sai da sequência de tabulação recusando a alternância sem deixar de reportar o estado. Leitor de tela verificado por teste: o papel é switch e não checkbox, o nome vem do label associado — a trilha não tem texto próprio —, aria-checked carrega o estado em vez de a cor sozinha, e aria-invalid é exposto sem trocar o papel do controle. Touch verificado em navegador com emulação de toque em viewport de 375px: a trilha visível mede 36x20 no tamanho default e 28x16 no sm, mas o alvo desenhado pelo pseudo-elemento mede acima do mínimo de 24x24 da WCAG 2.2 SC 2.5.8 nos dois, e o toque alterna. Reduced motion verificado com prefers-reduced-motion: reduce — a posição do thumb é o estado, então ela nunca é condicionada: sob reduce o thumb continua indo para a ponta marcada, só sem o tween (motion-reduce:transition-none). Movimento não é o único sinal aqui — a cor da trilha e o anel de foco dizem o mesmo.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: selection
Status: Stable

Origem e distribuição

Fonte: shadcn registry / switch
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/switch.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: Nenhum
Construído sobre: Nenhum
Usado por: Nenhum ainda

Switch

Instalação

Preview

Basic

Default

Sizes

States

Settings List

All states

Usage

Props

Metadata

Notas de acessibilidade

Classificação

Origem e distribuição

Acessibilidade

Dependências