Skip to Content
ComponentsAtomsRadio Group

Radio Group

Atom

Radio Group representa escolha exclusiva. Exatamente uma opção do grupo deve ser escolhida.

Use quando todas as opções precisam estar visíveis para comparação e o conjunto é pequeno. Para muitas opções, hierarquia complexa ou busca, use Select. Para múltipla escolha, use Checkbox.

Exemplos copiáveis

React

import * as React from "react"
 
type RadioOption = {
  value: string
  label: string
  description?: string
}
 
type PulsoRadioGroupProps = {
  legend: string
  name: string
  options: RadioOption[]
  defaultValue?: string
  value?: string
  onChange?: (value: string) => void
}
 
export function PulsoRadioGroup({
  legend,
  name,
  options,
  defaultValue,
  value,
  onChange,
}: PulsoRadioGroupProps) {
  return (
    <fieldset className="grid gap-3">
      <legend className="font-mono text-[10.5px] uppercase tracking-[var(--tracking-kicker)] text-[var(--fg-subtle)]">
        {legend}
      </legend>
 
      <div className="grid gap-2">
        {options.map((option) => {
          const optionId = `${name}-${option.value}`
          const descriptionId = option.description ? `${optionId}-description` : undefined
 
          return (
            <label key={option.value} htmlFor={optionId} className="inline-flex cursor-pointer select-none items-start gap-2.5">
              <input
                id={optionId}
                type="radio"
                name={name}
                value={option.value}
                defaultChecked={defaultValue === option.value}
                checked={value ? value === option.value : undefined}
                onChange={() => onChange?.(option.value)}
                aria-describedby={descriptionId}
                className="mt-0.5 h-4 w-4 accent-[var(--primary)] focus-visible:outline focus-visible:outline-[var(--ring-width)] focus-visible:outline-offset-2 focus-visible:outline-[var(--ring)]"
              />
 
              <span className="grid gap-0.5">
                <span className="text-sm font-medium text-[var(--fg-strong)]">{option.label}</span>
                {option.description ? (
                  <span id={descriptionId} className="text-xs text-[var(--fg-muted)]">
                    {option.description}
                  </span>
                ) : null}
              </span>
            </label>
          )
        })}
      </div>
    </fieldset>
  )
}
<PulsoRadioGroup
  legend="Modo de alerta"
  name="alert-mode"
  defaultValue="grouped"
  options={[
    {
      value: "immediate",
      label: "Imediato",
      description: "Notifica no momento em que o sinal cruzar o limiar.",
    },
    {
      value: "grouped",
      label: "Agrupado · 15 min",
      description: "Consolida sinais para reduzir ruído operacional.",
    },
    {
      value: "daily",
      label: "Diário · 08:00",
      description: "Apenas resumo no início do expediente.",
    },
  ]}
/>

Quando usar

  • 2–5 opções mutuamente exclusivas.
  • Quando todas as opções precisam ficar visíveis.
  • Configurações e preferências com consequência clara.
  • Escolhas frequentes em que comparar opções reduz erro.

Quando não usar

  • Para múltipla escolha; use Checkbox.
  • Para mais de 5 opções ou listas longas; use Select.
  • Para ação imediata avulsa; use Button.
  • Para liga/desliga binário com efeito imediato; use Switch.

Variantes

VarianteUsoRegra
StandardConfigurações e formuláriosLabel sempre associado
Com descriçãoOpções com consequênciaExplique impacto operacional
Card2–4 escolhas com pesoFacilita comparação
Segmented2–4 opções curtas e frequentesBom para período, modo, escala

Acessibilidade

  • Use fieldset e legend para nomear o grupo.
  • Todas as opções compartilham o mesmo name.
  • Cada opção precisa de label clicável.
  • Descrição usa aria-describedby quando explica consequência.

Regras

  1. Uma escolha ativa por grupo.
  2. Mais de 5 opções tende a Select.
  3. Não use cor como único indicador de seleção.
  4. Card variant deve ter poucas opções e descrições curtas.
  5. Cada opção precisa explicar consequência quando afeta operação.
Last updated on
ProgressSelect