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 buttons can have optional checked or unchecked children that are conditionally shown based on the state of the checkbox.
The following CSS variables can be overridden to customize choice fields:
This component also makes use of form field styles, which can be customized by the following variables:
- When users need to select only one option out of a set of mutually exclusive choices.
- If there are too many options to display on a mobile screen. Consider a
dropdownmenu 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.
- 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.
<Choice>component includes a
checkedChildrenprop 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
checkedChildrenprop should return one or more items wrapped in a
divwith the following className:
.ds-c-choice__checkedChild. This class sets the spacing and border color for the exposed elements.
- Add the className
divto show the inverse white border
- You may need to add the className
.ds-u-margin--0to your child element(s) to avoid extra top margin
- If you opt for smaller radio buttons or checkboxes, add className
.ds-c-choice__checkedChild--smallto your checked child container
- Surround a related set of choices with a
<legend>provides context for the grouping. Do not use
legendfor a single checkbox.
- Some screen readers read the
legendtext for each
fieldset, so it should be brief and descriptive.
- Each input should have a semantic
idattribute, and its corresponding
labelshould have the same value in its
- The custom checkboxes and radio buttons here are accessible to screen readers because the default fields are moved off-screen.
checkedChildrenwill be announced to screen readers when they are exposed. They have been tested with the following devices:
- Windows 10 + Internet Explorer 11 + JAWS screen reader
- Windows 10 + Chrome + JAWS
- Windows10 - Firefox + NVDA
- NVDA reads out the
<select>label and every
- NVDA reads out the
- MacOS Mojave + Safari + VoiceOver
- Form Guidelines
- GOV.UK Checkbox/Radio buttons discussion
- "We've updated the radios and checkboxes on GOV.UK"
- Four steps for choosing form elements on the Web (PDF)
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.
ColorMeets AA color contrast standards for accessibility and color blindness.Complete
Forced Colors Mode (FCM)While using FCM the components text is legible and improves readability.Complete
WCAG 2.1 Level AA ConformanceAll Axe checks for WCAG AA compliance have passed.Complete
Screen readersVoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.Complete
Keyboard navigationComponent is fully navigable with a keyboard.Complete
StorybookComponent has stories to cover all defined props.Complete
ResponsiveComponent designed to work in all responsive breakpoints.Complete
Spanish translationsIncludes Spanish translations for default text content.Not applicable
CodeTokens implemented in code.Complete
DesignTokens implemented in the Sketch.Complete
On this page
- Learn more
- Component maturity