# RadioGroup

> One choice from a few: a list, inline, or cards in 1 to 3 columns.

Category: Forms. Docs page: https://rime.mjsons.net/components/radio-group

## Installation

```bash
npx shadcn@latest add KezLahd/rime/radio-group
```

RadioGroup renders real radio inputs in a fieldset. The cards variant suits two to four choices that need a sentence each (a billing period, a plan).

## Usage

```tsx
import { RadioGroup } from "@/components/ui";

<RadioGroup aria-label="Billing period" value={period} onChange={setPeriod} options={[{ value: "monthly", label: "Monthly" }, { value: "yearly", label: "Yearly" }]} />
```

## Props: RadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `ReadonlyArray<RadioOption<V>>` |  |  |
| `value` (required) | `V \| null` |  |  |
| `onChange` (required) | `(value: V) => void` |  |  |
| `name` | `string` |  | Shared native name. Generated if omitted; arrow keys work across the group natively. |
| `variant` | `"list" \| "inline" \| "cards"` | `"list"` | list = stacked radios. inline = radios in a row (Yes / No). cards = choice cards: title + description tiles (withdrawal source, delivery destination). |
| `columns` | `1 \| 2 \| 3` | `2` | cards only. Collapses to one column under 640px. |
| `invalid` | `boolean` |  |  |
| `disabled` | `boolean` |  |  |
| `required` | `boolean` |  |  |
| `aria-label` | `string` |  |  |
| `aria-labelledby` | `string` |  |  |
| `className` | `string` |  |  |

## Examples

### Cards

```tsx
<RadioGroup variant="cards" columns={3} value={v} onChange={setV} options={PERIODS} aria-label="Billing period" />
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--columns` | `2` |

System tokens it reads: `--brand`, `--brand-gradient`, `--danger-base`, `--danger-field-fill`, `--dur`, `--ease`, `--focus-ring`, `--glow-sm`, `--ink-body`, `--ink-disabled`, `--ink-heading`, `--ink-muted`, `--line`, `--neutral-border`, `--r-lg`, `--rgb-brand`, `--rgb-brand-deep`, `--rgb-contact`, `--rgb-danger`, `--rgb-white`, `--surface-solid`, `--surface-sunken`, `--text-body`, `--text-caption`, `--text-small`.

## Accessibility

- Arrow keys move the choice within the group, as native radios do.
- Radio dots stay round in every theme: a square radio reads as a checkbox.

## Do

- Prefer RadioGroup over Select for 2 to 4 options.

## Don't

- Don't preselect a choice the user must consciously make (accepting terms, a paid plan).