# Checkbox Checkboxes allow users to select one or more options from a list. ## Guidance ### When to use **Checkboxes** - When a user can select any number of choices from a set list. - When a user needs to choose “yes” or “no” on only one option (use a stand-alone checkbox). For example, to toggle a setting on or off. - When users need to see all the available options at a glance. - When users should be able to select zero of the options. ### 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.](/patterns/Forms/forms/)** ### Checked children and the expose within pattern - The `` 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 The radio button component handles rendering labels, and if you’re using ChoiceList for a set of controls, will also wrap them in `
` to maintain accessibility, and `` to provide context. ### General accessibility guidance - For a single radio button, donʼt use `
` and ``. - Use semantic tags. Each input should have a semantic tag for the id attribute, and its corresponding label should have the same value in its for attribute. - No other interactive elements (such as links or buttons) should be included inside the label or hint text. - A group of checkboxes should be wrapped in a `
` that includes a `` element within. - The `` provides context for the grouping, much like a label. - Do not use `fieldset` and `legend` for a single checkbox element. - Normally an individual checkbox should not be a required field to complete a form but a checkbox group may be. - Each input should have a semantic `id` attribute, and its corresponding `label` should have the same value in its `for` attribute. - Be mindful of color contrast ratios between the checkbox and its background color. For instance, a dark green or blue behind the component will most likely cause problems for users. [Read our guidance on color for more information](https://design.cms.gov/foundation/system-color-tokens/#accessibility-considerations). ### Accessibility testing #### Keyboard testing - All checkboxes can be accessed using only the tab key. - The spacebar is used to check/uncheck a focussed checkbox. - There is a visible focus state. - The change in state is visible. #### 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. - Each label should be announced for every checkbox. - The checkbox element should be identified with a role of checkbox. - If hints or errors are present, they are read after the label. - In a checkbox group, I should hear the question or title related to them via a legend inside a fieldset. - When the checkbox is selected, that state is read out. **For mobile users** - All the above from the desktop screen reader experience apply. - Swiping focuses on a checkbox. - Double tapping with the checkbox in focus makes a selection and announces its been selected. ## Learn more - [Form Guidelines](/patterns/Forms/forms/) - ["We've updated the radios and checkboxes on GOV.UK"](https://designnotes.blog.gov.uk/2016/11/30/weve-updated-the-radios-and-checkboxes-on-gov-uk/)