Checkboxes allow users to select one or more options from a list.
About the checkbox component
When to use the checkbox component
- To display multiple answers. When a user can select any number of choices from a list.
- To allow users to toggle answers. When a user needs to acknowledge acceptance of something (like terms of service) or switch between two opposite states, such as unchecked = “no” and checked = “yes.”
When to consider something else
- Single-select only. If a user can only select one option from a list of many, use radio buttons instead.
- Make the label selectable. Users should be able to select either the text label or the checkbox to select or deselect an option.
- List options vertically. Horizontal listings can make it difficult to tell which label pertains to which checkbox.
- Use positive statements. Negative language in labels can be counterintuitive. For example, use “I want to receive a promotional email” instead of “I don’t want to receive a promotional email.”
- Use logical labels. Make sure that the label makes both states — checked and unchecked — clear to the user. If that’s not possible, consider using a radio button with two individual options instead. Then both states can have their own clearly marked label.
- Use adequate touch targets. Make sure selections are adequately spaced for touch screens. Consider using the tile variant for larger touch targets.
- Don’t mix default and tile variants. Pick one implementation and stick with it. When mixed, tiles can appear to indicate a bias or preference toward that option.
- Use a logical order. Make sure the selection options are organized in a meaningful way, like alphabetical or most-frequent to least-frequent. This helps users easily find the option they’re looking for.
- Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
- Use a fieldset and legend for a checkbox group. Surround a related set of checkboxes with a
<legend>provides context for the grouping. Don’t use fieldset and legend for a single check.
- These custom checkboxes are accessible. The custom checkboxes here are accessible to screen readers because the default checkboxes are moved off-screen with
position: absolute; left: -999em.
- Use semantic tags. Each input should have a semantic tag for the
idattribute, and its corresponding label should have the same value in its
Using the checkbox component
Checkbox border radius for rounded corners.
Tile background color when selected.
Tile border radius for rounded corners.
Tile border thickness
Tile border color.
Tile border color when selected.
This component has no variants.
Meaningful code and guidance updates are listed in the following table:
Styled aria-disabled to match disabled.
Now disabled styling is applied whether you use
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
Added support for high contrast mode and forced colors. All our components now support proper display when users have a forced colors mode set in their operating system. More information: uswds#4610
Improved whitespace sensitivity of radio and checkbox tiles. Now radio and checkbox tiles will display consistently whether or not there’s extra whitespace in the markup. More information: uswds#4286
Improved class order sensitivity for checkbox and radio. Now checkbox and radio components display properly regardless of the order of the class and modifier names. More information: uswds#4262
Updated checkbox and radio buttons to include automatic accessible color. Now checkbox and radio buttons will display in the proper accessible color, and adapt to the text, link, and background colors you set in your projects’s settings. More information: uswds#4199
Fixed character display in checkboxes and radio buttons. Allowed checkboxes and radio buttons to display properly regardless of character encoding. More information: uswds#4080