Design System

Radio Group

All the basic form elements for Twilio Paste

yarn add @twilio-paste/form — or — yarn add @twilio-paste/core


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:

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#

🚨STOP!🚨 Before continuing, make sure to follow these content guidelines.


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/form - or - yarn add @twilio-paste/core


import {Radio, RadioGroup} from '@twilio-paste/form';
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

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

1.5.3 (2020-05-28)

Note: Version bump only for package @twilio-paste/form

1.5.2 (2020-05-27)

Note: Version bump only for package @twilio-paste/form

1.5.1 (2020-05-27)

Bug Fixes#

1.5.0 (2020-05-22)


  • form: export styled InputElement, add FormControlWrapper (04da812)

1.4.1 (2020-05-20)

Note: Version bump only for package @twilio-paste/form

1.4.0 (2020-05-13)

Bug Fixes#

  • form: remove required onChange from input (49b2c77)


  • select: update knobs for select stories (#430) (dc48f63)

1.3.4 (2020-05-07)

Note: Version bump only for package @twilio-paste/form

1.3.3 (2020-05-07)

Bug Fixes#

  • form: updates to tokens used in borders (e97e49e)

1.3.2 (2020-05-04)

Note: Version bump only for package @twilio-paste/form

1.3.1 (2020-05-01)

Note: Version bump only for package @twilio-paste/form

1.3.0 (2020-05-01)


  • select: Select, Option, and OptionGroup (#399) (761924e)

1.2.0 (2020-04-25)


  • form: add radio and checkbox components (1b68f8d)
  • form: updates to form label (72c37c2)

1.1.10 (2020-04-22)

Bug Fixes#

  • tokens: Add shadow-border-input-* aliases, tokens to themes (#400) (a553100)

1.1.9 (2020-04-20)

Note: Version bump only for package @twilio-paste/form

1.1.8 (2020-04-17)

Note: Version bump only for package @twilio-paste/form

1.1.7 (2020-04-15)

Note: Version bump only for package @twilio-paste/form

1.1.6 (2020-04-08)

Bug Fixes#

  • form: package dependencies updated to be correct (48bb40f)

1.1.5 (2020-04-07)

Note: Version bump only for package @twilio-paste/form

1.1.4 (2020-04-07)

Bug Fixes#

  • form: use color prop, update tests and snapshots (1f7313a)

1.1.3 (2020-04-02)

Note: Version bump only for package @twilio-paste/form

1.1.2 (2020-04-01)

Bug Fixes#

  • form: enable safely spreading props to form controls (#367) (6a12a9d)

1.1.1 (2020-04-01)

Note: Version bump only for package @twilio-paste/form

1.1.0 (2020-04-01)


  • form: add autoresizing to the textarea component (#365) (9cc5b7b)

1.0.4 (2020-03-31)

Bug Fixes#

  • form: remove box-shadow, inherit font family (#362) (5cac3c4)

1.0.3 (2020-03-30)

Bug Fixes#

  • form: change hover for disabled and readonly input and textarea (#361) (7592de5)

1.0.2 (2020-03-28)

Note: Version bump only for package @twilio-paste/form

1.0.1 (2020-03-27)

Bug Fixes#

  • form: remove input type hidden box shadow (#359) (25301f4)

1.0.0 (2020-03-25)

Bug Fixes#

  • form: change FormHelperText to FormHelpText (7d8954d)


  • form: The FormHelperText component has been renamed to FormHelpText to align with the Sketch symbol library

0.2.3 (2020-03-24)

Bug Fixes#

  • form: switch from theme-tokens to theme package dep (9d26cda)

0.2.2 (2020-03-20)

Note: Version bump only for package @twilio-paste/form

0.2.1 (2020-03-17)

Note: Version bump only for package @twilio-paste/form

0.2.0 (2020-03-17)


0.1.2 (2020-03-17)

Note: Version bump only for package @twilio-paste/form

0.1.1 (2020-03-11)

Note: Version bump only for package @twilio-paste/form

0.1.0 (2020-03-11)


0.0.2 (2019-10-29)

Note: Version bump only for package @twilio-paste/form

0.0.1 (2019-08-15)#

Note: Version bump only for package @twilio-paste/form


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.