Components

Checkbox

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

Passed WCAG 2.1 AA

About the checkbox component

Checkboxes are an easily understandable way to indicate that users can select one or more answers to a question or items from a list. They’re always followed by a label or instructions that clearly indicate what checking the box represents.

Each checkbox has two different states: selected or unselected, which are similar to an on and off switch. If a checkbox label says “Yes, send me an email,” it’s clear what checking that box (or not checking it) will accomplish.

Checkboxes also visibly show users what’s been selected and makes it easy for them to “uncheck” an option, which can be difficult with other selection methods on a form (such as radio buttons or select menus). It’s common to include “check all that apply” instructions with checkboxes to let users know it’s okay to select more than one option at a time.

Default

Select any historical figure

Tile

Select any historical figure 

<h3 class="site-preview-heading">Default</h3>
<fieldset class="usa-fieldset">
  <legend class="usa-legend">Select any historical figure</legend>
  <div class="usa-checkbox">
    <input
      class="usa-checkbox__input"
      id="check-historical-truth"
      type="checkbox"
      name="historical-figures"
      value="sojourner-truth"
      checked="checked"
    />
    <label class="usa-checkbox__label" for="check-historical-truth"
      >Sojourner Truth</label
    >
  </div>
  <div class="usa-checkbox">
    <input
      class="usa-checkbox__input"
      id="check-historical-douglass"
      type="checkbox"
      name="historical-figures"
      value="frederick-douglass"
    />
    <label class="usa-checkbox__label" for="check-historical-douglass"
      >Frederick Douglass</label
    >
  </div>
  <div class="usa-checkbox">
    <input
      class="usa-checkbox__input"
      id="check-historical-washington"
      type="checkbox"
      name="historical-figures"
      value="booker-t-washington"
    />
    <label class="usa-checkbox__label" for="check-historical-washington"
      >Booker T. Washington</label
    >
  </div>
  <div class="usa-checkbox">
    <input
      class="usa-checkbox__input"
      id="check-historical-carver"
      type="checkbox"
      name="historical-figures"
      value="george-washington-carver"
      disabled="disabled"
    />
    <label class="usa-checkbox__label" for="check-historical-carver"
      >George Washington Carver</label
    >
  </div>
</fieldset>

<h3 class="site-preview-heading">Tile</h3>
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Select any historical figure</legend>
    <div class="usa-checkbox">
      <input
        class="usa-checkbox__input usa-checkbox__input--tile"
        id="check-historical-truth-2"
        type="checkbox"
        name="historical-figures-2"
        value="sojourner-truth"
        checked="checked"
      />
      <label class="usa-checkbox__label" for="check-historical-truth-2"
        >Sojourner Truth
        <span class="usa-checkbox__label-description"
          >This is optional text that can be used to describe the label in more
          detail.</span
        ></label
      >
    </div>
    <div class="usa-checkbox">
      <input
        class="usa-checkbox__input usa-checkbox__input--tile"
        id="check-historical-douglass-2"
        type="checkbox"
        name="historical-figures-2"
        value="frederick-douglass"
      />
      <label class="usa-checkbox__label" for="check-historical-douglass-2"
        >Frederick Douglass</label
      >
    </div>
    <div class="usa-checkbox">
      <input
        class="usa-checkbox__input usa-checkbox__input--tile"
        id="check-historical-washington-2"
        type="checkbox"
        name="historical-figures-2"
        value="booker-t-washington"
      />
      <label class="usa-checkbox__label" for="check-historical-washington-2"
        >Booker T. Washington</label
      >
    </div>
    <div class="usa-checkbox">
      <input
        class="usa-checkbox__input usa-checkbox__input--tile"
        id="check-historical-carver-2"
        type="checkbox"
        name="historical-figures-2"
        value="george-washington-carver"
        disabled="disabled"
      />
      <label class="usa-checkbox__label" for="check-historical-carver-2"
        >George Washington Carver</label
      >
    </div>
  </fieldset>
</form>

Guidance

When to use the checkbox component

  • To display multiple answers. When a user can select any number of choices from a list.
  • To allow users to toggle answers. When a user needs to acknowledge acceptance of something (like terms of service) or switch between two opposite states, such as unchecked = “no” and checked = “yes.”

When to consider something else

  • Single-select only. If a user can only select one option from a list of many, use radio buttons instead.

