# Radio Group

A set of mutually exclusive options.

- Category: Core Elements
- Page: https://wunderui.com/components/radio-group
- Tier: Free

## Install

```bash
npx wunderui-cli add radio-group
```

## Import

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

## Minimal usage

Then use it:

```tsx
import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export function Delivery() {
  return (
    <RadioGroup defaultValue="standard" aria-label="Delivery method" className="gap-3">
      <div className="flex items-start gap-2">
        <RadioGroupItem id="standard" value="standard" className="mt-0.5" />
        <Label htmlFor="standard" className="leading-5">
          Standard delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="express" value="express" className="mt-0.5" />
        <Label htmlFor="express" className="leading-5">
          Express delivery
        </Label>
      </div>
    </RadioGroup>
  )
}
```

Expected result: You should see two options, Standard delivery chosen and Express delivery empty. A click on an option or its text chooses it, and the arrow keys move between them.

## Usage

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <RadioGroup defaultValue="standard" aria-label="Delivery method" className="gap-3">
      <div className="flex items-start gap-2">
        <RadioGroupItem id="standard" value="standard" className="mt-0.5" />
        <Label htmlFor="standard" className="leading-5">
          Standard delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="express" value="express" className="mt-0.5" />
        <Label htmlFor="express" className="leading-5">
          Express delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="pickup" value="pickup" className="mt-0.5" />
        <Label htmlFor="pickup" className="leading-5">
          Store pickup
        </Label>
      </div>
    </RadioGroup>
  )
}
```

## When to use

### Use Radio Group for

- Exactly one choice from a short list, such as a delivery method or a plan
- Options with a description, so people can compare them before they choose
- A list that should stay visible instead of hiding in a menu

### Use something else

- [Checkbox](https://wunderui.com/components/checkbox) for several choices from a list, or one on or off choice
- [Switch](https://wunderui.com/components/switch) for a setting that takes effect at once
- [Radio Button Group](https://wunderui.com/components/radio-button-group) for one choice shown as a row of buttons
- [Segment](https://wunderui.com/components/segment) for switching between views, with one always selected

## Keyboard

The group is one tab stop: Arrow keys move inside it and Tab moves out. Enter does nothing; only Space and Arrow keys choose.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the group, to the chosen option or, with none chosen, to the first one, and out of it again. Other options are not tab stops. |
| `ArrowDown` or `ArrowRight` | Moves focus to the next option and chooses it. From the last option it wraps to the first. |
| `ArrowUp` or `ArrowLeft` | Moves focus to the previous option and chooses it. From the first option it wraps to the last. |
| `Space` | Chooses the focused option, for example after Tab put focus on a group with nothing chosen. |

## Behavior

What the group does itself, and what it leaves to the page.

- **One choice:** The group holds a single value. Choosing an option replaces the old one, and only you can clear the choice again, not people.
- **Controlled or not:** Pass a value and a change handler to own the choice, or a default value to let the group keep it. Each option is matched by its own value.
- **Arrow keys choose:** Moving focus with an arrow key also chooses the option, like a native radio group, while Tab alone only moves focus. Home and End do nothing, and a disabled option is skipped.
- **Names:** The group needs a name from an aria-label or aria-labelledby. Each radio is named by its label: a Label tied by htmlFor and id, the title of a Selector Item, or an aria-label.
- **Hit area:** The area that takes a click reaches 12 px to the sides and 8 px above and below the 16 px circle.
- **Invalid:** Marking the group invalid turns every radio red together, also the chosen one, and announces the error once. Write the message under the group and point to it with aria-describedby.
- **Disabled:** Disabling the group dims every option to 40 %, and disabling one item dims that option only. A label is not dimmed for you, so add the opacity class to it.
- **Tint tone:** The tint tone is for a radio on a surface that turns indigo when the option is chosen, such as a selected option card. The filled circle then takes the tint colours of that hue.
- **In a form:** With a name on the group the chosen value is sent with the form. Required asks for a choice before the form is sent.
- **Motion:** Fill and border change with a quick colour transition. The dot appears with the fill and has no motion of its own.
- **Reduced motion:** With reduced motion transitions are limited to colour and opacity. Nothing in the group moves, so nothing else changes.

## Anatomy

- `RadioGroup`: The group: a radio group that holds the chosen value and lays the options out in a grid with an 8 px gap. Name it with an aria-label, and mark the whole group invalid if needed.
- `RadioGroupItem`: One round option, 16 px across, with its own value. Its hit area reaches 12 px to the sides and 8 px above and below the circle, so a near miss still selects it.
- `Dot`: The 6 px dot shown while the option is chosen. RadioGroupItem renders it; you do not pass it.
- `Label`: The text that names the option, a Label whose htmlFor matches the radio's id, or the title of a Selector Item. A click on it chooses the option.
- `Description`: A line of detail under the label, in secondary text, such as when an order arrives. It is not part of the label, so it does not widen the name.

## Best practices

### When to use

- Use a Radio Group when people choose exactly one option from a short list they should see at once. For a long list use a menu, and for options shown as buttons use a Radio Button Group.

### Do

- Name the group with a visible label and aria-labelledby, or with an aria-label. A screen reader announces the name when focus enters the group.
- Give every option a visible label and join it with htmlFor and id, so a click on the text also chooses it.
- Choose a sensible default when one exists. Once an option is chosen it cannot be cleared, so an empty start only helps when the choice is required.
- Put the error on the group: mark it invalid and write one message under it. Do not repeat the message on every row.
- Use Selector Item with a RadioGroupItem as its control when each option needs a title, a description and a price, such as plans.

### Don't

- Don't use two radios for on and off. A single setting that is on or off is a Switch or a Checkbox.
- Don't validate before the first try. A red group on load reads as a mistake that was not made yet.
- Don't split one choice into several groups, or put an unrelated control between the options. People expect the arrow keys to stay inside one group.

## API reference

### RadioGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the group's own `grid w-full gap-2`. Use it for the layout: `flex flex-wrap gap-x-6` makes a row. |
| defaultValue | Value |  | The option that is chosen at the start, when the group keeps its own value. Leave it out to start with nothing chosen. |
| disabled | boolean | false | Every option ignores clicks and keys and is dimmed to 40 %. Dim the labels yourself. |
| form | string |  | The id of the form that owns the hidden inputs, for a group that is rendered outside the form. |
| inputRef | React.Ref<HTMLInputElement> |  | A ref to the hidden input of the group. |
| invalid | boolean |  | Marks the whole group invalid: `aria-invalid` goes on the group and every radio turns red together. Write the message under the group yourself. |
| name | string |  | The name of the field when a form is sent. The chosen `value` is submitted under it. |
| onValueChange | (value, eventDetails) => void |  | Called when a different option is chosen, with its `value`. |
| readOnly | boolean | false | The choice cannot be changed. It is announced as read-only. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the group with another tag or component. Accepts an element or a function that returns one. |
| required | boolean | false | A choice is needed before a form that holds the group can be sent. It does not draw anything by itself: show the error yourself with `invalid`. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the group, an object or a function of the state. |
| value | Value |  | The chosen option, matched against the `value` of each item. Pass it with `onValueChange` to control the group; use `defaultValue` to let the group keep it. |

Also accepts React.HTMLAttributes attributes.

### RadioGroupItem

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | Value |  | The value of this option. It is unique in the group and is what `value` and `onValueChange` of the group carry. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the radio's own. Use it for spacing such as `mt-0.5`, not to recolour the radio. |
| disabled | boolean |  | This option cannot be chosen, is dimmed to 40 % and is skipped by the arrow keys. The group's other options stay as they are. |
| inputRef | React.Ref<HTMLInputElement> |  | A ref to the hidden input of this option. |
| nativeButton | boolean | false | Set it to `true` when `render` swaps the element for a native `<button>`. |
| readOnly | boolean |  | This option cannot be chosen by people but keeps its state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the radio with another tag or component. Accepts an element or a function that returns one. |
| required | boolean |  | Whether a choice is needed in the group before a form is sent. Set it on the group instead. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the radio, an object or a function of the state. |
| tone | "default" \| "tint" | "default" | `default` is the brand radio on a plain surface. `tint` is for a radio on a surface that turns indigo when chosen, such as a selected option card: the mark takes the tint colours of that hue. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Layout: vertical and horizontal

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <RadioGroup defaultValue="standard" aria-label="Delivery method" className="gap-3">
      <div className="flex items-start gap-2">
        <RadioGroupItem id="standard" value="standard" className="mt-0.5" />
        <Label htmlFor="standard" className="leading-5">
          Standard delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="express" value="express" className="mt-0.5" />
        <Label htmlFor="express" className="leading-5">
          Express delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="pickup" value="pickup" className="mt-0.5" />
        <Label htmlFor="pickup" className="leading-5">
          Store pickup
        </Label>
      </div>
    </RadioGroup>
  )
}
```

