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

Examples - Single - v1

Default

View va-checkbox v1 default and additional variations in Storybook

Examples - Group - v3

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 va-checkbox group forms pattern single error in Storybook

Forms pattern - Multiple

View va-checkbox group forms pattern multiple in Storybook

Error

View va-checkbox group error in Storybook

Internationalization

View va-checkbox group internationalization in Storybook

Examples - Group - v1

Default

View va-checkbox-group v1 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).

Conditionally revealed fields

In the radio button and checkbox components, we offer an option to conditionally reveal fields when the user selects an answer. These fields are often used to group related questions together by revealing a single follow-up question only when they’re relevant to the user.

Conditionally revealed fields can be used if the following conditions are met:

There should only be one reveal on a page.
When the revealed trigger is selected, you must be able to tab directly into the newly revealed field (Which is why we’ve put the “other” question last.)
The newly revealed question field must be understood by itself. For example, don’t just say “Other”. Instead, say:

Since your relationship with the veteran was not listed, please describe it here

An example of a conditionally revealed field — Example of asking the relationship to the Veteran with radio buttons and a conditionally revealed field.

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>

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.
`formHeading`	`form-heading`	`string`		The content of the heading if `useFormsPattern` and `uswds` are true.
`formHeadingLevel`	`form-heading-level`	`number`	`3`	The heading level for the heading if `useFormsPattern` and `uswds` are 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)
`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. `uswds` should be true.
`uswds`	`uswds`	`boolean`	`true`	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.

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.

Accessibility considerations

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

Checkbox

Examples - Single - v3

Default

Tile

Checked

Hint text

Description String

Description JSX

On background

Error

Required

Internationalization

Examples - Single - v1

Default

Examples - Group - v3

Default

Label header

Hint text

Required

Single checkbox

Tile

Forms pattern - Single

Forms pattern - Single error

Forms pattern - Multiple

Error

Internationalization

Examples - Group - v1

Default

Usage

Additional guidance for VA

When to consider something else

Conditionally revealed fields

Errors

Error message with a checkbox group

Code usage

Attributes and Properties

Events

Using message-aria-describedby

Native Events

Accessibility considerations