A Checkbox is a binary input that can appear by itself or in a multiselect group. Checkboxes can be selected, unselected or in an indeterminate state.
Checkboxes must feature a descriptive label. They may appear alone or as a part of a group. A checkbox may also have sub-options or child checkboxes.
Use the Checkbox component when you want users to make one or more selections from a list of options. A checkbox can also be used to accept terms and conditions. Avoid using checkboxes when only one selection is allowed; in such cases, use Radio instead.
The checkbox’s input makes the selection visually distinct.
The label text size should match the base font size to ensure consistency with the body text. It can also include links and bold text. Labels should be short, with text that clearly states what action is selected.
Refer to the Checkbox component in Codex Figma.
The styles for checkbox states were designed with accessible color variations. In addition to the 'check' icon, these make the checkboxes’ selected or unselected states (e.g. disabled, hover, active) easier to perceive:
- Default unselected
- Hover unselected
- Active unselected
- Focus unselected
- Error unselected
- Error-hover unselected
- Error-active unselected
- Error-focus unselected
- Default selected
- Hover selected
- Active selected
- Focus selected
- Error selected
- Error-hover selected
- Error-active selected
- Error-focus selected
- Default indeterminate
- Disabled unselected
- Disabled selected
- Disabled indeterminate
The error checkbox must always be accompanied by an inline error message,whether for a group or an individual checkbox. This message ensures users are informed about the error and provides guidance to fix it.
The disabled state does not meet our minimum color contrast rules. WCAG 2.1 states that “…part[s] of an inactive user interface component […] have no contrast requirement”.  Provide sufficient information in a disabled element's context, so the user can understand what is disabled and how to enable it (if applicable).
In addition to selected and unselected, a checkbox can be in an indeterminate state. This state uses the 'subtract' icon. It is common for checkboxes to present a number of sub-options (which are also checkboxes). If all of the sub-options are checked, the main checkbox will also be checked, and if they're all unchecked, the main checkbox would be unchecked. If any one or more of the sub-options have a different state than the others, the main checkbox would present an indeterminate state. 
A checkbox lets a reader choose one or more options from a list.
- Split the sentence in the leading label across the choices. Translatable
- Web Content Accessibility Guidelines (WCAG) 2.1 – Success Criterion 1.4.3 Contrast (Minimum)
<input type="checkbox">Indeterminate state checkboxes
Open up the browser console to see events emitted on input.
Single checkbox with label and description
Always include label text via the default slot. You can also add description text via the
A single checkbox does not need an
v-model is bound to a boolean value:
true for checked,
false for unchecked.
Checkbox value: false
This improves privacy and helps prevent unsolicited emails.
When used in a form, a single Checkbox or group of Checkboxes can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.
When building a Checkbox field, always set
true, even for a single Checkbox, to ensure accessibility support. This wraps the group in a
<fieldset> element and labels it with an associated
If using a Checkbox or Checkbox group outside of a form, follow the instructions in the next demo.
For a group of related checkboxes, each Checkbox component's
v-model will be bound to an array of the
inputValue props of the checkboxes that are currently "on".
This demo shows what to do when using a Checkbox group outside of a form:
- Wrap the group in an element with
- Connect the group with a label via the
Checkbox group value: [ "checkbox-2", "checkbox-6" ]
inline prop to get an inline layout.
The indeterminate state indicates that a checkbox is neither on nor off. Within this component, this state is purely visual. The parent component must house the logic to set a checkbox to the indeterminate state via this prop (e.g. in the case of a set of nested checkboxes where some boxes are checked and some are not, making the parent checkbox neither fully on nor fully off).
This prop is independent of the value provided by
indeterminate is set to
true, the indeterminate visual state will display, but the value will not be affected. Nor will the value affect the visual state: indeterminate overrides the checked and unchecked visual states. If indeterminate changes to false, the visual state will reflect the current v-model value.
In the example below, all of the checkboxes have their
indeterminate prop set to
true initially. As a result, they all appear to be in the indeterminate state initially, whether they are checked or not. Checking or unchecking a checkbox will undo the indeterminate state since you have provided a definite value for the checkbox.
Checkbox group value: [ "checkbox-2", "checkbox-4" ]
Typical use of this component will involve using
v-for to loop through an array of items and output a Checkbox component for each one. Each Checkbox will have the same
v-model prop, but different
inputValue props and label content.
For a single checkbox, the
v-model value will be a boolean
true when the checkbox is checked and
false when unchecked.
For multiple checkboxes, the
v-model value will be an array of the
inputValue props of any currently checked checkboxes (or an empty array if no checkboxes are checked).
|Value of the checkbox or checkbox group.|
|HTML "value" attribute to assign to the input.|
Required for input groups.
|Whether the disabled attribute should be added to the input.||-|
|Whether the indeterminate visual state should be displayed.|
This is unrelated to the value provided by
|Whether the component should display inline.|
|modelValue ||Emitted when modelValue changes.|
|description||Short description text.|
The structure below can be used for most cases. If you need a description, see the section on that feature below.
To add a description below the label:
- Add a span after the
<label>element with an ID and class
cdx-label__description. Include the description text here.
- Add class
- Wrap the label and description in a div with classes
- Add an
aria-describedbyattribute to the
<input>element with the value of the ID of the description
This improves privacy and helps prevent unsolicited emails.
Native attributes of the
<input> element can be used. For example:
- Add the
checkedattribute to the
<input>element if it should be selected initially.
- Add the
disabledattribute to the
<input>element if it should be disabled.
Always include one of these two features for accessible grouping:
- If using the Checkbox group in a field, wrap the group in a
<fieldset>element and add a
<legend>element with the group label. This method is demonstrated below and requires some style resets on
<legend>. You can use the CSS-only Field and Label components to reset browser styles of these elements.
- If using the Checkbox group outside of a field, wrap the group in a
aria-labelledbyset to the ID of the group label. See an example of this above (you can just include a
<label>element instead of using the Label component).
cdx-checkbox--inline class to the root element to get an inline layout.