# Radio Button Group

A single-select group of toggle-styled buttons.

- Category: Forms
- Page: https://wunderui.com/components/radio-button-group
- Tier: Free

## Install

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

## Import

```tsx
import { RadioButtonGroup } from "@/components/ui/toggle-button-group"
```

## Minimal usage

Then use it:

```tsx
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Digest() {
  return (
    <RadioButtonGroup defaultValue={["weekly"]} aria-label="Digest frequency">
      <ToggleButton value="daily">Daily</ToggleButton>
      <ToggleButton value="weekly">Weekly</ToggleButton>
      <ToggleButton value="monthly">Monthly</ToggleButton>
    </RadioButtonGroup>
  )
}
```

Expected result: You should see three pill buttons, Weekly chosen with a filled circle and the others empty. A click or Space chooses a button, and Arrow keys move focus and choose.

## Usage

```tsx
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <RadioButtonGroup defaultValue={["monthly"]} aria-label="Digest frequency">
      <ToggleButton value="daily">Daily</ToggleButton>
      <ToggleButton value="weekly">Weekly</ToggleButton>
      <ToggleButton value="monthly">Monthly</ToggleButton>
    </RadioButtonGroup>
  )
}
```

## When to use

### Use Radio Button Group for

- One choice from a few short options, such as a billing period or a time range
- A setting where each option is a word or an icon, such as text alignment
- A choice that should stay visible and one click away instead of hiding in a menu

### Use something else

- [Checkbox Button Group](https://wunderui.com/components/checkbox-button-group) for several options that can be combined
- [Radio Group](https://wunderui.com/components/radio-group) for one choice from a list of options with descriptions
- [Segment](https://wunderui.com/components/segment) for switching between views, with one always selected
- [Selector Item](https://wunderui.com/components/selector-item) for a whole row with a title, a description and a radio

## Keyboard

The group works like native radios and is one tab stop: Tab moves focus to the chosen button (or the first while nothing is chosen), and Arrow keys move focus and choose in one step.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the group, to the chosen button, or to the first enabled button while nothing is chosen, and out of it again. The other buttons are not tab stops. |
| `ArrowRight` or `ArrowDown` | Moves focus to the next enabled button and chooses it. From the last button it wraps to the first. With `orientation="horizontal"` only ArrowRight does this, with `orientation="vertical"` only ArrowDown. |
| `ArrowLeft` or `ArrowUp` | Moves focus to the previous enabled button and chooses it, wrapping from the first to the last. With `orientation="horizontal"` only ArrowLeft does this, with `orientation="vertical"` only ArrowUp. |
| `Home` or `End` | Moves focus to the first or the last enabled button and chooses it. |
| `Space` or `Enter` | Chooses the focused button. On the button that is already chosen it does nothing: the choice stays. |

## Behavior

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

- **One choice, as an array:** The group holds at most one value, kept in an array like every toggle group: one entry, or empty while nothing is chosen. Choosing another button replaces the old one.
- **A choice stays:** Pressing the chosen button again keeps it chosen, like a native radio, and the change handler is not called. Only an empty starting value shows nothing chosen, and the first press ends that.
- **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 button is matched by its own value.
- **Keyboard:** One tab stop: the chosen button, or the first while nothing is chosen. Arrow keys, Home and End move focus and choose in one step, wrap at the ends and skip disabled buttons.
- **Radios made of buttons:** The group is a radio group and each option a radio with a checked state, so a screen reader says radio 2 of 3, chosen. It sends no value with a form by itself, so add a hidden input when it must.
- **Names:** The group needs a name from an aria-label or aria-labelledby. A button is named by its text, an icon-only button needs its own aria-label, and the mark is hidden from assistive technology.
- **Wrapping:** The row wraps by itself when the container is narrow, with an 8 px gap in both directions. Set the vertical orientation together with column classes for a column.
- **Invalid:** Marking the group invalid turns every unchosen button red together; chosen and disabled buttons keep their look. Write the message under the group and point to it with aria-describedby.
- **Disabled:** Disabling the group dims every button to 40 % and skips it with Tab and the arrow keys. Disabling one button dims that button only, and the arrow keys skip it.
- **Motion:** Border, fill and the dot change with a quick colour transition. Nothing moves, so the group has no layout animation.
- **Reduced motion:** With reduced motion the colour and opacity changes still run, but they only fade. Nothing in the group moves, so nothing else changes.

## Anatomy

- `RadioButtonGroup`: A wrapping row of buttons with an 8 px gap, where one is chosen once the person has chosen. It is a radio group: name it with an aria-label, and mark the whole group invalid if needed.
- `ToggleButton`: One button with its own value. In this group it is a radio, and a chosen one takes the indigo tint; icon-only buttons need an aria-label.
- `Mark`: The 16 px radio circle in front of the label, with a 6 px dot while the button is chosen. It is drawn for buttons with a text label and left out for icon-only ones; you can hide it.
- `Icon`: An optional Lucide icon before the label, 16 px at a 1.5 stroke. It takes the text colour of the button, so it turns indigo with the label.

## Best practices

### When to use

- Use it for one choice from a few short options that should be one click away, such as a billing period. For options with a description use Radio Group; for combining options use CheckboxButtonGroup.

### Do

- Keep the value as an array and read the choice from its first entry. It has one entry once a button is chosen and never becomes empty by a press, so no guard for an empty choice is needed.
- 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 icon-only button an aria-label such as Align left. A screen reader announces the label and whether the radio is chosen; the icon alone has no name.
- Choose a sensible default when one exists, and show what the choice changes right next to the group.
- Use CheckboxButtonGroup when people may choose several options or none. The two look alike but behave differently: this one is a radio group, the other a set of toggles.

### Don't

- Don't use two buttons for on and off. A single setting that is on or off is a Switch or a Toggle.
- Don't use it for more than about five options or for options that need a sentence of explanation. Use a Radio Group or a Select instead.
- Don't use it to switch between views or pages. People expect a Segment or Tabs for that.

## API reference

### RadioButtonGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes, merged with the group's own `flex flex-wrap gap-2`. Use it for the layout: `flex-col items-stretch` makes a column. |
| defaultValue | readonly Value[] |  | The button that is chosen at the start, as an array with its value, when the group keeps its own state. Leave it out to start with nothing chosen. |
| disabled | boolean | false | Every button ignores clicks and keys and is dimmed to 40 %. Disable a single option on its ToggleButton instead. |
| loopFocus | boolean | true | Whether the arrow keys wrap from the last button to the first and back. Set it to `false` to stop at the ends. |
| onValueChange | ((groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void) |  | Called when the choice changes, with the new array of one value. It is not called when the chosen button is pressed again, and it never receives an empty array. |
| orientation | "horizontal" \| "vertical" \| "both" | "both" | Which arrow keys move the choice. `both` (default) works like native radios: Right and Down go to the next button, Left and Up to the previous one. `horizontal` uses Left and Right only, `vertical` Up and Down only. It does not change the layout: add `flex-col` classes for a column. |
| 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. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline style for the group, an object or a function of the state. |
| value | readonly Value[] |  | The chosen button as an array with its value, or an empty array while nothing is chosen. Pass it with `onValueChange` to control the group; use `defaultValue` to let the group keep it. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Content: label, icon only and icon with label

```tsx
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <RadioButtonGroup defaultValue={["weekly"]} aria-label="Digest frequency">
      <ToggleButton value="daily">Daily</ToggleButton>
      <ToggleButton value="weekly">Weekly</ToggleButton>
      <ToggleButton value="monthly">Monthly</ToggleButton>
    </RadioButtonGroup>
  )
}
```

### Layout: row, wrapping and column

```tsx
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <RadioButtonGroup defaultValue={["weekly"]} aria-label="Digest frequency">
      <ToggleButton value="daily">Daily</ToggleButton>
      <ToggleButton value="weekly">Weekly</ToggleButton>
      <ToggleButton value="monthly">Monthly</ToggleButton>
    </RadioButtonGroup>
  )
}
```

### Selection: arrow keys choose, pressing again keeps the choice

```tsx
import { useState } from "react"
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

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

  return (
    <div className="flex flex-col gap-3">
      <RadioButtonGroup
        value={value}
        onValueChange={setValue}
        aria-label="Digest frequency"
      >
        <ToggleButton value="daily">Daily</ToggleButton>
        <ToggleButton value="weekly">Weekly</ToggleButton>
        <ToggleButton value="monthly">Monthly</ToggleButton>
      </RadioButtonGroup>
      <p aria-live="polite" className="text-sm text-text-secondary">
        Chosen: {value[0]}
      </p>
    </div>
  )
}
```

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

```tsx
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  return (
    <RadioButtonGroup aria-label="Digest frequency">
      <ToggleButton value="daily">Daily</ToggleButton>
      <ToggleButton value="weekly">Weekly</ToggleButton>
      <ToggleButton value="monthly">Monthly</ToggleButton>
    </RadioButtonGroup>
  )
}
```

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

```tsx
import { useState } from "react"
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

export function Example() {
  const [value, setValue] = useState<string[]>([])
  const invalid = value.length === 0

  return (
    <div className="flex flex-col gap-2">
      <RadioButtonGroup
        value={value}
        onValueChange={setValue}
        aria-label="Digest frequency"
        aria-invalid={invalid}
        aria-describedby={invalid ? "digest-error" : undefined}
      >
        <ToggleButton value="daily">Daily</ToggleButton>
        <ToggleButton value="weekly">Weekly</ToggleButton>
        <ToggleButton value="monthly">Monthly</ToggleButton>
      </RadioButtonGroup>
      {invalid && (
        <p id="digest-error" className="text-sm text-text-error">
          Choose how often to send the digest.
        </p>
      )}
    </div>
  )
}
```

## In context

### Billing period: a plan card that follows the choice

Two options, one always chosen. The price, unit and savings note change with the choice, and a live region announces the note.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

const PRICES = {
  monthly: { amount: "$12", unit: "per month", note: "Billed every month." },
  yearly: { amount: "$120", unit: "per year", note: "Saves $24 compared with monthly billing." },
}

export function Example() {
  const [period, setPeriod] = useState<"monthly" | "yearly">("monthly")
  const price = PRICES[period]

  return (
    <div className="flex flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <RadioButtonGroup
        value={[period]}
        onValueChange={([next]) => setPeriod(next as "monthly" | "yearly")}
        aria-label="Billing period"
      >
        <ToggleButton value="monthly">Monthly</ToggleButton>
        <ToggleButton value="yearly">Yearly</ToggleButton>
      </RadioButtonGroup>
      <div className="flex flex-col gap-1">
        <p className="text-sm font-medium text-foreground">Pro</p>
        <p className="text-2xl font-semibold text-foreground">
          {price.amount} <span className="text-sm font-normal text-text-secondary">{price.unit}</span>
        </p>
        <p aria-live="polite" className="text-sm text-text-secondary">
          {price.note}
        </p>
      </div>
      <Button variant="gradient">Choose Pro</Button>
    </div>
  )
}
```

### Text alignment: icon-only buttons that apply at once

Three icons, one chosen. Each icon has an aria-label, and the text under the group follows every press without a button.

```tsx
import { useState } from "react"
import { AlignCenter, AlignLeft, AlignRight } from "lucide-react"
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

const ALIGN_CLASS = { left: "text-left", center: "text-center", right: "text-right" }

export function Example() {
  const [align, setAlign] = useState<"left" | "center" | "right">("left")

  return (
    <div className="flex flex-col gap-3">
      <RadioButtonGroup
        value={[align]}
        onValueChange={([next]) => setAlign(next as "left" | "center" | "right")}
        aria-label="Text alignment"
      >
        <ToggleButton value="left" aria-label="Align left">
          <AlignLeft className="size-4" />
        </ToggleButton>
        <ToggleButton value="center" aria-label="Align centre">
          <AlignCenter className="size-4" />
        </ToggleButton>
        <ToggleButton value="right" aria-label="Align right">
          <AlignRight className="size-4" />
        </ToggleButton>
      </RadioButtonGroup>
      <p className={`rounded-xl border border-border bg-card p-4 text-sm text-foreground ${ALIGN_CLASS[align]}`}>
        Version 0.4 adds a sliding Segment pill and concentric radii.
      </p>
    </div>
  )
}
```

### Time range: figures that follow the choice

Three ranges with a radio circle in front of each label. Revenue and orders under the group are announced when they change.

```tsx
import { useState } from "react"
import { RadioButtonGroup } from "@/components/ui/radio-button-group"
import { ToggleButton } from "@/components/ui/toggle"

const RANGES = [
  { value: "7d", label: "7 days", revenue: "$4,280", orders: "142" },
  { value: "30d", label: "30 days", revenue: "$18,640", orders: "611" },
  { value: "90d", label: "90 days", revenue: "$52,310", orders: "1,728" },
]

export function Example() {
  const [range, setRange] = useState("30d")
  const current = RANGES.find((item) => item.value === range) ?? RANGES[1]

  return (
    <div className="flex flex-col gap-4">
      <RadioButtonGroup
        value={[range]}
        onValueChange={([next]) => setRange(next)}
        aria-label="Time range"
      >
        {RANGES.map((item) => (
          <ToggleButton key={item.value} value={item.value}>
            {item.label}
          </ToggleButton>
        ))}
      </RadioButtonGroup>
      <dl aria-live="polite" className="grid grid-cols-2 gap-4 rounded-xl border border-border bg-card p-4">
        <div>
          <dt className="text-sm text-text-secondary">Revenue</dt>
          <dd className="text-xl font-semibold text-foreground">{current.revenue}</dd>
        </div>
        <div>
          <dt className="text-sm text-text-secondary">Orders</dt>
          <dd className="text-xl font-semibold text-foreground">{current.orders}</dd>
        </div>
      </dl>
    </div>
  )
}
```

## For AI agents

`get_component("radio-button-group")`

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