### Label and description: text, hint and group label

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <RadioGroup defaultValue="standard" aria-label="Delivery method" className="gap-3">
      <div className="flex items-start gap-2">
        <RadioGroupItem id="standard" value="standard" className="mt-0.5" />
        <Label htmlFor="standard" className="leading-5">
          Standard delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="express" value="express" className="mt-0.5" />
        <Label htmlFor="express" className="leading-5">
          Express delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="pickup" value="pickup" className="mt-0.5" />
        <Label htmlFor="pickup" className="leading-5">
          Store pickup
        </Label>
      </div>
    </RadioGroup>
  )
}
```

### States: default, disabled group and disabled option

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <RadioGroup aria-label="Delivery method" className="gap-3">
      <div className="flex items-start gap-2">
        <RadioGroupItem id="standard" value="standard" className="mt-0.5" />
        <Label htmlFor="standard" className="leading-5">
          Standard delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="express" value="express" className="mt-0.5" />
        <Label htmlFor="express" className="leading-5">
          Express delivery
        </Label>
      </div>
      <div className="flex items-start gap-2">
        <RadioGroupItem id="pickup" value="pickup" className="mt-0.5" />
        <Label htmlFor="pickup" className="leading-5">
          Store pickup
        </Label>
      </div>
    </RadioGroup>
  )
}
```

