Radio

Playground

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>

When to use

• 2–5 visible options that benefit from side-by-side comparison. Past ~5, reach for Select — Material, Fluent and the macOS HIG all converge on the same ceiling.
• Vertical by default. Horizontal groups save space in dense layouts but scan worse and break under localization; avoid them past ~4 short options.
• Not a view switcher. Switching between views or modes in place is SegmentedControl's job; a radio group is a form answer. Filter chips that select one value are Chips.
• Not multi-select. Zero-or-more selection is a Checkbox group. Radio and checkbox are not interchangeable.
• Defaults: 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 (the GOV.UK posture). Never preselect a high-risk option (payments, privacy, deletion).
• A disabled option with a visible reason reads better than a missing one — put the reason in description.

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.

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.

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.

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 are gated ON with motion-safe:, so reduced motion simply never starts them, and the press scale is reset with motion-reduce:active:scale-100.
• AT matrix: VoiceOver + Safari verified locally; NVDA and JAWS untested (no Windows on the bench) — tracked for the next release pass.