Components
Checkbox
Use: Deployed English, Spanish, Tagalog
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 ofusa-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.
If you don't find your school in the search results, then check the box to enter in your school information manually.
<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
<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. | |
hint |
hint |
string |
Optional hint text. | |
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 correspondinglabel
should have the same value in it’sfor
attribute. - The
title
attribute can replace<label>
.