Use RadioGroup.RadioButtons to present an option for selection to the user within a RadioGroup. They should not be used outside of RadioGroup or when the user can select more than one option from a list.
- In a list, form or table, to present users with multiple, related options where only one option can be selected.
- When selection doesn’t take immediate effect and requires form submission.
- Situations where users can select multiple options. Use Checkbox instead.
- When there is only one item to select or deselect. Use Checkbox instead.
- When a selection takes immediate effect, especially on mobile. Use Switch instead.
- When it is visually difficult to observe that RadioGroup turns something on or off. Use Switch instead.
Use RadioGroup to select only one option from a list of 2 or more items.
Use RadioGroup to select multiple items.
Keep labels and legends clear and brief to avoid too many lines of text that are hard to scan and slow the user down. If clarification is needed, use IconButtons with Tooltips or
Use lengthy text that truncates and doesn’t offer clear instructions for how to make a selection.
Use RadioGroup when you need a clear answer to a binary question that requires form submission.
Each RadioButton in a RadioGroup should have a label that can be read by screen readers, and that can be clicked or tapped to make it easier for users to select and deselect options. Therefore, make sure to supply the label prop. If that’s not possible, make sure your standalone Label has an
htmlFor prop that matches the
id of the RadioButton. Test that a RadioButton and label are properly connected by clicking or tapping on the label and confirming that it activates the RadioButton next to it.
Each RadioGroup should have a
legend that clearly delineates what is being chosen. If you cannot use the provided legend styling,
legendDisplay can be set to
hidden, and an alternative legend can be displayed. See the legend visibility variant for an example.
After focus has been set on the first RadioButton inside a RadioGroup, the arrow keys are used to cycle focus between the various options. Clicking or tapping the label of RadioButton should also focus that particular RadioButton. All RadioGroup.RadioButtons within a RadioGroup should share the same
name to ensure keyboard accessibility, but that
name needs to be unique from other RadioGroup buttons on the page.
Be sure to localize
legend. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.
RadioGroups can be shown in a column or row by specifying the
RadioButtons can be either
sm (16px) or
md (24px), which is the default.
Disabled RadioButtons cannot be accessed by the keyboard and therefore should not contain any necessary info to complete the choice presented.
helperText to provide extra context or information for each option.
When including images, you can use the
helperText property to clearly describe the information being presented by the image, or use the image's
alt text to provide more context.
With an error
errorMessage to show an error message below the radio options.
With custom labels
label on RadioGroup.RadioButton can be replaced with a custom Label, as demonstrated below. Ensure the
htmlFor property matches the
id on the RadioButton.
By default, the
legend is visible above the items in the RadioGroup. However, if the form items are labeled by content elsewhere on the page, or a more complex legend is needed, the
legendDisplay prop can be used to visually hide the
legend. In this case, it is still available to screen reader users, but will not appear visually on the screen.
In the example below, the "Primary company account goal" text is acting as a heading and a legend for the radio buttons, so instead of repeating another legend, we visually hide the RadioGroup
legend. When a user focuses on the first radio, a screen reader will announce "Sell more products, radio button, 1 of 3, Primary company account goal, group".
Adding a Popover
RadioButton with an anchor ref to a Popover component doesn't pass the correct positioning to the Popover. Instead set the anchor ref to the parent container.
- Be brief with RadioGroup button labels so they are easily scanned.
- Error messages should be simple, clear and direct without negative, overly clever and technical language.
- A good error message: “To continue you must select one item from this list.”
- Include lengthy text labels that make it hard for a user to scan a list of choices.
- Write error messages that are overly-technical, long, negative, and too clever.
- A not-so-great error message: “Hey there, nice try, but not selecting something is baaaad. Bad as in bad. Per error code i-five, you must select a choice from this boolean”.
Use for single-cell options that can be turned on or off. Examples include a list of settings that take effect immediately without having to confirm form submission.