Checkbox

Guidelines

When to Use

• Use checkboxes when there is a list of options and the user may select any number (or none) of the choices.
• Use a Required Checkbox when an acknowledgment is required. For example, if a user must confirm that they have read Terms & Conditions on a page.

When Not to Use

• Do not use checkboxes when there is a list of two or more options and the user must select only one option. Use a radio button instead.

Variants

Checkbox + Label

Use a checkbox + label when only a text label is needed.

Selector Checkbox

Use a selector checkbox to display complex content like product details or shipping information.

Required Checkbox

• Use a required checkbox component to enforce mandatory selection. This component prevents users from proceeding until they check the box.
• Use for legal agreements and critical acknowledgments.
• Use the emphasized variant when users might miss the checkbox or when you need to add visual weight to ensure the selection is noticed before proceeding.

Required Checkbox

Emphasized Required Checkbox

States

Unchecked

• Option is unchecked.

Checked

• Option is checked.

Indeterminate

• The parent checkbox with nested child checkboxes may have this state. It occurs when nested checkboxes have mixed checked and unchecked states. See the section below on Nested Checkboxes.

Error

• An error has occurred. See error handling section below.

Skeleton

• Use this state whenever data is being loaded to help establish a user's mental model of the component's shape and the page layout.
• Use when the majority of page elements are loaded from API calls.
• The skeleton is temporary and should disappear once the data is loaded.

Usage

• Checkboxes allow users to select one or more items from a list of options.
• It is generally best practice to leave all checkbox options unchecked by default. This ensures that users review the options carefully and make an intentional choice.

Checkbox Groups

Do not mix checkbox + label and selector checkbox variants in the same group.

Do

Do Not

Content

• Always include labels unless the content provides enough context for users and has met accessibility requirements.
• Be concise and scannable.
• Try to describe what the user can do with the selected option, instead of what the user can’t do. Avoid negative language when possible.

• When the label is a statement or complete sentence, use sentence case with end punctuation.
• When the label is an incomplete sentence, use title case without end punctuation.
  • Incomplete Sentence: Save as Default Shipping Address
  • Sentence: Save this as your default shipping address.
• When appropriate, change text weights and colors to highlight information.
• Give users the option to select “none” if it is a valid answer instead of leaving all options unchecked.
• Clearly explain how many options the user can select near the checkboxes. Do not assume users know how many options they can select when displaying checkboxes.

Order of Options

List the options in a logical and meaningful order:

• Most to least frequently selected
• Positive to negative
• Simplest to most complex
• Safest to most risk
• Numerical or alphabetical (Keep in mind that the alphabetical order will change when the labels are localized)

Behavior

• Selecting the label or checkbox will check or uncheck the checkbox.
• Selecting a checkbox should not immediately submit the selection. A selection is applied only if the entire form is submitted.
• The label will wrap to the next line if it does not fit in the available horizontal space.

Error Handling

Checkbox Groups

Fieldset Level Error

• When a required selection is not made, a critical notification should display instructions on how to fix the error. Even when a fieldset has nested checkboxes, limit it to a single critical notification at the top.

Required Checkbox

When users attempt to proceed without selecting the required checkbox, display an error message that clearly states what the user must do to continue.

Nested Checkboxes

• Checkboxes can have parent-child relationships.
• When the parent is selected, all child checkboxes are checked.
• When the parent is deselected, all child checkboxes are unchecked.
• When all children are selected or deselected, the parent checkbox is set to the matching state.
• When the child checkboxes are a mix of checked and unchecked states, the parent checkbox is set to indeterminate.

Placement

When possible, align checkboxes in a group vertically stacked for easier reading.

Structure

Checkbox + Label

1. Checkbox: Positioned to the top left of its label.
2. Label

Spacing

Options in a checkbox group should be vertically spaced 16px.

Checkbox + Label

Selector Checkbox Button

Native App Considerations

There are no Native App specific considerations for this component.

Accessibility

Keyboard Accessibility

[AC1] When there is a checkbox on the page:

• Focus can be moved to the checkbox using TAB.

[AC2] When the checkbox is in focus:

• The focus indicator is clearly visible.
• Pressing SPACE toggles the checked state of the checkbox.

[AC3] If there is a group of nested checkboxes and the parent checkbox is in focus:

• Pressing SPACE toggles the parent checkbox between the checked, unchecked, and mixed states.

Screen Reader Output

[AC1] When a screen reader user presses DOWN ARROW to a group of related checkboxes:

• Name: The corresponding group name of the checkboxes is announced.
• “Grouping” is announced as the screen reader enters the group, and “Out of grouping” is announced as the screen reader exits the group.

Example Output: “Sandwich Toppings Grouping”

• Name: “Sandwich Toppings”

[AC2] When the screen reader TABS to an individual checkbox:

• Name: The name of the checkbox is announced.
• Role: The role of “checkbox” is announced.
• State: The current state (“checked”, “not checked”, or “mixed”) is announced.
• If the checkbox is required, “required” is announced.

Example Output: “Lettuce checkbox not checked required”

• Name: “Lettuce”
• Role: “checkbox”
• State: “unchecked”

[AC3] When a checkbox is toggled using SPACE:

• State: The correct change in state (“checked” or “unchecked”) is announced.

[AC4] When a screen reader user TABS __to a checkbox in an error state:

• Name: The name of the checkbox is announced.
• Role: The role of “checkbox” is announced.
• State: The current state (“checked”, “not checked”, or “mixed”) is announced. The “invalid” state is also announced.
• The corresponding error message is announced.
• If the checkbox is required, “required” is announced.

Example Output: “I have read and agreed to the terms and conditions. Error: You must agree to the terms and conditions. Invalid entry checkbox not checked required.”

• **Name: “**I have read and agreed to the terms and conditions.”
• Role: “Checkbox”
• State: “Invalid entry”, “unchecked”
• Error Message: “Error: You must agree to the terms and conditions.”

Developer Notes

• Use semantic HTML:
  • Use <input type=”checkbox”> and <label> to create checkboxes.
  • Use <fieldset> to group related checkboxes together and use <legend> to provide a group label.
  • Single checkboxes don’t require a <legend> and <fieldset>.
  • Add the “required” attribute to the fieldset or individual <input> if the checkbox is required.
• For error states:
  • Use aria-live=”assertive” for the error message container.
  • Use aria-describedby to associate the error message with the checkbox.
• For custom components:
  • Use role=”checkbox” to indicate a checkbox.
  • Use aria-checked=”true/false” to indicate changes in checkbox state.
  • Use role=”group” on the checkbox container to indicate related checkboxes.
  • Use aria-label or aria-labelledby to provide a group name to related checkboxes.
• For nested checkboxes:
  • Use aria-checked=”mixed’ for indicating a mixed state for parent checkboxes.
  • Use aria-controls=”Element_ID1 Element_ID2:” on the parent checkbox to identify the checkboxes controlled by the parent checkbox.

In the Wild