Usability guidance

  • Make the label selectable. Users should be able to select either the text label or the checkbox to select or deselect an option.
  • List options vertically. Horizontal listings can make it difficult to tell which label pertains to which checkbox.
  • Use positive statements. Negative language in labels can be counterintuitive. For example, use “I want to receive a promotional email” instead of “I don’t want to receive a promotional email.”
  • Use logical labels. Make sure that the label makes both states — checked and unchecked — clear to the user. If that’s not possible, consider using a radio button with two individual options instead. Then both states can have their own clearly marked label.
  • Use adequate touch targets. Make sure selections are adequately spaced for touch screens. Consider using the tile variant for larger touch targets.
  • Don’t mix default and tile variants. Pick one implementation and stick with it. When mixed, tiles can appear to indicate a bias or preference toward that option.
  • Use a logical order. Make sure the selection options are organized in a meaningful way, like alphabetical or most-frequent to least-frequent. This helps users easily find the option they’re looking for.

Accessibility guidance

Test the checkbox component in your own project.

USWDS tested the checkbox component for accessibility. You should test your implementation, too.

Use checkbox accessibility tests
  • Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
  • Use a fieldset and legend for a checkbox group. Surround a related set of checkboxes with a <fieldset>. The <legend> provides context for the grouping. Don’t use fieldset and legend for a single check.
  • These custom checkboxes are accessible. The custom checkboxes here are accessible to screen readers because the default checkboxes are moved off-screen with position: absolute; left: -999em.
  • 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.

Using the checkbox component

Checkbox settings

Variable Description
$theme-checkbox-border-radius

Checkbox border radius for rounded corners.
$theme-input-background-color

Background color for radio and checkbox inputs.
$theme-input-tile-border-radius

Tile border radius for rounded corners.
$theme-input-tile-border-width

Tile border thickness

Checkbox variants

This component has no variants.

Accessibility test status

The USWDS team did 8 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
8 7 0 1 0

Overview of recent accessibility test results:

  • Passed: 7
  • Passed with exceptions: 0
  • Conditional: 1
  • Failed: 0

Learn more on the checkbox accessibility tests page.

Package

  • Package usage: @forward "usa-checkbox";
  • Dependencies: uswds-fonts, usa-fieldset, usa-legend, usa-input-list

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-11-13 3.10.0
  • Assets
 No

Removed style tags from indeterminate checkbox SVGs. These style tags were unnecessary and caused a conflict with some automated testing tools. More information: uswds#6162

2024-09-18 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2803

2024-04-26 3.8.0
  • Assets
  • Styles
 No

Added indeterminate styles for checkboxes. Checkboxes will now display as indeterminate when you set input.indeterminate = true via JavaScript or add the data-indeterminate attribute. This is currently only a style addition and does not affect checkbox functionality. More information: uswds#5713

2023-11-20 N/A
  • Guidance
 No

Added usa-input-list to the list of dependencies. More information: uswds-site#2149

2023-09-29 3.6.1
  • Accessibility
  • Styles
 No

Updated radio and checkbox tiles to have lighter borders, reducing visual noise. More information: uswds#5494

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved legibility in forced colors mode. Adds a consistent border in forced colors mode. More information: uswds#5147

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2022-08-05 3.1.0
  • Accessibility
  • Styles
 No

Styled aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). More information: uswds#4783

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-11 2.13.3
  • Accessibility
  • Styles
 No

Added support for forced colors mode. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610

2021-08-18 2.12.1
  • Styles
 No

Improved whitespace sensitivity of radio and checkbox tiles. Now radio and checkbox tiles will display consistently whether or not there’s extra whitespace in the markup. More information: uswds#4286

2021-08-18 2.12.1
  • Styles
 No

Improved class order sensitivity for checkbox and radio. Now checkbox and radio components display properly regardless of the order of the class and modifier names. More information: uswds#4262

2021-06-16 2.12.0
  • Accessibility
  • Styles
 No

Updated checkbox and radio buttons to include automatic accessible color. Now checkbox and radio buttons will display in the proper accessible color, and adapt to the text, link, and background colors you set in your projects’s settings. More information: uswds#4199

2021-03-17 2.11.0
  • JavaScript
  • Styles
 No

Fixed character display in checkboxes and radio buttons. Allowed checkboxes and radio buttons to display properly regardless of character encoding. More information: uswds#4080