Examples

Radio button list

A ChoiceList component can be used to render a radio button group or checkbox group. Use the type prop to specify the type of field to display.

Radio button children

Radio buttons can have optional checked or unchecked children that are conditionally shown based on the state of the checkbox.

Code

React

See Storybook "Choice" page and Storybook "Choice List" page for React documentation.

Style customization

The following CSS variables can be overridden to customize choice fields:

Form components

This component also makes use of form field styles, which can be customized by the following variables:

Guidance

When to use

Radio buttons

• When users need to select only one option out of a set of mutually exclusive choices.

When to consider alternatives

• If there are too many options to display on a mobile screen. Consider a dropdown menu if you don’t have enough space to list out all available options, and if the user can only select one of the options.
• Never use radio buttons for optional questions, since once a radio button is selected from a list, it or another choice will remain selected.

Usage

• Don't rely on the visual difference between radio buttons and checkboxes. Make it clear with words when users can select one or multiple options.
• Users should be able to tap on or click on either the text label or the checkbox to select or deselect an option.
• In general, list choices vertically; horizontal listings can make it difficult to tell which label pertains to which choice. An exception is where you have binary choices with short labels, like 'Yes / No'. The convention here is for horizontal alignment.
• Avoid using negative language in labels as they can be counterintuitive. For example, “I want to receive a promotional email” instead of “I don’t want to receive promotional email.”
• Use caution if you decide to set a default value. Setting a default value can discourage users from making conscious decisions, seem pushy, or alienate users who don’t fit into your assumptions. In addition, you'll never know if the user explicitly chose that option or just didn't notice the question. If you're unsure, leave nothing selected by default.

View the "Forms" guidelines for additional guidance and best practices.

Checked children and the expose within pattern

• The <Choice> component includes a checkedChildren prop that can expose hidden text information or form elements. This expose within pattern is especially useful if you need to collect data from follow up questions or give just-in-time feedback.
• Checked children can be exposed by checking the parent checkbox or radio button
• The checkedChildren prop should return one or more items wrapped in a div with the following className: .ds-c-choice__checkedChild. This class sets the spacing and border color for the exposed elements.
• Add the className .ds-c-choice__checkedChild--inverse to the div to show the inverse white border
• You may need to add the className .ds-u-margin--0 to your child element(s) to avoid extra top margin
• If you opt for smaller radio buttons or checkboxes, add className .ds-c-choice__checkedChild--small to your checked child container

Accessibility testing

General observations

• No other interactive elements (such as links or buttons) should be included inside the label or hint text.
• A group of radio buttons should be wrapped in a <fieldset> that includes a <legend> element within.
  • The <legend> provides context for the grouping, much like a label.
• Each input should have a semantic id attribute, and its corresponding label should have the same value in its for attribute.

Keyboard testing

• Each group of radio buttons can be accessed by keyboard using the tab key.
• Each radio button within a group can be accessed by keyboard using the arrow keys.
• Arrow keys are used to make a selection.
• There is a visible focus state.
• The change in state is visible.

If there are checkedChildren being used and...

• ...short conditional content, such as an alert, is present, users can tab to any interactive elements within the conditional content.
• ...lengthier conditional content is present, users should most likely be on the first legend or label element of the conditional content. They can then tab to any interactive elements within the conditional content.

Screen reader testing

For desktop users

• Some screen readers read the legend text for each form element within, so it should be brief and descriptive.
• In a radio group, I should hear the question or title related to them via a legend inside a fieldset.
• Each label should be announced for every radio button.
• The radio button element should be identified with a role of radio.
• If hints or errors are present, they are read after the label.
• When the radio button is selected, that state is read out

If there are checkedChildren being used and...

• ...short conditional content, such as an alert, is present, users will hear the child elements read out after the radio is selected because of the aria-live being used.
• ...lengthier conditional content is present, users will not hear the child elements being read as they are displayed.

For mobile users

• All the above from the desktop screen reader experience apply.
• Swiping focuses on a radio button.
• Doubletapping with the radio button in focus makes a selection and announces its been selected.

Pointer device testing

• Users may select either the text label or the radio button itself to select an option.
• Click/tap target area is a minimum of 24x24px.

Read our Form Validations guidance for communicating to users about form errors and how to fix them.

Related patterns

• Dropdown

Learn more

• Form Guidelines
• GOV.UK Checkbox/Radio buttons discussion

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel
• "We've updated the radios and checkboxes on GOV.UK"

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel
• Four steps for choosing form elements on the Web (PDF)

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel

Component maturity