Skip to content
WunderUI

Radio Button Group

Free

Let people choose one option from a few short ones, shown as a row of toggle buttons.

npx wunderui-cli add radio-button-group

Playground

Installation

bash
npx wunderui-cli add radio-button-group

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

Content

A button holds a word or two. A text label gets a radio circle in front so the choice never relies on colour alone, and an icon-only button has no circle and needs an aria-label.

Layout

The row wraps by itself when the container is narrow. For a stack, set the orientation to vertical so the arrow keys follow the layout.

Selection

The group works like native radios. Tab puts focus on the chosen button, the arrow keys move focus and choose in one step, and pressing the chosen button again keeps it chosen.

Chosen: weekly

States

Disable the whole group, or one option that is not available right now. Hover, pressed and focus are real states: move the pointer over a button, or press Tab.

Error and invalid

The error belongs to the group: every unchosen button turns red together and one message under the group says what to do. Choose another option to clear it.

Choose how often to send the digest.

Keyboard interactions

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.

TaborShiftTab
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.
ArrowRightorArrowDown
Moves focus to the next enabled button and chooses it. From the last button it wraps to the first. With only ArrowRight does this, with only ArrowDown.
ArrowLeftorArrowUp
Moves focus to the previous enabled button and chooses it, wrapping from the first to the last. With only ArrowLeft does this, with only ArrowUp.
HomeorEnd
Moves focus to the first or the last enabled button and chooses it.
SpaceorEnter
Chooses the focused button. On the button that is already chosen it does nothing: the choice stays.

Behavior and motion

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

The parts the component is made of. Each one renders a you can target from CSS.

  • data-slot="radio-button-group"

    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.

  • 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.

  • data-slot="toggle-button-mark"Optional

    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.

  • Optional

    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

  • 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.

  • 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.

  • Do

    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.

  • Do

    Choose a sensible default when one exists, and show what the choice changes right next to the group.

  • Do

    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

    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

    Don't use it to switch between views or pages. People expect a Segment or Tabs for that.

API reference

RadioButtonGroup renders a radio group element and takes the props below and every native attribute. The buttons inside are ToggleButton; their props are described on the Toggle page.

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.

PropTypeDefaultDescription
valuereadonly Value[]—The chosen button as an array with its value, or an empty array while nothing is chosen. Pass it with to control the group; use to let the group keep it.
defaultValuereadonly 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.
onValueChange(groupValue, eventDetails) => 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.
disabledbooleanfalseEvery button ignores clicks and keys and is dimmed to 40 %. Disable a single option on its ToggleButton instead.
orientation"horizontal" | "vertical" | "both""both"Which arrow keys move the choice. (default) works like native radios: Right and Down go to the next button, Left and Up to the previous one. uses Left and Right only, Up and Down only. It does not change the layout: add classes for a column.
loopFocusbooleantrueWhether the arrow keys wrap from the last button to the first and back. Set it to to stop at the ends.
renderReactElement | (props, state) => ReactElement—Replaces the element of the group with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the group's own . Use it for the layout: makes a column.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the group, an object or a function of the state.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("radio-button-group")
Installnpx wunderui-cli add radio-button-group

The full library index for assistants is at /llms.txt.