Skip to content
flyingsalmon

Radio group

A radio group picks exactly one option from a small set that stays visible, and it owns its label and its error message.

Pace

Installation

npx shadcn@latest add @flyingsalmon/radio-group

Usage

import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group'

export function RadioGroupUsage() {
  return (
    <RadioGroup label="Room" defaultValue="double">
      <RadioGroupItem value="single" label="Single room" />
      <RadioGroupItem value="double" label="Double room" />
    </RadioGroup>
  )
}

Examples

Horizontal

Horizontal lays the options out in a row and the arrow keys follow. Keep it for short labels: a row of full sentences wraps unpredictably and loses the alignment that makes options scannable.

Seat

Disabled

Disabling the group dims every option. Disabling one item takes that option out while the rest stay live.

Boat tour
Room, locked after booking

Error

The group label, the item borders, and the focus ring turn red and the message appears below. The checked disc keeps its knocked-out dot; only its fill changes colour.

Room

Pick a room to continue

Controlled

value and onValueChange hand the selection to the app. name also puts the chosen value into the surrounding form's FormData, so a plain native submit works.

Cost split

Brian Nguyen chose: split evenly.

Guidelines

When to use

  • To pick exactly one option from two to five choices, where seeing every option helps the decision.
  • For an answer a form collects and submits later, such as a room type or a cost split.

When not to use

  • Use Toggle group when the traveller must be able to clear the choice, because a radio group cannot be emptied once it holds a value.
  • Use Select for more than five options, where the list outgrows the form.

Do and don’t

  • Do
    Ask the question once, as the label above the options, and let each option be only an answer: "Who pays for dinners?"The traveller reads the question once and then scans the answers. Repeating it in every option buries the difference between them.
  • Do
    Spell out the consequence when an option is a sentence: "Keep it booked: the rest of the day moves around it".The traveller chooses an outcome they can see, not a label they have to decode.
  • Do
    Preselect the option most travellers want when any answer is harmless.The default saves the click, and a traveller who wants something else sees every alternative beside it.
  • Don’t
    Preselect an answer the traveller must choose deliberately.A preselected answer gets accepted without being read. Leave the group empty, and a skipped group fails on submit with the message on the group itself.
  • Don’t
    Offer a single option on its own.One option offers no choice and cannot be unselected. A yes or no is a checkbox.
  • Don’t
    Lay options in a row unless each label is a word or two.Longer labels wrap unevenly across the row and the options stop lining up. A column of sentences reads top to bottom.

Accessibility

KeyDescription
TabEnters the group once, on the checked option or the first enabled one. A second Tab leaves the group.
ArrowDownArrowRightMoves to the next enabled option and selects it, wrapping at the last. ArrowDown works in a vertical group and ArrowRight in a horizontal one.
ArrowUpArrowLeftMoves to the previous enabled option and selects it, wrapping at the first. ArrowUp works in a vertical group and ArrowLeft in a horizontal one.
SpaceSelects the focused option.

The group exposes role="radiogroup" and is named by its label. Clicking an option’s label selects that option. An error sets aria-invalid on the group and links the message through aria-describedby, keeping any description you pass. The focus ring appears on keyboard focus only. required marks the label and sets aria-required on the group; the validation itself stays with your app.

API

RadioGroup

Also takes every <div> attribute. The fields page describes the label, error, and wrapper behaviour that every field shares.

PropTypeDefaultDescription
labelstring–The question the group answers, shown above the options.
errorstring–Turns the group red and shows the message below it.
valuestring–The selected option when the app controls it.
defaultValuestring–The starting option when the app does not control it.
onValueChange(value: string) => void–Called with the value of the newly selected option.
orientationRadioGroupOrientationRadioGroupOrientation.VerticalVertical stacks the options; Horizontal lays them in a row.
namestring–Puts the chosen value into the surrounding form's FormData.
requiredbooleanfalseMarks the label and sets aria-required. It does not block submission.
disabledbooleanfalseDims and disables every option.
classNamestring–Styles the wrapper that holds the label, options, and message, not the option list.

RadioGroupItem

Also takes every button attribute. There is no description line and no node label.

PropTypeDefaultDescription
valuestringRequiredThe value the group reports when this option is selected.
labelstring–The text beside the circle. It is part of the click target.
disabledbooleanfalseTakes this option out while the rest stay live.
classNamestring–Styles the row that holds the circle and its label.

  • Checkbox

    A yes or no, or any number of independent options.
  • Toggle group

    Chips for one choice the traveller can clear.
  • Select

    One choice from a list too long to show.
  • Fields

    The label, error, and wrapper behaviour every field shares.