Checkbox

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

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 dropdown boxes). 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
<h6>Default</h6>
<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" id="check-historical-truth" type="checkbox" name="historical-figures" value="sojourner-truth" 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>
      <label class="usa-checkbox__label" for="check-historical-carver">George Washington Carver</label>
    </div>
  </fieldset>
</form>

<h6 class="margin-top-7">Tile</h6>
<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>
      <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>
      <label class="usa-checkbox__label" for="check-historical-carver-2">George Washington Carver</label>
    </div>
  </fieldset>
</form>

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 different

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

Usability guidelines

  • 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

  • Customize accessibly. If you customize the text inputs, ensure they continue 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 it’s for attribute.

Implementation

Checkbox settings
Variable Description
$theme-checkbox-border-radius

Checkbox border radius for rounded corners

$theme-input-tile-background-color-selected

Tile background color when selected

$theme-input-tile-border-radius

Tile border radius for rounded corners

$theme-input-tile-border-width

Tile border thickness

$theme-input-tile-border-color

Tile border color

$theme-input-tile-border-color-selected

Tile border color when selected

Checkbox variants
Variant Description
usa-checkbox__input--tile Input tiles provide a larger interaction area and neatly group the label with the form control for readability. They’re useful in application forms and questionnaires, but may not be recommended when they create clutter on the page.

Package information

  • Package usage: @import form-controls
  • Requires: required, global