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.
Installation
npx shadcn@latest add @flyingsalmon/radio-groupUsage
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.
Disabled
Disabling the group dims every option. Disabling one item takes that option out while the rest stay live.
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.
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.
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
- DoAsk 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.
- DoSpell 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.
- DoPreselect 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’tPreselect 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’tOffer a single option on its own.One option offers no choice and cannot be unselected. A yes or no is a checkbox.
- Don’tLay 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
| Key | Description |
|---|---|
| Tab | Enters the group once, on the checked option or the first enabled one. A second Tab leaves the group. |
| ArrowDownArrowRight | Moves to the next enabled option and selects it, wrapping at the last. ArrowDown works in a vertical group and ArrowRight in a horizontal one. |
| ArrowUpArrowLeft | Moves to the previous enabled option and selects it, wrapping at the first. ArrowUp works in a vertical group and ArrowLeft in a horizontal one. |
| Space | Selects 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | – | The question the group answers, shown above the options. |
| error | string | – | Turns the group red and shows the message below it. |
| value | string | – | The selected option when the app controls it. |
| defaultValue | string | – | The starting option when the app does not control it. |
| onValueChange | (value: string) => void | – | Called with the value of the newly selected option. |
| orientation | RadioGroupOrientation | RadioGroupOrientation.Vertical | Vertical stacks the options; Horizontal lays them in a row. |
| name | string | – | Puts the chosen value into the surrounding form's FormData. |
| required | boolean | false | Marks the label and sets aria-required. It does not block submission. |
| disabled | boolean | false | Dims and disables every option. |
| className | string | – | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | Required | The value the group reports when this option is selected. |
| label | string | – | The text beside the circle. It is part of the click target. |
| disabled | boolean | false | Takes this option out while the rest stay live. |
| className | string | – | Styles the row that holds the circle and its label. |