Use RadioButtons when you have a few options that a user can choose from. Never use radio buttons if the user can select more than one option from a list.

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier for the input.

onChange
Required
AbstractEventHandler<SyntheticInputEvent<HTMLInputElement>, {| checked: boolean |}>
-

Callback triggered when the user interacts with the input.

value
Required
string
-

The value of the input.

checked
boolean
false

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

disabled
boolean
false

Indicates if the input is disabled. See the combinations 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"
"md"

sm: 16px, md: 24px

subtext
string
-

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

Usage guidelines

When to Use
  • Situations where users can only choose one out of multiple, related options.
When Not to Use
  • Any time users can choose more than one option. Use Checkboxes instead.
  • As a solitary option. RadioButtons should always appear in groups of 2 or more. Consider a Checkbox or Switch instead.

RadioButton Group

Here is an example of an accessible group of radio buttons. All radio buttons should be wrapped in a Fieldset.

Example: With Subtext

Here is an example of a group of radio buttons with subtext.

Example: With Images

Here is an example of a group of radio buttons with images. 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.

Example: ref

The innermost RadioButton element can be accessed via ref

Example: RadioButton and Popover

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

Combinations