# Radio group

> One choice from a few: the dot pops into the new circle, or, as cards, one selection frame glides from card to card.

Radio cards usually blink a ring off one card and onto another. Here the selection is one frame that glides to the new card, easing its height when the cards differ, while the dot shrinks out of the old circle and pops into the new one. Real radio inputs underneath, so arrow keys and forms work natively.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/radio-group.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `ui-interaction-motion`
- Docs and live preview: https://hairlineui.com/ui/radio-group
- Registry item (source): https://hairlineui.com/r/radio-group.json

## Usage

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

<RadioGroup
  label="Plan"
  variant="cards"
  defaultValue="pro"
  options={[
    { value: "starter", label: "Starter", description: "One template", aside: "$39" },
    { value: "pro", label: "All access", description: "Every template, every update", aside: "$99" },
  ]}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `RadioOption[]` | – | value, label, description, aside, disabled. |
| `value / defaultValue` | `string` | – | Chosen value. |
| `onValueChange` | `(value: string) => void` | – | Called on choice. |
| `label` | `string` | – | Accessible name (a legend). |
| `showLabel` | `boolean` | `false` | Show the legend. |
| `variant` | `"list" \| "cards"` | `"list"` | Plain dots or cards. |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Direction of the options. |

## States

- **list**: The dot pops into the new circle (380ms, slight overshoot) as it shrinks out of the old.
- **cards**: The frame glides to the new card (420ms) and its height eases (380ms).
- **focus**: The ring and halo on the circle, from the keyboard.

## What it handles

Card-style radios often lose arrow-key navigation because they are built from buttons. These are native radios with the frame drawn over them.

- **One moving frame**: Measured from layout, thrown to the new card with a slight overshoot.
- **Native keyboard**: Arrow keys move and select, Tab enters at the chosen one.
- **Cards or list**: Same API; cards add a description and an aside.
- **Forms**: A real name and value for each option.

## Replaces

radio cards, selection ring animation, fieldset and legend wiring

## Where it fits

- **Plan pickers**: Cards with a price on the right.
- **Shipping and delivery**: Options with a description line each.
- **Settings**: A short vertical list of exclusive choices.
- **Onboarding questions**: Horizontal options in a single row.

## Notes

- A fieldset with a legend; disabled disables the whole group.
- Reduced motion: the frame and dot move at once.

License: MIT (https://hairlineui.com/license#components)