Skip to main content

Radio group

Last updated:
1/25/2024

A radio button allows the user to select one option from a small list. Radio buttons are used for mutually exclusive options.

View in Storybook
Legend

Modifiers

With help text

Add help text to further explain the radio group’s function or meaning. If an individual radio button needs more explanation, help text will appear under its radio button within the group.

Legend

This is an example help text. It can wrap to two lines, but try not to go longer than three.

This is an example help text. It can wrap to two lines, but try not to go longer than three.

With error message

If a radio button selection within the group throws an error, an error message will appear.

Select a radio button in the preview to clear the error message.

Legend

This is an example of an error message.

This is an example help text. It can wrap to two lines, but try not to go longer than three.

With help text and error message

If a radio group requires help text and throws an error, an error message will appear above the help text.

Select a different radio button in the preview to clear the error message.

Legend

This is an example of an error message.

This is an example help text. It can wrap to two lines, but try not to go longer than three.

This is an example help text. It can wrap to two lines, but try not to go longer than three.

Styles

Default

Use the default style wherever the user needs to select one option from a small list. Default is the most used radio group style.

Legend

Button group

The button group style is only approved to be used for product attribute selections. Approval is required to use this style.

This style has a pseudo-state called “unavailable.” If the user selects an option that is not compatible with other options in the group, those options will be marked as unavailable. Users are still able to select options marked unavailable.

Legend
Legend

This is an example of an error message.

This is an example help text. It can wrap to two lines, but try not to go longer than three.

States

Disabled

A radio group can be disabled if the experience requires it. If you need to disable a group, make sure the reason is obvious. If the reason is not obvious, you can keep the group enabled and add an error message to explain. The user’s selection within the radio group will not be submitted with the form’s data.

Disabled radio group
Disabled button style radio group

Usage

Radio buttons are used for groups of two or more options that are exclusive of each other. The user can only select one option. When a user selects an option, the previously selected option is unselected.

The first option in a radio group is usually selected by default. If the first option is disabled, the second option can be selected. There are some edge cases, such as yes / no questions, where no options should be selected by default.

An unselected radio button represents a negative selection and a selected radio button represents a positive selection. If there is a large number of options and not enough space on the page, consider using a single-select component.

Do:

  • Order radio groups vertically, unless using the button group style
  • Select the first radio button option by default
  • Ensure that the range of radio button options are distinct and comprehensive
  • Use radio groups for selections or settings

Don't:

  • Add too many options to a radio group — a good rule of thumb is if you have seven or more options, consider using a select component instead
  • Use radio buttons when more than one option can be selected
  • Use radio groups for actions
  • Use the button group style for anything other than selecting product details

Content guidelines

Do:

  • Keep labels short, clear, and descriptive
  • Use positive and active language
  • Start labels with a capital letter
  • Order options in a logical way, such as alphabetically, or by most or least selected
  • Organize labels by way of parallel syntax wherever possible

Don't:

  • Include punctuation after labels, unless the label is more than one sentence long

User research

Key takeaways

Clear, comprehensive, and distinct options

Because users must select an option from a radio group, ensure that the group’s options address all of a user’s possible choices. Add catchall options, such as “Other” or “None,” for users when no other options apply.

Default selection for radio button lists

The first option of radio groups is usually selected by default. Radio groups generally have at least one option selected. The default selection can be useful to suggest an option, but, unless strong research is a determining factor, select the option that is the least harmful or presumptuous. Add a “None” option if the user must be able to select a null option.

The edge case for this is binary questions such as yes/no options.

No sources

Accessibility

This component passes AAA WCAG standards. However, changes made by the content owner or implementer could impact accessibility compliance. Be sure to follow code standards, usage guidelines, and content guidelines to ensure that this component is fully accessible.

For more information, see WAI-ARIA Authoring Practices for radio buttons and Deque’s screen reader keyboard shortcuts and gestures documentation.