RadioGroup

<RadioGroup> is a mutually-exclusive choice — exactly one of N options is selected. Use when the user benefits from seeing every option at once.

import from "@na/ui/components/radio-group" ▶ Open in Storybook packages/ui/src/components/radio-group.tsx

When to use

• 2–5 visible-at-once options where the user benefits from comparing them.
• Onboarding “pick a path” steps.

Don’t use RadioGroup for: > 5 options (Select — see-on-demand, less visual weight), inline-toolbar choices (SegmentedControl — same shape but stylized as one segmented bar), or cases where one option is so much more common that it should be the default and others are tucked away.

Default

Daily digestWeekly digestNever

<RadioGroup defaultValue="weekly">
  <Label className="flex items-center gap-2">
    <RadioGroupItem value="daily" />
    Daily digest
  </Label>
  <Label className="flex items-center gap-2">
    <RadioGroupItem value="weekly" />
    Weekly digest
  </Label>
  <Label className="flex items-center gap-2">
    <RadioGroupItem value="never" />
    Never
  </Label>
</RadioGroup>

With descriptions

When each option needs explanation, pair the label with a muted description below.

Lite

Up to 5 agents, 1 environment.

Standard

Unlimited agents, 3 environments, audit log.

Enterprise

SSO, dedicated infra, SLA.

API

RadioGroup

Prop	Type	Default	Description
value	string	—	Controlled value. Pair with onValueChange.
defaultValue	string	—	Initial value for uncontrolled mode.
onValueChange	(value: string) => void	—	Fires on every change.
disabled	boolean	false	Disable every item.
name	string	—	Form-submission name.
orientation	"vertical" | "horizontal"	"vertical"	Drives arrow-key navigation direction.

RadioGroupItem

Prop	Type	Default	Description
value *	string	—	Unique value within the group.
disabled	boolean	false	Disable this item only.
id	string	—	For pairing with <Label htmlFor>. Optional when wrapped in Label.

Design guidelines

✓ Do

• Order options by frequency or by natural sequence (Daily / Weekly / Never). Don't alphabetize.
• Pre-select the most-common option as default. Forcing a click for the obvious answer is friction.
• Use vertical layout. Horizontal radio rows often look like SegmentedControl mid-evolution.

✗ Don't

• Use RadioGroup for > 5 options. The user can't scan the whole list — that is Select.
• Mix radio and checkbox in the same group. Pick one cardinality.
• Show options without descriptions when one or more are non-obvious. Add the description.

Accessibility

• Composes Radix RadioGroup — role="radiogroup", items as role="radio", arrow-key navigation between items, Space selects.
• Pair items with <Label htmlFor> or wrap them.
• For dynamic value changes (a setting toggle), set aria-live="polite" on the parent if the consequence is announced elsewhere.

Related

• SegmentedControl — Visually compact, same cardinality.
• Select — When the option count grows.
• RadioCardGroup — Card-style radios for onboarding (planned).

▶ Open RadioGroup stories in Storybook