Components
Checkbox
Use: Deployed
USWDS v3
Examples - Single
Default
View va-checkbox in StorybookTile
View va-checkbox tile 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
On background
View va-checkbox on a background in Storybook
Error
View va-checkbox error in Storybook
Required
View va-checkbox required in Storybook
Internationalization
View va-checkbox internationalization in Storybook
Examples - Group
Default
View va-checkbox-group default in Storybook
Label header
View va-checkbox group label header in Storybook
Hint text
View va-checkbox group with hint text in Storybook
Required
View va-checkbox group required in Storybook
Single checkbox
View va-checkbox group single checkbox in Storybook
Tile
View va-checkbox group tile in Storybook
Forms pattern - Single
View va-checkbox group forms pattern single in Storybook
Forms pattern - Single error
View Error state for single checkbox pattern in Storybook
Forms pattern - Multiple
View Multiple checkbox pattern example in Storybook
Error
View Checkbox group with error state in Storybook
Internationalization
View Checkbox group with internationalization in Storybook
Indeterminate
Use the indeterminate state for a parent checkbox that controls a sublist of checkboxes. The parent checkbox shows this state when some (but not all) child checkboxes are selected.
See our pattern guidance on asking users for a mutually exclusive answer.
View Checkbox with indeterminate state in Storybook
Usage
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).
Choosing between variations
- Use the Forms pattern - Single and Forms pattern - Multiple variations for implementing the Ask users for a single response pattern. These component variations are specifically designed to help implement the single response pattern. The Forms pattern - Single error variation shows error handling for the component variation. For checkbox groups used outside of this pattern, for example on a longer form page, use the Label header checkbox group variation.
Conditionally revealed fields
Conditionally revealed fields show additional form elements only when a user selects a specific option. They help reduce visual complexity by showing follow-up questions only when they’re relevant.
When using conditionally revealed fields:
- Limit to one reveal per page. Avoid confusing the user with multiple expanding sections.
- Ensure keyboard accessibility. When a user selects the trigger option, they should be able to tab directly into the newly revealed field (which is why the trigger option is placed last).
- Make the revealed question self-explanatory. Avoid vague labels like “Other” for text fields. Instead, use clear, specific labels that work independently:
Since your relationship with the veteran was not listed, please describe it here
Errors
- Refer to the specific error examples above.
Hint text
- Refer to the hint text example above.
Code usage
Attributes and Properties
enableAnalytics
enable-analytics
boolean
false
Whether or not an analytics event will be fired.
error
error
string
A string with an error message.
formHeading
form-heading
string
The content of the heading if `useFormsPattern` is true.
formHeadingLevel
form-heading-level
number
3
The heading level for the heading if `useFormsPattern` is true.
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)
messageAriaDescribedby
message-aria-describedby
string
An optional message that will be read by screen readers when a checkbox is focused.
required
required
boolean
false
Whether or not this input field is required.
useFormsPattern
use-forms-pattern
string
Enabling this will add a heading and description for integrating into the forms pattern. Accepts `single` or `multiple` to indicate if the form is a single input or will have multiple inputs.
Events
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.
Using message-aria-describedby
In HTML, the attribute aria-describedby accepts ids of the elements that describe an object. This is used to establish a relationship between an element and text elsewhere that describes it for screen readers.
However, the VA.gov Design System uses web components and the shadow DOM, which prevents HTML’s aria-describedby from being able to establish the relationship between elements. Because of that, the message-aria-describedby prop is used in our components instead. Instead of accepting ids, it accepts a message string to read out. This message is placed inside the shadow DOM, hidden visually, but made accessible to screen readers. This allows it to function similarly to aria-describedby and have the descriptive text read out when the element is focused.
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.