### Error and invalid: the group, not the row

```tsx
import { useState } from "react"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"

export function Example() {
  const [value, setValue] = useState("")
  const invalid = value === ""

  return (
    <div className="flex flex-col gap-2">
      <RadioGroup
        value={value}
        onValueChange={setValue}
        invalid={invalid}
        aria-label="Delivery method"
        aria-describedby={invalid ? "delivery-error" : undefined}
        className="gap-3"
      >
        <div className="flex items-start gap-2">
          <RadioGroupItem id="standard" value="standard" className="mt-0.5" />
          <Label htmlFor="standard" className="leading-5">
            Standard delivery
          </Label>
        </div>
        <div className="flex items-start gap-2">
          <RadioGroupItem id="express" value="express" className="mt-0.5" />
          <Label htmlFor="express" className="leading-5">
            Express delivery
          </Label>
        </div>
        <div className="flex items-start gap-2">
          <RadioGroupItem id="pickup" value="pickup" className="mt-0.5" />
          <Label htmlFor="pickup" className="leading-5">
            Store pickup
          </Label>
        </div>
      </RadioGroup>
      {invalid && (
        <p id="delivery-error" className="text-sm text-text-error">
          Choose a delivery method.
        </p>
      )}
    </div>
  )
}
```

## In context

### Delivery: a radio group with a group error

Nothing is chosen yet, so the error belongs to the group: Choose a delivery method. The radios are marked invalid, and the rows do not repeat the message.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

const OPTIONS = [
  { value: "standard", label: "Standard delivery", description: "Arrives in 3–5 business days" },
  { value: "express", label: "Express delivery", description: "Arrives tomorrow" },
  { value: "pickup", label: "Store pickup", description: "Ready in 2 hours" },
]

