Checkbox
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.
Guidelines
When to use checkboxes
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.
Specifications
- Checkbox
The checkbox’s input makes the selection visually distinct. - Label
The Checkbox must always contain a label, with the text size matching the base font size for consistency with the body text. Labels can include links and bold text and should be concise, clearly indicating the selected option. - Description (optional)
If additional information about the label is required, a description can be included. - Custom input (optional)
An additional input field can be included within the Checkbox to allow the user to input a custom response.
Component limitations
A Checkbox group should consist of at least 2 checkboxes, with no maximum limit on the number of checkboxes per group.
The Checkbox label will expand to fit longer text while the checkbox itself remains aligned with the first line of the label's text.
Refer to the Checkbox component in Codex Figma.
Types
Depending on the content type, the following types of Checkboxes are available:
- With only label
By default, the Checkbox always includes a label that matches the base font size for consistency. - With description
In some cases, an optional description can be added below the label for additional information. - With custom input
In cases where additional user input is required, an optional custom input field can be added below the label or description.
The custom input within the Radio can include any of the following form components designed to gather user input, including:
- TextInput and TextArea
- Select
- Combobox
- ChipInput
- Lookup
- A combination of more than one input
Note: Groups of Checkboxes, Radios, and Toggle switches are not allowed within this custom input.
Interaction states
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.
Accessibility note
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”. [1] Provide sufficient information in a disabled element's context, so the user can understand what is disabled and how to enable it (if applicable).
Indeterminate state
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. [2]
Best practices
Consider the following recommendations when using checkboxes.
Label’s format
- Accompany the Checkbox with a label that matches the base font size.
- Include a description below the label to provide additional information.
- Use text formatting like bold and italic in the label.
- Include standalone links within the label to provide additional information regarding a specific option when necessary.
- Bold all Checkbox labels, even if a description is included, as this can interfere with the text hierarchy.
- Link the entire Checkbox label as it could cause issues with the selection.
Error state
- Include inline error messages for both individual and groups of checkboxes to inform users and guide them in fixing issues.
- Leave the error checkbox without an accompanying error inline message.
Indeterminate checkbox
- Use the indeterminate checkbox when there is a long list of sub-checkboxes to select.
- Align secondary checkboxes with the label of the indeterminate checkbox.
- Use the indeterminate checkbox when there is a short list of sub-checkboxes.
- Align all checkboxes together when using indeterminate checkboxes.
Inline checkboxes
- Use inline checkboxes, but reserve its use for specific cases to prevent disruptions in the reading flow.
- Use inline checkboxes if there are too many checkboxes per line.
- Use inline checkboxes if there is significant variation in the length of the checkbox labels.
Custom input within the Radio
- Combine 2 different fields within the custom input if needed.
- Nest another group of radios, checkboxes, or toggle switches within the custom input.
- Display the custom input at the end of a Checkbox group whenever possible.
- Disable the custom input unless its corresponding Checkbox is selected.
- Design a layout where multiple Checkboxes include custom inputs visible simultaneously.
- Enable the custom input when its corresponding Checkbox is not selected.
Content
A checkbox lets a reader choose one or more options from a list.
- Create a direct question or a complete sentence to precede the checkboxes. Translatable & Clear
- Split the sentence in the leading label across the choices. Translatable
Keyboard navigation
Key | Function |
---|---|
Tab | It moves the focus to the next Checkbox within a group or to the next interactive element in tab order. |
Shift + Tab | It moves the focus to the previous Checkbox within a group or to the previous interactive element. |
Space | If the focus is placed on the Checkbox, it toggles the Checkbox state. |
References
- Web Content Accessibility Guidelines (WCAG) 2.1 – Success Criterion 1.4.3 Contrast (Minimum)
- MDN:
<input type="checkbox">
Indeterminate state checkboxes
Demos
Open up the browser console to see events emitted on input.
Configurable
Name | Value |
---|---|
Props | |
status | |
disabled | |
indeterminate | |
View | |
Reading direction |
Single checkbox with label and description
Always include label text via the default slot. You can also add description text via the #description
slot.
A single checkbox does not need an inputValue
prop. v-model
is bound to a boolean value: true
for checked, false
for unchecked.
Checkbox value: false
Name | Value |
---|---|
View | |
Reading direction |
Form field
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 isFieldset
to true
, even for a single Checkbox, to ensure accessibility support. This wraps the group in a <fieldset>
element and labels it with an associated <legend>
.
If using a Checkbox or Checkbox group outside of a form, follow the instructions in the next demo.
Checkbox group
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
role="group"
- Connect the group with a label via the
aria-labelledby
attribute
Checkbox group value: [ "checkbox-2", "checkbox-6" ]
Inline checkboxes
Use the inline
prop to get an inline layout.
Indeterminate state
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 v-model
. If 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" ]
With custom input
To add a custom input, use the custom-input
slot to pass in an input like TextInput, TextArea, Select, Combobox, ChipInput, Lookup, or a combination of more than one input.
In the example below, the custom input is always visible but remains disabled until the parent Checkbox is selected. Inside the custom input <div>
, a Field wraps the TextInput to display its own validation message.
Form data: { "options": [ "quickReply", "quickTopic" ], "otherValue": "" }
Vue usage
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).
Props
Prop name | Description | Type | Default |
---|---|---|---|
modelValue | Value of the checkbox or checkbox group. Provided by v-model binding in the parent component. | boolean|( string|number )[] | false |
inputValue | HTML "value" attribute to assign to the input. Required for input groups. | string|number|boolean | false |
name | HTML "name" attribute to assign to the input. | string | null |
disabled | Whether the disabled attribute should be added to the input. | boolean | false |
indeterminate | Whether the indeterminate visual state should be displayed. This is unrelated to the value provided by v-model , and the indeterminate visual state will override the checked or unchecked visual state. | boolean | false |
inline | Whether the component should display inline. By default, display: block is set and a margin exists between sibling components, for a stacked layout. | boolean | false |
hideLabel | Whether the label should be visually hidden. When true, the label will remain accessible to assistive technology. | boolean | false |
status | Validation status of the Checkbox. | ValidationStatusType | 'default' |
Events
Event name | Properties | Description |
---|---|---|
update:modelValue | modelValue boolean|string[]|number[] - The new model value | Emitted when modelValue changes. |
Slots
Name | Description | Bindings |
---|---|---|
default | Label text. | |
description | Short description text. | |
custom-input | Custom input. |
CSS-only version
Markup structure
With description
To add a description below the label:
- Add a
<span>
after the<label>
element with an ID and classcdx-label__description
. Include the description text here. - Add an
aria-describedby
attribute to the<input>
element whose value is the ID of the description
Checkbox group
Native attributes of the <input>
element can be used. For example:
- Add the
checked
attribute to the<input>
element if it should be selected initially. - Add the
disabled
attribute to the<input>
element if it should be disabled.
Note that indeterminate
is not supported in the CSS-only version since it cannot be set without JavaScript.
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<fieldset>
and<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
<div>
withrole="group"
andaria-labelledby
set to the ID of the group label. See an example of this above.
Inline checkboxes
Add the cdx-checkbox--inline
class to the root element to get an inline layout.
With custom input
To add a custom input, add a <div>
element with the cdx-radio__custom-input
class inside a Checkbox. Inside the custom input, add an input like TextInput, TextArea, Select, Combobox, ChipInput, Lookup, or a combination of more than one input.