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.
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.
subtext to provide extra context or information for each option.
When including images, you can use the
subtext 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
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.