RadioGroups are used for selecting only 1 item from a list of 2 or more items. If you need multiple selection or have only one option, use Checkbox. If you need to provide a binary on/off choice that takes effect immediately, use Switch.

also known as Single Select, Option Buttons, Radio Inputs

Web:

iOS:

Android:

A11y:

Props

Component props
Name
Type
Default
children
Required
React.Node
-

A collection of RadioGroup.RadioButtons representing the available options, as well as any Labels or layout components (Box, Flex, etc.), if needed. Other components such as Checkboxes should not be included. Note that children can be grouped into organizational components if desired.

id
Required
string
-

A unique identifier for this RadioGroup.

legend
Required
string
-

The description of the radio group that tells users what is being asked of them.

direction
"column" | "row"
-

Determines the layout of the group. See the direction variant to learn more.

errorMessage
string
-

Adds an error message below the group of radio buttons. See the error variant to learn more.

legendDisplay
"visible" | "hidden"
-

Whether the legend should be visible or not. If hidden, the legend is still available for screen reader users, but does not appear visually. See the legend visibility variant to learn more.

Subcomponents

RadioGroup.RadioButton

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.

RadioGroup.RadioButton Props

RadioGroup.RadioButton subcomponent props
Name
Type
Default
id
Required
string
-

A unique identifier for the input.

onChange
Required
({| event: SyntheticInputEvent<HTMLInputElement>, checked: boolean |}) => void
-

Callback triggered when the user interacts with the input.

value
Required
string
-

The value of the input.

checked
boolean
-

Indicates if the input is checked. See the state example for more details.

disabled
boolean
-

Indicates if the input is disabled. See the state example for more details.

helperText
string
-

Optional description for the input, used to provide more detail about an option. See the helperText example for more details.

image
React.Node
-

An optional Image component can be supplied to add an image to each radio button. Spacing is already accounted for — simply specify the width and height. See the images example for more details.

label
string
-

The displayed label for the input.

name
string
-

The name given for all radio buttons in a single group.

ref
HTMLInputElement
-

Ref forwarded to the underlying input element. See ref example for more details.

size
"sm" | "md"
-

sm: 16px, md: 24px

Usage guidelines

When to use
  • 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.
When not to use
  • 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.

Best Practices

Do

Use RadioGroup to select only one option from a list of 2 or more items.

Don't

Use RadioGroup to select multiple items.

Do

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 helperText.

Don't

Use lengthy text that truncates and doesn’t offer clear instructions for how to make a selection.

Do

Use RadioGroup when you need a clear answer to a binary question that requires form submission.

Don't

Use a RadioGroup to turn a state on and off with immediate effect on mobile; use Switch instead.

Accessibility

Labels

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.

Legends

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.

Keyboard interaction

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.

Localization

Be sure to localize errorMessage, helperText, label, and legend. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.

Variants

Direction

RadioGroups can be shown in a column or row by specifying the direction property.

Size

RadioButtons can be either sm (16px) or md (24px), which is the default.

States

Disabled RadioButtons cannot be accessed by the keyboard and therefore should not contain any necessary info to complete the choice presented.

With helperText

Use helperText to provide extra context or information for each option.

With Image

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

Use errorMessage to show an error message below the radio options.

With custom labels

The label on RadioGroup.RadioButton can be replaced with a custom Label, as demonstrated below. Ensure the htmlFor property matches the id on the RadioButton.

Legend visibility

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.

Writing

Do
  • 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.”
Don't
  • 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”.

CheckBox
Use when presenting a user with a list of choices where multiple options can be selected.

Switch
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.

Fieldset
Fieldset is used under the hood of RadioGroup to ensure accessible groups of radio buttons.