Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Checkbox

Use: Deployed
Allows users to select one or more items from a visible list.

View va-checkbox-group in Storybook

View va-checkbox-group in Storybook

Usage

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 to consider something else

  • If there are too many options to display on a mobile screen.
  • If a user can only select one option from a list (use radio buttons instead).

How to use

  • Users should be able to tap on or click on either the text label or the checkbox to select or deselect an option.
  • List options vertically if possible; horizontal listings can make it difficult to tell which label pertains to which checkbox.
  • 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.”
  • If you customize, make sure selections are adequately spaced for touch screens.

Errors

  • Checkbox groups typically appear inside of <fieldset>s. The class name of usa-input-error may be placed on the <fieldset> that contains all of the checkboxes.
  • The error message is placed just below the <legend>.
  • See form error handling for additional guidance.
Error Error message
If you don't find your school in the search results, then check the box to enter in your school information manually. Error Error message
<div class="form-checkbox usa-input-error">
  <span class="usa-input-error-message" role="alert" id="errorable-checkbox-5-error-message">
    <span class="sr-only">Error</span> 
    Error message
  </span>
  <input aria-describedby="errorable-checkbox-5-error-message" id="errorable-checkbox-5" type="checkbox">
  <label class="usa-input-error-label" name="undefined-label" for="errorable-checkbox-5">Checkbox 1</label>
</div>

<div class="form-checkbox usa-input-error">
  <span class="label-above-checkbox">If you don't find your school in the search results, then check the box to enter in your school information manually.</span>
  <span class="usa-input-error-message" role="alert" id="errorable-checkbox-5-error-message">
    <span class="sr-only">Error</span> 
    Error message
  </span>
  <input aria-describedby="errorable-checkbox-5-error-message" id="errorable-checkbox-5" type="checkbox">
  <label class="usa-input-error-label" name="undefined-label" for="errorable-checkbox-5">Checkbox 2</label>
</div>

Error message with a checkbox group

Checkbox group Error: This is an error message
<fieldset class="fieldset-input usa-input-error">
  <legend class="legend-label usa-input-error-label">Checkbox group</legend>
  <span class="usa-input-error-message" role="alert" id="default-error-message">
    <span class="sr-only">Error:</span> This is an error message
  </span>
  <div class="form-expanding-group">
    <div class="form-checkbox-buttons">
      <input type="checkbox" autocomplete="false" id="default-0" value="value" />
      <label name="undefined-0-label" for="default-0">Checkbox label</label>
    </div>
  </div>
  <div class="form-expanding-group">
    <div class="form-checkbox-buttons">
      <input type="checkbox" autocomplete="false" id="default-1" value="value" />
      <label name="undefined-1-label" for="default-1">Checkbox label</label>
    </div>
  </div>
</fieldset>

Native Events

  • The native onBlur event is available on this component. It can be used by adding the event handler to your component and it will then listen to the event and respond accordingly when the event fires.

Code usage

Attributes and Properties

Property Attribute Type Default Description
enableAnalytics enable-analytics boolean false Whether or not an analytics event will be fired.
error error string A string with an error message.
label label string The text label for the checkbox group.
required required boolean false Whether or not this input field is required.

Events

Name Description
component-library-analytics The event used to track usage of the component. This is emitted when an input value changes and enableAnalytics is true.
vaChange The event emitted when the input value changes.

Accessibility considerations

  • Surround a related set of checkboxes with a <fieldset>. The <legend> provides context for the grouping. Do not use fieldset and legend for a single check.
  • The custom checkboxes here are accessible to screen readers because the default checkboxes are moved off-screen with margin-left: -2rem; opacity: 0; position: absolute; left: auto;.
  • Each input should have a semantic id attribute, and its corresponding label should have the same value in it’s for attribute.
  • The title attribute can replace <label>.
Edit this page in GitHub (Permissions required)
Last updated: Jun 14, 2022