Radio Group

A radio group is used for selecting a single choice from a list of at least two options

Import from
@twilio-paste/core/radio-group — or — @twilio-paste/radio-group


A radio group is used for selecting a single choice from a list of at least two options. The user can only select one radio option at a time.

About Radio Group#

Radio groups are used when a user has a single choice to make from two or more options. The user can only choose one radio selection at a time.

Radio groups should:

  • Include at least two or more options
  • Allow users to select only one option
  • Include at most 6 options (use your discretion here if you need more; if there's a chance in the future that it might be more than 6, use a Select component drop-down) If there is help text that the user needs to know before making selection, use checkbox/radio.
  • List options in a rational order that makes logical sense

Best Practices#

  • See content guidelines for copy requirements
  • Avoid nesting radio buttons with other radio buttons
  • If an option is strongly recommended, add "(Recommended)" to the label. Be sure to add to the label, not the help text
  • See Default Pre-Selected State to determine if you should have a default selection
  • Use the same name attribute on all radio buttons in the group. This ensures that if there is more than one group in the form, each one stays associated with its own group
  • If a radio group is “Optional”, users won't be able to unselect a selected radio. If you need to give users a way to unselect, consider adding a clear button or using another type of form field.
  • Use a Select Component if there is a chance additional options over 6 will be added in the future.

Accessibility Information#

  • A radio group must have a visible label that is in close proximity to the control
  • HTML radio groups don't natively support the required attribute. In cases where a radio is required to be checked:
    • Display a required indicator
    • Ensure the radio label text includes wording that successfully describes the requirement to the user that they should select the radio
  • When in an error state, display an inline error message below the offending radio group that clearly describes the error.

Layout Examples#

Vertically Stacked Radio Group#

Use this option if labels are too long (see horizontal alignment for limits) or the list needs to wrap to two lines.

An optional default choice is pre-selected (see Default Pre-Selected State below).

When should your campaign run?
We recommend at least two weeks.

Default Pre-Selected State#

By default, we don't have a pre-selected state. It's at the discretion of Paste consumers to set a default selected option. If there is a pre-selected state, be sure to make the first option the default option. Please review this article to determine if you should default a selection: takes you to an external page.

Don't have a default selection if:

  • A default value would incorrectly imply that the user doesn't need to make a selection when they actually need to make a choice.
  • You are collecting unbiased data. Defaulting to an option biases or alters the experience in an undesired way and your data will be skewed
  • There is no acceptable default option for safety, security, or legal reasons and therefore the user must make an explicit choice. (show display error)

Component Example

With Help Text#

You can provide additional information about the group with the use of help text. Help text can appear after the group label but before the first option. Use the group label to explain the purpose of the group, not how to make the selection. Assume that users know how to use radio buttons. For example, don't say "Select one of the following choices".

Choose Network Access Profile
Network Access Profile specifies what networks your SIM's would connect to and how you will be billed.

Required Usage#

Use the required dot only when necessary to denote it is required. This goes before the fieldset legend.

Required: SSL Certificate Validation
Determines if certificate validation is performed on all Twilio originated requests.

Horizontal Alignment#

  • Options are placed next to each other, in logical order, with appropriate spacing. If people can easily compare shorter options from left to right, use this alignment
  • Do not run onto two lines
  • If the label is longer than 3 words/20 characters, consider using a vertically stacked version. If the content is too long, please use vertical stacking
Select payment method



Checked and disabled#

Disabled group#

Exit Criteria

Group Error#

If the selected items don't pass the group validation requirements an inline error message should be displayed.

An inline error is placed at the bottom of the group to inform a user of any errors in their choices.

Exit Criteria
Please select an exit criteria.

Individual error#

Composition notes#

When to use an Radio Group#

Use a Radio Group to select a single option from a list of two, but no more than six (use your discretion) options.

Content Guidelines#

🚨 Before continuing, make sure to follow these


Validate the group on form submission. Don't validate each item in the group, treat validation on the group as a whole.


Error text should go below groups.

Labels and Help Text#

  • Radio text should not end in punctuation even if it's a sentence, but especially it it's a word or a fragment
  • Use with an associated label component
  • All labels begin with a capital letter

Usage Guide#



yarn add @twilio-paste/radio-group - or - yarn add @twilio-paste/core


import {Radio, RadioGroup} from '@twilio-paste/radio-group';
const Component = () => (
<RadioGroup name="foo" value="foo" legend="foo" onChange={NOOP}>
<Radio id="foo" value="foo" name="foo">

Radio Props#

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

helpText?string or ReactNodenull
onChange?(event: React.MouseEvent<HTMLElement>)null
onFocus?(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null

RadioGroup Props#

legendstring or ReactNodenull
orientationoneOf(['vertical', 'horizontal'])vertical
errorText?string or ReactNodenull
helpText?string or ReactNodenull
onChange(event: React.MouseEvent<HTMLElement>)null
onFocus?(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null


If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.


The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.