Radio

When to use

• One answer from a short list. A handful of visible options that benefit from side-by-side comparison. Past a handful, reach for Select: the group costs more vertical space than the comparison is worth.
• A choice that must be made. A radio cannot be unticked, so use it when an answer is required. Where the person may want none, include a "None of the above" option.
• Vertical by default. Horizontal groups save space in dense layouts but scan worse and break under localization; keep them to a few short options.
• A safe default, or none. Pick the safest, lowest-risk option as defaultValue, or leave the group unselected and pair required with a "None of the above" option when the choice must be deliberate, so a skipped question is never mistaken for an answered one. Never preselect a high-risk option (payments, privacy, deletion).
• Options in a logical order, each with a visible reason when unavailable: a disabled option with its reason in description reads better than a missing one.

When not to use

• For multi-select. Zero-or-more selection is a Checkbox group. Radio and checkbox are not interchangeable.
• For a long list. Use Select once the options stop fitting comfortably on screen.
• To switch a view or mode in place. That is SegmentedControl's job; a radio group is a form answer. Filter chips that select one value are Chips.
• For an on/off setting. Use Switch.
• When the answer may be nothing. Add a "None" option, or use a Checkbox.

Installation

pnpm add @tessinaui/ui

Usage

import { Radio, RadioGroup } from "@tessinaui/ui";

{/* Uncontrolled group */}
<RadioGroup defaultValue="email" label="Contact method">
  <Radio value="email" label="Email" />
  <Radio value="sms"   label="SMS"   />
  <Radio value="phone" label="Phone" />
</RadioGroup>

{/* Controlled group */}
<RadioGroup value={method} onValueChange={setMethod} label="Contact method">
  <Radio value="email" label="Email" />
  <Radio value="sms"   label="SMS" />
</RadioGroup>

{/* With a group error */}
<RadioGroup required label="Plan" errorMessage="Please select an option.">
  <Radio value="a" label="Option A" />
  <Radio value="b" label="Option B" />
</RadioGroup>

Examples

Default

A radio group with three options and a group label.

Sizes

Five indicator sizes — xs, sm, md, lg, and xl. Tap targets stay ≥44px on touch viewports at every size.

Intents

Semantic colors for the ring and glyph — none, error, warning, success, and info.

With descriptions

Each option pairs a label with helper text below it.

Validation

A required group error, and a warning message — an explicit intent keeps its color instead of being repainted red.

States

Disabled (with an in-description reason), loading, and a read-only group — focusable and announced, but not operable.

Settings rows

labelPlacement="start" + fullWidth is the mobile settings-row: text leading, control trailing, the whole row one tap target. Dividers are composition (divide-y), not a prop.

Horizontal

orientation="horizontal" wraps options in a row — with a group description and an optional marker.

Rich labels

Labels take ReactNode — links inside a label keep working without changing the selection. Pass aria-label when rich content would read poorly.

Icon and trailing slots

The checkout pattern: a leading mark via icon, the fee via trailing. Both slots are decorative to assistive tech. The icon slot is one label line tall, so an icon up to that height (16, 20, 20, 24 and 28px from xs to xl) centres on the label's first line; a taller one grows the row and aligns with the top of the label.

Check indicator

indicator="check" swaps the selected dot for a check mark, propagated from the group.

Cards

Full-surface RadioCard options arranged in a card group.

Card badges and pricing

A badge pinned over the card's top edge joins the accessible description; the price lives in trailing.

Card anatomy

Indicator leading the content, no indicator at all (border + tint carry the selection), and arbitrary children below the description.

Form integration

name submits through a hidden input and required marks the group invalid until a selection exists. noValidate on the form suppresses the browser's own validation bubble so the message is the group's errorMessage — house styling, a polite live region, in the flow of the form rather than a tooltip that disappears on the next click — and focus moves to the group on failure.

On a coloured surface

Wrap a region in <Surface> and every radio inside inherits tone="on-color". The ring becomes the plate's well behind an ink boundary, the selected ring turns into the inverse chip, an intent keeps its own fill, and the label, description and error line take the plate's inks. A RadioCard stays a page panel on the plate.

RTL

dir="rtl" on the group mirrors every row: the ring moves to the right edge, text aligns right, and a labelPlacement="start" settings row puts the ring on the left. labelPlacement is logical, so it never needs flipping by hand. Leave dir unset and the group follows the page's direction.

API Reference

Radio props

All other native and aria-* attributes are forwarded to the control (Base UI <span role="radio"> + hidden input) — the documented form-control exception shape (§7).

RadioGroup props

RadioCard props

rounded shapes the card, never the radio inside it: the indicator ring and its dot stay circular at every card radius, because a circle is what makes a radio read as a radio (QA flow §7.4 identity geometry — the same rule that keeps status dots, the switch thumb and the slider thumb round). This is where RadioCard and CheckboxCard diverge on purpose — a square box is a checkbox's identity, so its indicator does follow the card.

RadioCardGroup props

Same value/name/validation/propagation surface as RadioGroup, plus columns (1 \| 2 \| 3 \| 4, default 2) and indicator/rounded propagation. Renders the same named-fieldset semantics. Its tone colours the legend and helper text on a coloured surface; each card stays a page panel.

RadioSkeleton props

States

Sizes

Accessibility

Pattern: WAI-ARIA Radio Group, via Base UI's roving-tabindex implementation.

• The group renders as one <fieldset role="radiogroup"> named by its <legend> (direct child) via aria-labelledby — no nested groups.
• The wrapping <label> row makes the whole row the tap target; the control is named by the label text span alone, so the required asterisk, error text and slots never pollute the accessible name.
• description and errorMessage reach the control via aria-describedby (resolvable ids, asserted in tests); errors are polite live regions and set aria-invalid.
• Touch targets: 44px overlays + ≥44px row pitch on touch viewports; the 24px WCAG 2.5.8 minimum at desktop density, where 44px overlays would overlap stacked rows and steal neighbour clicks.
• forced-colors: states map to ButtonText / SelectedItem / GrayText.
• Reduced motion: the glyph transitions and the press scale are gated ON with motion-safe:, so reduced motion simply never starts them.
• Contrast (audit:contrast, both themes): a checked intent="warning" radio's raw-amber fill reads 2.2:1 against the light page, under the 3:1 WCAG 1.4.11 asks. That is the intent palette's own ceiling, accepted design-system-wide (§9, TES-272), not a Radio tuning miss, and the state never rests on the amber: the on-warning dot (or check) marks checked and is gated at 9.7:1 against the fill, and the unchecked warning boundary steps to warning-tinted-foreground (7.1:1 in light). Every other checked fill and unchecked boundary clears 3:1.
• AT matrix: VoiceOver + Safari passed 2026-09-14 — "Contact method, radio group", then "Email, selected, radio button, 1 of 3"; Down arrow selects and reads "SMS, selected, radio button, 2 of 3", then "Phone … 3 of 3". NVDA and JAWS untested (no Windows on the bench).