---
title: "RadioGroup"
description: "A vertical list of labelled options where exactly one can be chosen, kept to a single tab stop with a roving focus."
url: "https://opsinjs.pensievelabs.org/docs/components/radio-group"
source: "https://opsinjs.pensievelabs.org/docs/components/radio-group.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["radio buttons", "single choice"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="radio-group"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured, so whether the dot on the accent fill and the disabled muted ink clear the floors on this control is unknown; the accent pairs themselves are measured.&#x22;,
  &#x22;Nobody has listened to it in a screen reader, so whether a description reads usefully as part of its option is unheard.&#x22;,
  &#x22;Forced colours and prefers-contrast: more are unhandled, so whether the selection survives when the platform replaces the neutral ring and dot has not been tested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="radio-group" unbuilt="false" importPath="@/components/ui/radio-group" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { RadioGroup } from "@/components/ui/radio-group"
```

```tsx
<RadioGroup
  label="Reminder style"
  value={style}
  onValueChange={setStyle}
  options={[
    { value: "standard", label: "Standard" },
    { value: "quiet", label: "Quiet" },
    { value: "off", label: "None" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="radio-group" />

### A single choice [#a-single-choice]

Three options, one chosen. `options` carries the list, `value` marks the chosen one.

<ComponentPreview name="radio-group-a-single-choice" kind="example" align="start" />

### Options with descriptions [#options-with-descriptions]

The same list with a `description` under each label.

<ComponentPreview name="radio-group-with-descriptions" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A settled single choice of two to about seven options, such as a reminder style.&#x22;,
  &#x22;A choice whose options each need a line of helper text.&#x22;,
  &#x22;A choice laid out in full, every option visible at once.&#x22;,
]"
  avoid="[
  { case: &#x22;One or two word options that switch a parameter of a view, on one line.&#x22;, instead: &#x22;segmented-control&#x22; },
  { case: &#x22;More than about seven options, or long labels, so a select that collapses into one control reads more calmly.&#x22;, instead: &#x22;field&#x22; },
  { case: &#x22;The choice needs a label, a hint and a validation message wired to it.&#x22;, instead: &#x22;field&#x22; },
]"
/>

## Accessibility [#accessibility]

The audit found nothing to change. The rendered pass was clean, with zero axe violations,
rows floored at `--opsin-target-minimum`, focus kept visible and no sideways scroll at
320px. The source has one roving tab stop, a visible legend wired by `aria-labelledby`
rather than an `aria-label`, and selection carried three ways through `aria-checked`, the
lifted ring and the filled dot, never on colour alone.

**Residual items.**

* An option's `description` renders inside the radio, so the accessible name folds it in
  rather than exposing it through `aria-describedby`. It is announced and passes AA, and
  wiring it as a distinct description restructures the name, a redesign rather than a fix.
* The dot grows from the centre on `spring-snap` while the leaving one shrinks, and the
  row's colour fades on `duration-fast`. Under `prefers-reduced-motion` the token sheets
  collapse both to a single frame, which is what 2.3.3 asks of motion an interaction
  starts.
* Every colour is a role token, so no contrast ratio reads from the source. The measured
  pairs are the report below.

<KeyboardTable
  name="radio-group"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus into the control, onto the selected option&#x22;,
    notes: &#x22;With nothing selected, the first enabled option takes it.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back out of the control&#x22;,
    notes: &#x22;One stop in reverse too.&#x22;,
  },
  {
    keys: &#x22;Arrow Down, Arrow Right&#x22;,
    action: &#x22;Moves to the next option and selects it&#x22;,
    notes: &#x22;Wraps, skips disabled. Left and Right swap under right-to-left.&#x22;,
  },
  {
    keys: &#x22;Arrow Up, Arrow Left&#x22;,
    action: &#x22;Moves to the previous option and selects it&#x22;,
    notes: &#x22;Wraps, skips disabled options.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Selects the focused option&#x22;,
    notes: &#x22;The activator of a role=\&#x22;radio\&#x22;.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Does nothing&#x22;,
    notes: &#x22;The primitive cancels Enter, so no form submits by accident.&#x22;,
  },
  {
    keys: &#x22;Home, End&#x22;,
    action: &#x22;Not bound&#x22;,
    notes: &#x22;The primitive does not enable them. The browser default stands.&#x22;,
  },
]"
/>

<ContrastReport component="radio-group" />

## Props interface [#props-interface]

<PropsTable name="RadioGroupProps" />

`value` and `onValueChange` make this controlled, with no internal state. A `value`
matching no option renders nothing chosen and warns in development. A disabled
option stays in the list, drawn in the muted ink and skipped by the Arrow keys. No
options renders nothing.
