# Radio

Page: /docs/components/radio

{/* Figma: Meridian → Radio (docs 41:48, component sets 18:1375 and 18:1913). Spec: docs/design-system/meridian/radio.md */}

One choice from a short set: 16 circles with 14 labels built in, and Radio card for choices that need a title and a description. On the site it asks things like company size on a demo form or the plan someone wants to hear about.

```tsx
import { RadioGroup } from "@commenda/meridian/ui/radio";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

export function RadioBasic() {
	return (
		<Panel>
			<RadioGroup
				label="Company size"
				defaultValue="1-50"
				options={[
					{ value: "1-50", label: "1 to 50 employees" },
					{ value: "51-500", label: "51 to 500 employees" },
					{ value: "500+", label: "More than 500 employees" },
				]}
			/>
		</Panel>
	);
}
```

## Usage [#usage]

```tsx
import { RadioGroup } from "@commenda/meridian/ui/radio";

<RadioGroup
  label="Company size"
  options={[
    { value: "1-50", label: "1 to 50 employees" },
    { value: "51-500", label: "51 to 500 employees" },
  ]}
  onValueChange={setSize}
/>;
```

## A group [#a-group]

Stacked, 8 apart, with one chosen. Two to five options; more is a Select.

```tsx
import { RadioGroup } from "@commenda/meridian/ui/radio";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

export function RadioBasic() {
	return (
		<Panel>
			<RadioGroup
				label="Company size"
				defaultValue="1-50"
				options={[
					{ value: "1-50", label: "1 to 50 employees" },
					{ value: "51-500", label: "51 to 500 employees" },
					{ value: "500+", label: "More than 500 employees" },
				]}
			/>
		</Panel>
	);
}
```

## With descriptions [#with-descriptions]

A line under each label when the options need explaining.

```tsx
import { RadioGroup } from "@commenda/meridian/ui/radio";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

export function RadioDescriptions() {
	return (
		<Panel>
			<RadioGroup
				label="What would you like?"
				defaultValue="demo"
				options={[
					{
						value: "demo",
						label: "Book a demo",
						description: "A 30-minute call with a product specialist.",
					},
					{
						value: "expert",
						label: "Talk to a tax expert",
						description: "Questions about your filings before you buy.",
					},
				]}
			/>
		</Panel>
	);
}
```

## States [#states]

The same states as Checkbox.

```tsx
import { RadioGroup } from "@commenda/meridian/ui/radio";

function Panel({ children, grid = false }: { children: React.ReactNode; grid?: boolean }) {
	return (
		<div
			className={`not-prose my-4 rounded-xl border border-fd-border bg-white p-8 ${
				grid ? "grid gap-4 md:grid-cols-3" : "flex flex-col gap-2"
			}`}
		>
			{children}
		</div>
	);
}

export function RadioStates() {
	return (
		<Panel>
			<RadioGroup
				label="Billing"
				orientation="horizontal"
				defaultValue="annual"
				options={[
					{ value: "annual", label: "Annual" },
					{ value: "monthly", label: "Monthly" },
					{
						value: "quarterly",
						label: "Quarterly",
						disabled: true,
						disabledReason: "Not offered yet",
					},
				]}
			/>
			<p className="mt-2 text-[12px] text-fd-muted-foreground">
				Hover and Tab to see hover and focus.
			</p>
		</Panel>
	);
}
```

## Radio card [#radio-card]

For bigger choices that need a title and a description, like a plan or a product. The whole card is the click target. When several can be chosen, use a [Checkbox card](/docs/components/checkbox#checkbox-card).

```tsx
import { RadioGroup } from "@commenda/meridian/ui/radio";

export function RadioCards() {
	return (
		<div className="not-prose my-4 rounded-xl border border-fd-border bg-white p-8">
			<RadioGroup
				label="Plan"
				variant="card"
				orientation="horizontal"
				defaultValue="starter"
				options={[
					{
						value: "starter",
						label: "Starter",
						description: "For companies registered in a few states.",
					},
					{ value: "growth", label: "Growth", description: "For companies selling across the US." },
					{
						value: "enterprise",
						label: "Enterprise",
						description: "For groups with entities in many countries.",
					},
				]}
			/>
		</div>
	);
}
```

## Anatomy [#anatomy]

Circle 16, 1px border soft-pearl 400. Chosen fills blue 700 with a 6 white dot. The label is 14 and sits 8 to the right, the description 2 below. Radio card: 1px border, radius 8, padding 16, control and text 12 apart.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `options` (required) | `readonly RadioOption[]` |  |
| `style` | `CSSProperties \| ((state: RadioGroupState) => CSSProperties \| undefined)` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `form` | `string` | Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form. |
| `disabled` | `boolean` | Whether the component should ignore user interaction. |
| `name` | `string` | Identifies the field when a form is submitted. |
| `readOnly` | `boolean` | Whether the user should be unable to select a different radio button in the group. |
| `required` | `boolean` | Whether the user must choose a value before submitting a form. |
| `inputRef` | `((instance: HTMLInputElement \| null) => void \| (() => VoidOrUndefinedOnly) \| DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) \| RefObject<HTMLInputElement \| null>` | A ref to access the hidden input element. |
| `hideLabel` | `boolean` |  |
| `description` | `string` |  |
| `variant` | `"default" \| "card"` |  |
| `orientation` | `"vertical" \| "horizontal"` |  |
| `className` | `string` |  |
| `value` (conditional) | `string` |  |
| `defaultValue` | `string` |  |
| `onValueChange` (conditional) | `(value: string) => void` |  |

## Best practices [#best-practices]

- Use Radio for one choice from two to five options that should all stay visible. More than five, or when space is tight, use a Select.
- Start with one option chosen when there is a sensible default. Leave the group empty only when choosing is the point, as on a HubSpot form where the answer qualifies the lead.
- Order options by size or time, not alphabetically by default.
- Use Radio card when each option needs a title and a description. Keep cards in a row the same height.
- For a single on or off choice, use a Checkbox or a Switch, never one radio.
- Source: Pathfinder Radio. Meridian sets labels in 14 and descriptions in 14.
