Radio Group
A Radio Group allows users to choose one option from a set in which every option is visible.
When to Use
- for a choice of one from a few options, such as “Never”, “Every week”, and “Every day”
- when users need to read every option before they choose, as none is hidden in a popup
- as choice cards, for options that each need a description, such as a billing method
A choice card is a radio inside a bordered label. See Field for how to build one.
When Not to Use
- to choose any number of options (use a Checkbox for each)
- for one setting that is on or off (use a Switch)
- for a list that is too long to show in full (use a Select, which keeps its options in a popup)
- to switch between views of the same content (use a Segmented Control)
See Checkbox for a comparison of the Checkbox, the Switch, and the Radio Group.
Anatomy
| Element | Usage |
|---|---|
| Radio | Required |
| Label* | Optional |
| Dot | Checked state only |
| Group | Required |
* A radio with no visible label needs an aria-label.
RadioGroup stacks its options 12px apart. See Sizing for the rule.
States
If disabled is set on one RadioGroupItem, the other options stay interactive, and the arrow keys skip the disabled one. If disabled is set on RadioGroup, every radio is disabled, and the group is removed from the tab order. To mark a group as invalid, set invalid on its Field, or set aria-invalid on a RadioGroupItem that has no Field.
Behavior
By default, no option is checked. To check one, set defaultValue or value. When users click the checked radio, it stays checked, so a group that has a choice can’t return to none.
Accessibility
Base UI’s Radio Group makes the set one tab stop, and users move the choice with the arrow keys.
A Radio Group needs a name that says what is being chosen so that screen reader users hear the question and not only
the options, as WCAG 2.2 SC 4.1.2 Name, Role, Value requires. To provide one, set aria-label or aria-labelledby on RadioGroup,
or place the group in a FieldSet with a FieldLegend.
Add a Label to every radio. See Field for the legend, the description, and the error of a group.
Installation
npx shadcn@latest add @summit/radio-groupUsage
import { Label } from '@/components/ui/label';
import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group';
<RadioGroup aria-label="Payment reminders" defaultValue="weekly">
<div className="flex items-center gap-2">
<RadioGroupItem id="never" value="never" />
<Label htmlFor="never">Never</Label>
</div>
<div className="flex items-center gap-2">
<RadioGroupItem id="weekly" value="weekly" />
<Label htmlFor="weekly">Every week</Label>
</div>
</RadioGroup>;API Reference
RadioGroup and RadioGroupItem add no props. The props of RadioGroup are passed to Base UI’s Radio Group, and the props of RadioGroupItem are passed to the root of Base UI’s Radio. See the Base UI Radio Group documentation for value, onValueChange, name, readOnly, and required.