Skip to content
Change the site theme
Figma
(information)

Radio Button Group

Design assets pending
Peer review pending

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


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.

Use the text + icon variant when icons are not easily recognizable (e.g., 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, pairing it with a text label is recommended.

Radio Button Groups:

  • Should have between 2–6 options
  • Are comprised of mutually exclusive options
  • Have a default option selected when possible
  • Labels should use sentence case

When to use Radio Button Group

When to use Radio Button Group page anchor
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.

Installation

Installation page anchor
yarn add @twilio-paste/radio-button-group - or - yarn add @twilio-paste/core
import {RadioButtonGroup, RadioButton} from '@twilio-paste/core/radio-button-group';
const Component = () => (
<RadioButtonGroup attached>
<RadioButton>One</RadioButton>
<RadioButton>Two</RadioButton>
<RadioButton>Three</RadioButton>
</RadioButtonGroup>
);

Radio Button Group Props

Radio Button Group Props page anchor

All the valid HTML attributes for input[type="radio] are supported including the following props:

PropTypeDescriptionDefault
childrenReact.ReactElement[]RadioButton
namestringName for the Radio Button Groupnull
attached?booleanIf the group of buttons are visually attachedfalse
legendstringLabel text for the Radio Button Groupnull
helpText?stringHelp text for the Radio Button Groupnull
id?stringID for the Radio Button Groupnull
value?stringValue for the Radio Button Groupnull
disabled?booleanMake the Radio Button Group disabledfalse
onChange?(event: React.MouseEvent<HTMLElement>)Pass a function for the onChange handlernull
errorText?stringError text for the Radio Button Groupnull
element?stringOverrides the default element name to apply unique styles with the Customization Provider'RADIO_BUTTON_GROUP'
i18nRequiredLabel?stringOverrides the default string marking the group as required'(required)'

All the valid HTML attributes for div are supported including the following props:

PropTypeDescriptionDefault
childrenReact.ReactElement[]Contents of the Radio Button
hasError?booleanAdds an error state to the Radio Buttonfalse
defaultChecked?booleanSets the Radio Button as the default checked optionfalse
checked?booleanSets the Radio Button as checkedfalse
id?stringID for the Radio Buttonnull
value?stringValue for the Radio Buttonnull
disabled?booleanMake the Radio Button disabledfalse
namestringName for the Radio Button Groupnull
element?stringOverrides the default element name to apply unique styles with the Customization Provider'RADIO_BUTTON'

Black lives matter.