Radio Group

Single-choice selection pattern for plans, preferences, and mutually exclusive options with accessible radio semantics and keyboard-friendly structure.

AccessibleDark ModeKeyboard Nav

Install

$npx react-principles add radio-group

Live Demo

Open in Storybookopen_in_new

Selected plan: pro

Code Snippet

src/ui/RadioGroup.tsx

import { RadioGroup } from "@/ui/RadioGroup";

<RadioGroup value={plan} onValueChange={setPlan}>
  <RadioGroup.Item value="starter" label="Starter" description="Best for side projects" />
  <RadioGroup.Item value="pro" label="Pro" description="For production apps" />
  <RadioGroup.Item value="enterprise" label="Enterprise" description="Advanced controls" />
</RadioGroup>

Copy-Paste (Single File)

RadioGroup.tsx

import { createContext, useContext, useId, useState, type HTMLAttributes, type ReactNode } from "react";
import { cn } from "@/lib/utils";

export interface RadioGroupProps extends HTMLAttributes<HTMLDivElement> {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  name?: string;
  children: ReactNode;
}

Props

Prop	Type	Default	Description
`value`	`string`	`—`	Controlled selected value for the root radio group.
`defaultValue`	`string`	`""`	Initial selected value when the group is uncontrolled.
`onValueChange`	`(value: string) => void`	`—`	Called when users pick a different radio option.
`name`	`string`	`Generated id`	Sets the shared hidden input name for the group.
`RadioGroup.Item.value`	`string`	`—`	Unique item value submitted when the option is selected.
`RadioGroup.Item.disabled`	`boolean`	`false`	Disables an individual option and prevents interaction.
`RadioGroup.Item.label`	`string`	`—`	Primary label text rendered inside the option card.
`RadioGroup.Item.description`	`string`	`—`	Secondary helper text rendered below the label.

react-principles