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 English, Spanish, Tagalog USWDS v3
Allows users to select one or more items from a 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.

Examples - Single - v1

Default

View va-checkbox in Storybook

Checked

View va-checkbox checked in Storybook

Hint text

View va-checkbox with hint text in Storybook

Description String

View va-checkbox with description string in Storybook

Description JSX

View va-checkbox with description JSX in Storybook

Tile

View va-checkbox tile in Storybook

Error

View va-checkbox error in Storybook

Required

View va-checkbox required in Storybook

Internationalization

View va-checkbox internationalization in Storybook

Examples - Single - v3

Default

View va-checkbox v3 default and additional variations in Storybook

Examples - Group - v1

Default

View va-checkbox-group default in Storybook

Hint text

View va-checkbox group with hint text in Storybook

Error

View va-checkbox group error in Storybook

Required

View va-checkbox group required in Storybook

Single checkbox

View va-checkbox group single checkbox in Storybook

Internationalization

View va-checkbox group internationalization in Storybook

Examples - Group - v3

Default

View va-checkbox-group v3 default and additional variations in Storybook

Usage

Refer to the U.S. Web Design System for usage guidance

Additional guidance for VA

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

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>

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.
hint hint string Optional hint text.
label label string The text label for the checkbox group.
labelHeaderLevel label-header-level string Insert a header with defined level inside the label (legend)
required required boolean false Whether or not this input field is required.
uswds uswds boolean false Whether or not the component will use USWDS v3 styling.

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.

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.

Accessibility considerations

Refer to the U.S. Web Design System for accessibility guidance

Edit this page in GitHub (Permissions required)
Last updated: Sep 18, 2023