Components

Checkbox

Use: Deployed

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

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 message Checkbox 1

If you don't find your school in the search results, then check the box to enter in your school information manually. Error message Checkbox 2

<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 This is an error message

Checkbox label

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