RadioGroup

Installation

npx gbs-add-block@latest -a RadioGroup -beta

The block copies the radio-group folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. There are no peer dependencies other than React.

Requirements

• React 19 and @types/react 19
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark(), color-mix() and :has())

Import the stylesheet once, for example in your global CSS:

@import "../components/radio-group/styles.css";

or in your root layout / entry file:

import "@/components/radio-group/styles.css";

A RadioGroup asks one question with a few mutually exclusive answers, all visible at once. The buttons are the browser's own <input type="radio"> elements sharing a name, restyled — which is what gives the group one tab stop, arrow keys that move between the choices and skip the disabled ones, and validation of the whole group as a single required field, with no JavaScript involved.

Default

Quick Start

"use client";
 
import { RadioGroup } from "@/components/radio-group";
 
export default function ReportSettings() {
  const [frequency, setFrequency] = useState<string | null>("weekly");
 
  return (
    <RadioGroup
      label="Send the report"
      name="frequency"
      options={[
        { value: "daily", label: "Daily" },
        { value: "weekly", label: "Weekly" },
        { value: "monthly", label: "Monthly" },
      ]}
      value={frequency}
      onValueChange={setFrequency}
    />
  );
}

Plain strings work where the label is the value: options={["Daily", "Weekly", "Monthly"]}.

Controlled with value + onValueChange, or uncontrolled with defaultValue. null means nothing is chosen.

For choices that need their own markup, pass <Radio> children instead:

<RadioGroup label="Delivery" name="delivery">
  <Radio value="standard" label="Standard" description="3–5 days" />
  <Radio value="express" label="Express" description="Tomorrow" />
</RadioGroup>

Which control?

Cards

variant="card" draws each choice as a bordered tile, for choices that carry a line of explanation — plans, shipping speeds, permission levels.

<RadioGroup
  label="Plan"
  variant="card"
  orientation="horizontal"
  options={[
    { value: "starter", label: "Starter", description: "Up to 3 projects" },
    { value: "team", label: "Team", description: "Unlimited projects and members" },
  ]}
/>

The whole tile is the target: the radio covers it, so a press anywhere on the card lands on the control itself rather than on a label that forwards the press. Horizontal card groups wrap, each tile taking at least 180 px.

Clearing

A radio cannot be unselected by clicking it or by keyboard. That is what the control is, not an oversight — so an optional question needs one of these:

• clearable, which offers a button that empties the group, or
• an explicit choice of its own: { value: "none", label: "No reminders" }.

The second is usually better, because "no reminders" is an answer and an empty group is an unanswered question. Use clearable when the difference matters — a filter that is either set or not.

Props Table

RadioGroup

Radio

Accepts every <input> attribute, plus:

Keyboard

None of this is implemented here: it is what the browser does with radios that share a name, in every engine and in right-to-left layouts.

Accessibility: role="radiogroup" on the fieldset, named by its legend, with aria-describedby wired to the description and the error. Disabled choices keep their label colour instead of fading, because someone still has to be able to read the option they cannot pick.

Styling and Theming

All rules are in the CSS components layer, so utility classes passed through className override them.

CSS variables

Override them on .rd-group, .rd-root, on :root, or through style. Each falls back to the shared --gbs-* of the same name, then to the DataGrid's --dg-* when that stylesheet is loaded, and finally to the built-in palette.

Data attributes

Headless Use

resolveValue is why a stale value from a record selects nothing rather than an arbitrary option: showing one would claim a choice that was never made. A disabled option still counts, because a locked-in choice has to stay visible.

Next.js

The components are client components: "use client" is at the top of the files. They render the chosen value on the server, so the page paints with the right choice already selected.

With a name, the group posts with a plain form and is read from FormData by a server action without any client state at all.

Notes

• options and children are alternatives; passing both renders the options and ignores the children.
• A group inside a <form> with required is validated by the browser, which points its own message at the first radio.