Skip to content
WunderUI

Radio Group

Free

Let people choose exactly one option from a short list they can see at once.

npx wunderui-cli add radio-group

Playground

Installation

bash
npx wunderui-cli add radio-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 { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

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.

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 for

  • Checkbox for several choices from a list, or one on or off choice
  • Switch for a setting that takes effect at once
  • Radio Button Group for one choice shown as a row of buttons
  • Segment for switching between views, with one always selected

Layout

Stack the options when they have descriptions or are more than three. Use one row only for two or three short labels; it wraps on a narrow screen.

Label and description

A visible group label names the choice, and each radio has its own label. A click on the text selects the option, and a description sits under its label.

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 radio, or press Tab.

Error and invalid

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

Choose a delivery method.

Keyboard interactions

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

TaborShiftTab
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.
ArrowDownorArrowRight
Moves focus to the next option and chooses it. From the last option it wraps to the first.
ArrowUporArrowLeft
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 and motion

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

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

Arrives tomorrow

Ready in 2 hours

  • data-slot="radio-group"

    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.

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

    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.

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

    The 6 px dot shown while the option is chosen. RadioGroupItem renders it; you do not pass it.

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

  • Optional

    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

  • 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 option a visible label and join it with htmlFor and id, so a click on the text also chooses it.

  • Do

    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.

  • Do

    Put the error on the group: mark it invalid and write one message under it. Do not repeat the message on every row.

  • Do

    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

    Don't validate before the first try. A red group on load reads as a mistake that was not made yet.

  • Don’t

    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 renders a radio group element and takes the props below and every native attribute. RadioGroupItem wraps the Base UI radio.

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.

PropTypeDefaultDescription
valueValue—The chosen option, matched against the of each item. Pass it with to control the group; use to let the group keep it.
defaultValueValue—The option that is chosen at the start, when the group keeps its own value. Leave it out to start with nothing chosen.
onValueChange(value, eventDetails) => void—Called when a different option is chosen, with its .
invalidboolean—Marks the whole group invalid: goes on the group and every radio turns red together. Write the message under the group yourself.
disabledbooleanfalseEvery option ignores clicks and keys and is dimmed to 40 %. Dim the labels yourself.
readOnlybooleanfalseThe choice cannot be changed. It is announced as read-only.
requiredbooleanfalseA 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 .
namestring—The name of the field when a form is sent. The chosen is submitted under it.
formstring—The id of the form that owns the hidden inputs, for a group that is rendered outside the form.
inputRefRef<HTMLInputElement>—A ref to the hidden input of the group.
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 row.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the group, an object or a function of the state.

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.

PropTypeDefaultDescription
value requiredValue—The value of this option. It is unique in the group and is what and of the group carry.
disabledboolean—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.
readOnlyboolean—This option cannot be chosen by people but keeps its state.
requiredboolean—Whether a choice is needed in the group before a form is sent. Set it on the group instead.
tone"default" | "tint""default" is the brand radio on a plain surface. 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.
inputRefRef<HTMLInputElement>—A ref to the hidden input of this option.
nativeButtonbooleanfalseSet it to when swaps the element for a native .
renderReactElement | (props, state) => ReactElement—Replaces the element of the radio with another tag or component. Accepts an element or a function that returns one.
classNamestring | (state) => string | undefined—Extra classes, merged with the radio's own. Use it for spacing such as , not to recolour the radio.
styleCSSProperties | (state) => CSSProperties | undefined—Inline style for the radio, an object or a function of the state.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

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

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