RadioGroup

One choice out of a few, all in view. Rows for settings, cards for the big choices that shape what follows. Built on the vendored Base UI radio group.

Playground

RadioGroup
State

Rows

Give an item a label and the whole row becomes its target: an empty ink-tint ring, black with a white dot once chosen.

With descriptions

A description adds a quieter line under the label. It is read after the option's name, not as part of it.

Cards

RadioCard is the whole card as one target — for the few choices that shape what comes next, like the kind of business in onboarding. The chosen card gets a soft ink wash, its edge melting into it; focus rings the card. Lay the cards out on the group with className, and name the group from its legend.

What kind of business is it?

In a row

Short, parallel options can sit on one line: switch the group to flex. Arrow keys move between them either way.

Disabled

Disable the whole group, or single options — and say why next to them, so a greyed-out choice isn't a mystery.

Payment at booking

Connect payments to take deposits.

API reference

RadioGroup

PropTypeDefaultDescription
valueValue—Controlled choice. The group is typed by it, so onValueChange hands back the same type.
defaultValueValue—Initial choice when uncontrolled.
onValueChange(value: Value, details) => void—Called with the chosen item's value.
disabledbooleanfalseDisables every item.
namestring—Submits the choice with a form.
aria-labelledbystring—Point it at a FieldLegend's id — or use aria-label when there's no visible heading.
classNamestring—Layout: a stacked grid with a 12px gap by default; grid-cols-2 gap-2 for cards, flex for a row.

RadioGroupItem, RadioCard

PropTypeDefaultDescription
valueValue—What the group's value becomes when chosen.
labelReactNode—Visible name; the text is part of the target. Required on RadioCard. Without it, RadioGroupItem needs aria-label.
descriptionReactNode—A quieter line under the label, linked by aria-describedby.
disabledbooleanfalseDims the option and skips it; its text goes muted.
classNamestring—Layout for the outermost element: the row or card when labelled, else the radio.

Everything else passes through to the Base UI radio group and radio (readOnly, required, inputRef, …).

Guidelines

  • Use a RadioGroup for two to five options worth seeing side by side. More than that, or options people don't need to compare, belong in a Select.
  • Preselect the sensible default — the most common answer, or the safest. Leave the group empty only when there is no honest default and the choice must be made on purpose.
  • Cards are for the few choices that shape what follows — the kind of business, a plan. Settings and preferences stay as rows.
  • Keep labels short and parallel (“24 hours before”, “2 hours before”); move the detail into description instead of growing the label.
  • Name the group — a FieldLegend it points at with aria-labelledby, or an aria-label.
  • A radio can't be unset. For a single on/off that takes effect at once, use a Switch.