export function Example() {
  const [value, setValue] = useState("")
  const [tried, setTried] = useState(false)
  const [done, setDone] = useState(false)
  const invalid = tried && value === ""
  const chosen = OPTIONS.find((option) => option.value === value)

  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-3">
        <p id="delivery-label" className="text-sm font-medium text-foreground">
          Delivery method
        </p>
        <RadioGroup
          value={value}
          onValueChange={(next) => {
            setValue(next)
            setDone(false)
          }}
          invalid={invalid}
          aria-labelledby="delivery-label"
          aria-describedby={invalid ? "delivery-error" : undefined}
          className="gap-3"
        >
          {OPTIONS.map((option) => (
            <div key={option.value} className="flex items-start gap-2">
              <RadioGroupItem id={option.value} value={option.value} className="mt-0.5" />
              <div className="flex flex-col gap-1">
                <Label htmlFor={option.value} className="leading-5">
                  {option.label}
                </Label>
                <p className="text-sm text-text-secondary">{option.description}</p>
              </div>
            </div>
          ))}
        </RadioGroup>
        {/* The error belongs to the group: the radios are marked invalid, the rows are not repeated with the message. */}
        {invalid && (
          <p id="delivery-error" className="text-sm text-text-error">
            Choose a delivery method.
          </p>
        )}
      </div>
      <Button
        variant="gradient"
        onClick={() => {
          setTried(true)
          setDone(value !== "")
        }}
      >
        Continue
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {done && chosen ? `${chosen.label} confirmed.` : ""}
      </p>
    </div>
  )
}
```

### Plan: a radio list in a card

One Selector Item per option. The chosen row takes the indigo border and the filled dot, so the choice never relies on colour alone.

```tsx
import { useState } from "react"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem, SelectorItemGroup } from "@/components/ui/selector-item"

const PLANS = [
  { value: "starter", title: "Starter", description: "1 project, community support", price: "$0" },
  { value: "pro", title: "Pro", description: "Unlimited projects, priority support", price: "$12" },
  { value: "team", title: "Team", description: "Shared libraries, roles and an audit log", price: "$49" },
]

export function Example() {
  const [value, setValue] = useState("pro")
  const chosen = PLANS.find((plan) => plan.value === value) ?? PLANS[0]

  return (
    <div className="flex flex-col gap-3">
      <p id="plan-label" className="text-sm font-medium text-foreground">
        Plan
      </p>
      <RadioGroup value={value} onValueChange={setValue} aria-labelledby="plan-label">
        <SelectorItemGroup className="min-w-0">
          {PLANS.map((plan) => (
            <SelectorItem
              key={plan.value}
              controlPosition="leading"
              title={plan.title}
              description={plan.description}
              metadata={`${plan.price} / month`}
              control={<RadioGroupItem value={plan.value} />}
            />
          ))}
        </SelectorItemGroup>
      </RadioGroup>
      <p aria-live="polite" className="text-sm text-text-secondary">
        {chosen.title} plan, {chosen.price} per month.
      </p>
    </div>
  )
}
```

### Sort order: a compact list that changes the view

A radio group in a small panel. Choosing an option applies at once, so the list under it re-sorts without a button.

```tsx
import { useState } from "react"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

const SORTS = [
  { value: "newest", label: "Newest first" },
  { value: "oldest", label: "Oldest first" },
  { value: "name", label: "Name A–Z" },
]

const FILES = [
  { name: "Q3 report.pdf", day: 3, edited: "Nov 3" },
  { name: "Roadmap.docx", day: 5, edited: "Nov 5" },
  { name: "Brand assets.zip", day: 8, edited: "Nov 8" },
]

export function Example() {
  const [sort, setSort] = useState("newest")
  const files = [...FILES].sort((a, b) =>
    sort === "name" ? a.name.localeCompare(b.name) : sort === "oldest" ? a.day - b.day : b.day - a.day
  )

  return (
    <div className="flex flex-col gap-3">
      <p id="sort-label" className="text-sm font-medium text-foreground">
        Sort by
      </p>
      <RadioGroup
        value={sort}
        onValueChange={setSort}
        aria-labelledby="sort-label"
        className="gap-0 rounded-lg border border-border bg-popover p-1"
      >
        {SORTS.map((option) => (
          <label
            key={option.value}
            className="flex h-9 cursor-pointer items-center gap-2 rounded-md px-2 text-sm hover:bg-bg-page active:bg-bg-subtle"
          >
            <RadioGroupItem value={option.value} aria-label={option.label} />
            {option.label}
          </label>
        ))}
      </RadioGroup>
      <ul className="divide-y divide-border rounded-xl border border-border bg-card">
        {files.map((file) => (
          <li key={file.name} className="flex items-center justify-between px-4 py-2.5 text-sm">
            <span className="font-medium">{file.name}</span>
            <span className="text-text-secondary">{file.edited}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

## For AI agents

`get_component("radio-group")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
