Skip to Content
ComponentsAtomsToggle Group

Toggle Group

Atom

Toggle Group organiza opções curtas relacionadas. Use quando a comparação visual entre opções compactas ajuda a operar mais rápido.

Use type="single" quando apenas uma opção pode estar ativa. Use type="multiple" quando as opções são independentes. Para escolhas com descrição ou consequência pesada, prefira Radio Group ou Checkbox.

Exemplos copiáveis

React

import * as React from "react"
 
type ToggleOption = {
  value: string
  label: string
}
 
type PulsoToggleGroupProps = {
  label: string
  options: ToggleOption[]
  value: string
  onChange: (value: string) => void
}
 
export function PulsoToggleGroup({ label, options, value, onChange }: PulsoToggleGroupProps) {
  return (
    <div role="group" aria-label={label} className="inline-flex rounded-[var(--radius-md)] border border-[var(--border)] bg-[var(--muted)] p-1">
      {options.map((option) => {
        const selected = option.value === value
 
        return (
          <button
            key={option.value}
            type="button"
            aria-pressed={selected}
            data-state={selected ? "on" : "off"}
            onClick={() => onChange(option.value)}
            className={[
              "min-h-8 rounded-[var(--radius-sm)] 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)]",
              selected ? "bg-[var(--card)] text-[var(--fg)] shadow-[var(--shadow-sm)]" : "text-[var(--fg-muted)] hover:text-[var(--fg)]",
            ].join(" ")}
          >
            {option.label}
          </button>
        )
      })}
    </div>
  )
}
const [period, setPeriod] = React.useState("7d")
 
<PulsoToggleGroup
  label="Período"
  value={period}
  onChange={setPeriod}
  options={[
    { value: "24h", label: "24h" },
    { value: "7d", label: "7d" },
    { value: "30d", label: "30d" },
  ]}
/>

Quando usar

  • Período curto: 24h / 7d / 30d.
  • Modo de visualização: lista, tabela, timeline.
  • Escala simples: linear/log.
  • Filtros compactos com opções curtas.

Quando não usar

  • Para opções longas ou com descrição.
  • Para decisões críticas com consequência complexa.
  • Para navegação entre páginas.
  • Para listas com muitas opções; use Select.

Acessibilidade

  • Use role="group" com aria-label.
  • Cada item deve ser botão com aria-pressed.
  • Se o grupo for semanticamente escolha exclusiva de formulário, Radio Group pode ser mais correto.
  • Estado ativo precisa ser visível sem depender apenas de cor.

Regras

  1. Labels curtos: idealmente 1 palavra ou abreviação conhecida.
  2. Altura e peso visual consistentes entre opções.
  3. Não misture single e multiple no mesmo grupo.
  4. Motion deve ser curto e suave, sem deslocamento exagerado.
  5. Use Radio Group quando a consequência precisa de descrição.
Last updated on
ToggleTooltip