Skip to Content
ComponentsAtomsToggle

Toggle

Atom

Toggle é um botão com estado persistente. Use para alternar uma preferência visual ou modo reversível sem trocar de página.

Toggle é diferente de Switch: Switch liga/desliga comportamento imediato com semântica de chave; Toggle representa estado pressionado de um botão. Para escolhas mutuamente exclusivas em grupo, use Toggle Group ou Radio Group.

Exemplos copiáveis

React

import * as React from "react"
 
type PulsoToggleProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
  pressed: boolean
  children: React.ReactNode
}
 
export function PulsoToggle({ pressed, children, className, ...props }: PulsoToggleProps) {
  return (
    <button
      type="button"
      aria-pressed={pressed}
      data-state={pressed ? "on" : "off"}
      className={[
        "inline-flex h-9 items-center justify-center rounded-[var(--radius-sm)] border border-[var(--border)] px-3 text-sm font-medium transition-colors duration-[var(--motion-duration-fast)] ease-[var(--motion-easing)]",
        "focus-visible:outline focus-visible:outline-[var(--ring-width)] focus-visible:outline-offset-2 focus-visible:outline-[var(--ring)]",
        pressed
          ? "border-[var(--primary)] bg-[var(--primary-soft)] text-[var(--primary)]"
          : "bg-[var(--card)] text-[var(--fg-muted)] hover:text-[var(--fg)]",
        className,
      ].filter(Boolean).join(" ")}
      {...props}
    >
      {children}
    </button>
  )
}
const [dense, setDense] = React.useState(false)
 
<PulsoToggle pressed={dense} onClick={() => setDense((value) => !value)}>
  Modo denso
</PulsoToggle>

Quando usar

  • Preferência visual reversível.
  • Modo compacto/expandido em uma área.
  • Botão de estado em toolbar.
  • Alternância simples que não exige formulário.

Quando não usar

  • Para liga/desliga sistêmico; use Switch.
  • Para múltiplas opções relacionadas; use Toggle Group.
  • Para navegação; use Link/Tabs.
  • Para ação momentânea sem estado; use Button.

Acessibilidade

  • Use button com aria-pressed.
  • O label deve continuar fazendo sentido nos dois estados.
  • Estado visual precisa ter contraste e não depender só de cor.
  • Teclado deve ativar com Space/Enter naturalmente.

Regras

  1. Toggle tem estado persistente.
  2. Estado pressionado não significa risco.
  3. Não use Toggle para confirmar decisão crítica.
  4. Use motion curto e tokenizado.
  5. Se houver mais de uma opção conectada, avalie Toggle Group.
Last updated on
TextareaToggle Group