Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Radio Button Group

Version 4.1.1GithubStorybook

Radio Button Group is a set of related, mutually exclusive options where only one can be selected at a time.

Component preview theme
const RadioButtonGroupExample = () => {
return (
<RadioButtonGroup attached name="foo" legend="Choose a day" helpText="The message will be sent on the day you choose">
<RadioButton value="m">Mon</RadioButton>
<RadioButton value="t" defaultChecked>Tues</RadioButton>
<RadioButton value="w">Wed</RadioButton>
<RadioButton value="th">Thu</RadioButton>
<RadioButton value="f">Fri</RadioButton>
</RadioButtonGroup>
)
}
render(<RadioButtonGroupExample />)

Guidelines

Guidelines page anchor

About Radio Button Group

About Radio Button Group page anchor

A Radio Button Group is a set of 2–6 mutually exclusive radio buttons. It is often used as a way to swap between different views of the same data (e.g., swapping between different chart types for a data set).

Radio Button Groups in forms

Radio Button Groups in forms page anchor

Be thoughtful when using Radio Button Groups in forms. It can be difficult for users to discern which option is “selected” with only 2 options, while having too many options can be overwhelming. We recommend no more than 6 options. Radio Button Groups used in forms should have a label.

Radio Button Groups vs Tabs

Radio Button Groups vs Tabs page anchor

Tabs are used to layer related pieces of information together and display one layer at a time. Use Tabs to alternate between views within the same context. Use Radio Button Groups to toggle between different functionality in a single view. Tabs replace the entire view based on the selected tab. Radio Buttons update the data within the view.

Button Group vs Radio Button Group

Button Group vs Radio Button Group page anchor

Radio Groups are form elements that allow customers to select only one option from a list of text at a time. Radio Groups are easily scannable and work well within a larger form because they visually compete less with primary page actions.

Radio Button Groups are functionally the same as Radio Groups since only one option can be selected at a time. However, the Radio Button Group contains buttons while Radio Groups contain Radios. This distinction makes Radio Button Groups more visually prominent, so they may be ideal for a more graphical element. They can also be great options when selecting between simple things, like days of the week, modes of contact (e.g., phone, sms, email), etc.

A Radio Button Group is the same as a Radio Group to assistive technology.

  • If the Radio Button only has an icon, the icon needs a label.
  • The Radio Button Group needs a legend, which labels what the set of Radio Buttons does.

Use the text variant with short labels, no more than 3 words per label.

Component preview theme
const RadioButtonGroupExample = () => {
return (
<RadioButtonGroup attached name="foo" legend="Choose a day" helpText="The message will be sent on the day you choose">
<RadioButton value="m">Mon</RadioButton>
<RadioButton value="t" defaultChecked>Tues</RadioButton>
<RadioButton value="w">Wed</RadioButton>
<RadioButton value="th">Thu</RadioButton>
<RadioButton value="f">Fri</RadioButton>
</RadioButtonGroup>
)
}
render(<RadioButtonGroupExample />)

Use the text and icon variant when icons are not easily recognizable (like product-specific icons) and a text label would help with understanding. If an icon has a chance of not being completely understood at a glance, pair it with a text label.

Component preview theme
const RadioButtonGroupExample = () => {
return (
<RadioButtonGroup attached name="foo" legend="Choose a product" helpText="The product you choose will be used for your new role">
<RadioButton value="phone"><CallIcon decorative={false} title="phone icon"/>Phone</RadioButton>
<RadioButton value="text"><SMSCapableIcon decorative={false} title="text icon"/>Text</RadioButton>
<RadioButton value="email"><EmailIcon decorative={false} title="email icon"/>Email</RadioButton>
</RadioButtonGroup>
)
}
render(<RadioButtonGroupExample />)

Display an error message below the radio button group. For additional guidance on how to compose error messages, refer to the error state pattern.

Component preview theme
const RadioButtonGroupExample = () => {
return (
<RadioButtonGroup
attached
name="foo"
legend="What is your preferred programming language?"
errorText="Select a programming language."
helpText="Select the language with which you are most familiar."
>
<RadioButton value="js" hasError>JavaScript</RadioButton>
<RadioButton value="py" hasError>Python</RadioButton>
<RadioButton value="c" hasError>C++</RadioButton>
</RadioButtonGroup>
)
}
render(<RadioButtonGroupExample />)
Component preview theme
const RadioButtonGroupExample = () => {
return (
<RadioButtonGroup attached name="foo" legend="Choose a letter" helpText="Don't get it wrong!">
<RadioButton value="a">A</RadioButton>
<RadioButton value="b">B</RadioButton>
<RadioButton value="c" disabled>C</RadioButton>
</RadioButtonGroup>
)
}
render(<RadioButtonGroupExample />)

Radio Button Group labels should be 1-3 words to prevent the group from becoming too large. Use sentence case for each option.

Consider context and the user goal to determine the order of items. For example, days of the week have an obvious order, while asking users to select a programming language might be listed in order of anticipated popularity.

When possible, automatically select a default option.

Do

Use Radio Button Group when options are mutually exclusive and only one option is valid.

Don't

Don’t use Radio Button Groups if you need to select multiple options.

Do

Group related buttons in a Radio Button Group (e.g., types of graphs).

Don't

Don’t group buttons together that are not related to each other.

Do

Pair icon-only variants with text for better context.

Don't

Don’t use the icon-only variant if the icons are not easily recognizable.

Do

Use Radio Button Group to let users select one option from a list.

Don't

Don’t use Radio Button Groups for actions, such as save, edit, or delete. Use single Buttons or a Button Group instead.