Components

Radio

Single-select control for choosing one option from a small, visible set. Mirrors the Checkbox pattern: bare control, labeled variant, description variant, and RadioGroup composer.

States

Uses a native hidden input[type="radio"] with a custom circle visual. The filled dot appears on the checked state; border and fill shift for error and disabled.

RadioGroup

The primary usage pattern. RadioGroup renders a fieldset with a legend and manages mutual exclusivity via the shared name attribute.

Team role

With descriptions

Pass a description per option to get the full-width layout — label bold above, description subdued below. Use when options need more than a one-word label.

Export format

Horizontal layout

Set layout="horizontal" for short option labels that fit inline. Wraps on narrow viewports.

Size

Error state

Pass an error string to RadioGroup. All radios in the group shift to the error border; the error message appears below.

Visibility

Select a visibility level to continue.

Sizes

sm16pxDense lists, compact forms.
md18pxDefault. Most form contexts.
lg20pxTouch-friendly, larger settings panels.

Keyboard & accessibility

TabMove focus into/out of the radio group.
↑ / ↓ or ← / →Move between options within the group and select the focused one.
fieldset + legendGroups radios semantically. Screen readers announce the group label before each option.
name attributeShared across all radios in a group — the browser enforces single-selection natively.
aria-invalidSet on the fieldset when error prop is provided.

Usage guidance

DoUse Radio for 2–5 mutually exclusive options. Show all options visibly — don't hide them in a Select.
DoAlways use RadioGroup (not bare Radio) to ensure a single selection and correct ARIA grouping.
DoPre-select a sensible default when one option is clearly the most common choice.
Don'tUse Radio for yes/no — a single Checkbox or Toggle is clearer.
Don'tUse Radio for 6+ options — use a Select dropdown instead.
Don'tMix Radio and Checkbox in the same form group — they signal different interaction models.

Tokens used

action/primaryChecked border and background
action/on-primaryInner dot color
border/baseUnchecked border
border/disabledDisabled border
bg/baseUnchecked background
bg/disabledDisabled background
status/errorError state border
border-width/boldCircle border weight (2px)
radius/fullCircle and dot shape
text/baseLabel text
text/subtleDescription text
text/disabledDisabled label and description
space/2Gap between control and label
space/3Gap between options (vertical)
space/5Gap between options (horizontal)
Figma: In progressReact: v1