Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Checkbox

Checkboxes allow users to select one or more options from a list.

Examples

Checkbox 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.

Loading

Checkbox children

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

Loading

Code

React

Checkboxes can be managed as a group using <ChoiceList> or individually using <Choice>.

Note that each of the items in the choices array represents props that will be passed to an individual <Choice> component. You can therefore define any of the props listed in the <Choice> component table below, including all valid attributes of the HTML input element.

<ChoiceList> component

React Properties Documentation
NameTypeDefaultDescription
choicesrequiredChoiceProps[]Array of Choice data objects to be rendered.
classNamestringAdditional classes to be added to the root element.
disabledbooleanDisables the entire field.
hintReactNodeAdditional hint text to display
requirementLabelReactNodeText showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.
inversedbooleanApplies the "inverse" UI theme
labelrequiredReactNodeLabel for the field
labelClassNamestringAdditional classes to be added to the FormLabel.
namerequiredstringThe field's name attribute
onBlur(...args: any[]) => anyCalled anytime any choice is blurred
onComponentBlur(...args: any[]) => anyCalled when any choice is blurred and the focus does not land on one of the other choices inside this component (i.e., when the whole component loses focus)
onChange(...args: any[]) => any
size"small"Sets the size of the checkbox or radio button
typerequiredChoiceListTypeSets the type to render checkbox fields or radio buttons
errorMessageReactNodeEnable the error state by providing an error message.
errorMessageClassNamestringAdditional classes to be added to the error message
errorIdstringThe ID of the error message applied to this field.
textClassNamestringAdditional classes to be added to the label text.
errorPlacement"top" | "bottom"Location of the error message relative to the field input
labelIdstringA unique id to be used on the field label. If one isn't provided, a unique ID will be generated.

<Choice> component

React Properties Documentation
NameTypeDefaultDescription
checkedbooleanSets the input's checked state. Use this in combination with onChange for a controlled component; otherwise, set defaultChecked.
checkedChildrenReactNodeContent to be shown when the choice is checked. See Checked children and the expose within pattern on the Guidance tab for detailed instructions.
uncheckedChildrenReactNodeContent to be shown when the choice is not checked
classNamestringAdditional classes to be added to the root div element.
inputClassNamestringAdditional classes to be added to the input element.
labelReactNodeLabel text or HTML.
labelClassNamestringAdditional classes to be added to the FormLabel.
defaultCheckedbooleanSets the initial checked state. Use this for an uncontrolled component; otherwise, use the checked property.
disabledboolean
errorMessageReactNode
errorMessageClassNamestringAdditional classes to be added to the error message
inputRef(...args: any[]) => anyAccess a reference to the input element
hintReactNodeAdditional hint text to display below the choice's label
idstringA unique ID to be used for the input field, as well as the label's for attribute. A unique ID will be generated if one isn't provided.
requirementLabelReactNodeText showing the requirement ("Required", "Optional", etc.). See Required and Optional Fields.
inversedbooleanApplies the "inverse" UI theme
size"small"
namerequiredstringThe input field's name attribute
onBlur(...args: any[]) => any
onChange(event: ChangeEvent<HTMLInputElement>) => any
typerequiredChoiceTypeSets the type to render checkbox fields or radio buttons
valuerequiredChoiceValueThe input value attribute
This component passes any additional props to its underlying <input> element as attributes. See the corresponding MDN documentation for <input> for a list of valid attributes.

Styles

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

CSS variables for choice
VariableDefault Core Theme Value
--choice__background-colorhex value: #ffffff--color-white
--choice__background-color--checkedhex value: #0071bc--color-primary
--choice__background-color--disabledhex value: #d9d9d9--color-border
--choice__background-color--inversehex value: #ffffff00--color-transparent
--choice__background-color--disabled--inverse#e9ecf126
--choice__border-colorhex value: #262626--color-base
--choice__border-color--checkedhex value: #0071bc--color-primary
--choice__border-color--disabledhex value: #a6a6a6--color-gray-light
--choice__border-color--errorhex value: #262626--color-base
--choice__border-color--error--inversehex value: #ffffff--color-white
--choice__border-color--inversehex value: #ffffff--color-white
--choice__border-color--lefthex value: #0071bc--color-primary
--choice__border-color--focushex value: #004f84--color-primary-darker
--choice__border-color--disabled--inversehex value: #a6a6a6--color-gray-light
--choice__border-radius0px
--choice__border-width2px
--choice__color--uncheckedhex value: #ffffff--color-white
--choice__color--disabledhex value: #5a5a5a--color-gray-dark
--choice__size32px
--choice__size--small20px
--choice__size-radio22px
--choice__size-radio--small12px
--choice-label__color--disabledhex value: #5a5a5a--color-gray-dark
--choice-label__color--disabled--inversehex value: #e9ecf1--color-muted-inverse

Form components

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

CSS variables for form
VariableDefault Core Theme Value
--form-label__color--inversehex value: #ffffff--color-white
--form__max-width460px
--form__max-width--small6em
--form__max-width--medium12em
--form-hint__colorhex value: #5a5a5a--color-gray-dark
--form-hint__color--inversehex value: #e9ecf1--color-muted-inverse
--form-error__colorhex value: #e31c3d--color-error
--form-error__color--inversehex value: #f7bbc5--color-error-lighter

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.

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

  • Surround a related set of choices with a <fieldset>. The <legend> provides context for the grouping. Do not use fieldset and legend for a single checkbox.
  • Some screen readers read the legend text for each fieldset, so it should be brief and descriptive.
  • Each input should have a semantic id attribute, and its corresponding label should have the same value in its for attribute.
  • The custom checkboxes and radio buttons here are accessible to screen readers because the default fields are moved off-screen.
  • checkedChildren will 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 <option> value
    • MacOS Mojave + Safari + VoiceOver

Learn more

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets 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.
    Incomplete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Not applicable

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete