Capítulo 27 de 108

Radio Group

Core Idea

Conjunto de botões marcáveis onde no máximo um pode estar selecionado por vez. Use para escolha única entre opções mutuamente exclusivas (plano, densidade de layout, preferência de notificação).

Key Concepts

  • RadioGroup: container que controla o valor selecionado (defaultValue ou value/onValueChange).
  • RadioGroupItem: cada opção individual; requer value único e id para associar ao Label/FieldLabel.
  • disabled: no RadioGroup desabilita todos os itens; no RadioGroupItem desabilita só um item.
  • aria-invalid: em cada RadioGroupItem para indicar erro de validação (usar com data-invalid no Field).
  • Base: construído sobre @base-ui/react (Base UI Radio Group).

Code Examples

import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

<RadioGroup defaultValue="option-one">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="option-one" id="option-one" />
    <Label htmlFor="option-one">Option One</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="option-two" id="option-two" />
    <Label htmlFor="option-two">Option Two</Label>
  </div>
</RadioGroup>
  • O que demonstra: uso básico não controlado com defaultValue.
<RadioGroup defaultValue="plus" className="max-w-sm">
  <FieldLabel htmlFor="plus-plan">
    <Field orientation="horizontal">
      <FieldContent>
        <FieldTitle>Plus</FieldTitle>
        <FieldDescription>For individuals and small teams.</FieldDescription>
      </FieldContent>
      <RadioGroupItem value="plus" id="plus-plan" />
    </Field>
  </FieldLabel>
  {/* ... demais planos */}
</RadioGroup>
  • O que demonstra: padrão "choice card" - FieldLabel envolve o Field inteiro, tornando o card inteiro clicável.

Reference Tables

Composição:

RadioGroup
├── RadioGroupItem
└── RadioGroupItem

Anti-patterns

  • RadioGroupItem sem id único: quebra a associação com Label/FieldLabel e a acessibilidade de clique no texto.
  • Usar RadioGroup para seleção múltipla: nesse caso o componente correto é um grupo de Checkbox.

Key Takeaways

  1. RadioGroup é o container de estado; RadioGroupItem só define o value de cada opção.
  2. Para card clicável (choice card), envolva Field inteiro em FieldLabel, não apenas o texto.
  3. FieldSet + FieldLegend agrupam o RadioGroup com um título e descrição comuns, útil para grupos formais (ex: "Subscription Plan").
  4. Estado inválido segue padrão duplo: aria-invalid em cada RadioGroupItem + data-invalid no Field.
  5. disabled no nível do RadioGroup desabilita tudo; no nível do item, desabilita seletivamente.

Connects To

  • Field / FieldSet / FieldLegend: fornecem label, descrição e agrupamento visual/semântico para o grupo.
  • Checkbox: use quando a seleção pode ser múltipla em vez de exclusiva.
  • Select: alternativa quando há muitas opções e não se quer ocupar espaço vertical com todos os itens visíveis.
AnteriorCheckboxPróximoSelect