Forms

Radio Group

Radio Group is an accessible grouping layer for mutually exclusive radio options with legend, helper text, and errors.

Group label + options — single selection

betaReact AvailableFigma PartialDocs Partial

React last updated: 2026-07-13
Documentation last updated: 2026-06-01
Accessibility target: WCAG 2.2 AA (target)
Version: 0.2.0-beta

Known open questions

Figma documents Radio variants but not a separate Radio Group component frame — group behavior inferred from accessibility requirements.

Live preview

Native radio inputs stay circular in every shape personality.

Standalone radios sharing a name

StarterPro

How should Radio buttons be grouped?

RadioGroup with disabled option

Billing cycle

MonthlyYearlyCustom

Group error

Validation at group level

Shipping method

StandardExpress

Select a shipping method.

Purpose

Manages mutually exclusive radio options under one accessible group label with shared name, description, and error relationships.

Anatomy

RadioGroup = fieldset + legend + Radio options + helper or ValidationMessage.

Variants and states

default · disabled · error

When to use

When 2–6 options should remain visible together and only one may be selected.

When not to use

More than ~6 options (use Select). Multiple independent selections (use Checkbox).

Accessibility

Uses fieldset and legend for the group label. Each option is a native radio input sharing the same name. Arrow keys follow native radio group behavior within the set.

Keyboard behavior

Native radio group arrow-key navigation within the shared name.

Common mistakes

Forgetting a group label/legend. Giving each radio a different name attribute.

Properties

Group label (text). Options (value + label). Required, disabled, helper, and error supported at group level.

When should a Select be used instead of a Radio Group?

Use Radio Group when every option should remain visible and the list is short (roughly 2–6 items). Use Select when space is limited or the list is too long to scan comfortably.

Tokens used

semantic/surface/defaultsemantic/border/defaultsemantic/action/primarysemantic/focus-ringsemantic/action/danger

Component API

Prop	Type	Default	Description
label	string	—	Group label rendered as legend.
options	{ value, label, disabled? }[]	—	Radio options in the group.
value	string	—	Controlled selected value.
defaultValue	string	—	Initial uncontrolled value.
error	string	—	Group-level validation message.

React example

Copy React example

import { RadioGroup } from "@/components/ui/RadioGroup";

export function Example() {
  return (
    <RadioGroup
      label="Billing cycle"
      defaultValue="monthly"
      options={[
        { value: "monthly", label: "Monthly" },
        { value: "yearly", label: "Yearly" },
      ]}
    />
  );
}