Components

Radio group

Choose exactly one option from a small set. Same visual patterns as Checkbox but circular and mutually exclusive. The RadioField compound handles label + description in a single component.

Updated Jul 8, 2026 by Leonardo Posada

Primitive

The base RadioGroup + RadioGroupItem give you full layout control. Use them when a table row or custom layout requires it.

Box only
<RadioGroup defaultValue="usd">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="usd" id="usd" />
    <Label htmlFor="usd">USD</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="cop" id="cop" />
    <Label htmlFor="cop">COP</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="mxn" id="mxn" />
    <Label htmlFor="mxn">MXN</Label>
  </div>
</RadioGroup>
States
<RadioGroup defaultValue="on">
  <RadioGroupItem value="on" />
  <RadioGroupItem value="off" />
  <RadioGroupItem value="disabled" disabled />
  <RadioGroupItem value="disabled-on" disabled />
</RadioGroup>

RadioField

Compound that pairs each RadioGroupItem with its label and optional description. Same API as CheckboxField.

Label only
<RadioGroup defaultValue="monthly">
  <RadioField value="monthly" label="Monthly" />
  <RadioField value="annual" label="Annual" />
  <RadioField value="lifetime" label="Lifetime" />
</RadioGroup>
Label + description

Up to 3 seats, basic reporting.

Up to 20 seats, advanced reporting and rules.

Custom seats, SSO, dedicated support.

<RadioGroup defaultValue="team">
  <RadioField
    value="starter"
    label="Starter"
    description="Up to 3 seats, basic reporting."
  />
  <RadioField
    value="team"
    label="Team"
    description="Up to 20 seats, advanced reporting and rules."
  />
  <RadioField
    value="enterprise"
    label="Enterprise"
    description="Custom seats, SSO, dedicated support."
  />
</RadioGroup>

When to use

  • 2–5 mutually exclusive options (choose only one).
  • Settings where all options should be visible at once.
  • Quick single-choice inside a form (payment method, currency, plan).

When not to use

  • Multi-select — use a Checkbox group.
  • More than ~5 options — use a Select or Combobox.
  • Only 2 options that are on/off — use a Switch.

Usage

Do
  • Show all options at once — that's the whole point of radios.
  • Default to the safest / most common option.
  • Use RadioField with description when options need extra context (plan features, permissions).
  • Vertical layout is the default; only go horizontal when labels are super short.
Don't
  • Don't hide options behind a Show more — put them all in view.
  • Don't use radios when the choice is 'true/false' — that's a Switch.
  • Don't leave the group without a default selection unless the field is optional.