Checkbox
Checkboxes allow a user to select zero, one, or multiple values from a predefined list of 7 or less options.
Anatomy
- Form Field Label: The Form Field Label describes all of the checkboxes in the checkbox group and functions as a header.
- Checkbox: Checkboxes are aligned close to its label or by itself in some cases.
- Checkbox Label: Checkbox Labels give information about what to select or unselect.
Usage Guidance
- The Form Field Label can be positioned in two places; above or left of the checkbox group for LTR languages. Form Field Labels are aligned to the right of the checkbox group for RTL languages.
- Checkbox Labels are positioned to the right of Checkboxes for LTR languages or to the left of Checkboxes for RTL languages.
- Checkboxes allow users to select one or many options. Selected options are shown as a white check with blue fill. Clicking it again will deselect the choice.
- Each Checkbox is tied to a distinct value. Label for each selection should describe the choice and be kept as concise as possible. See these guidelines for more information on writing Checkbox labels.
When to Use
- Use Checkboxes when the user is allowed to select 0, 1, or multiple values from a predefined list of 7 or less options.
When to Use Something Else
- Consider using a Switch if the only options are yes or no.
- For a list between 2 to 7 predefined options, consider using Radio Buttons or a Select to select one option.
- Use a Prompt when the number of list items is large or unknown. Prompts have search capabilities and folders which provide users with the means to browse options. Prompts can be configured to support single or multi-select.
Examples
These examples are using FormField from Preview. We can plan to promote this component to the Main package in a future major version.
View Form Field (Preview) DocumentationBasic Example
Checkbox may be used on its own without Form Field since it
includes a <label>
with a for
attribute referencing the underlying <input type="checkbox">
element.
Inverse
Checkbox with inverse variation
Disabled
Set the disabled
prop of the Checkbox to prevent users from interacting with it.
Indeterminate
Set the indeterminate
prop of the Checkbox to true
to indicate the Checkbox is neither checked
nor unchecked.
A common use case for an indeterminate Checkbox is when the value of a parent Checkbox is dependent on a number of child Checkboxes. The parent Checkbox is set to the indeterminate state if some (but not all) of its children are checked.
Ref Forwarding
Checkbox supports ref forwarding. It will forward
ref
to its underlying <input type="checkbox">
element.
Label Position Horizontal
Set the orientation
prop of the Form Field to designate the position of the label relative to the
input component. By default, the orientation will be set to vertical
.
Required
Set the required
prop of a wrapping Form Field to true
to indicate that the field is required.
Labels for required fields are suffixed by a red asterisk.
Error States
Set the error
prop of the wrapping Form Field to FormField.ErrorType.Alert
or
FormField.ErrorType.Error
to set the Checkbox to the Alert or Error state, respectively. You will
also need to set the hintId
and hintText
props on the Form Field to meet accessibility
standards. You may wish to omit the label
prop on the Form Field given that Checkbox already
includes a label.
The error
prop may be applied directly to the Checkbox with a value of Checkbox.ErrorType.Alert
or Checkbox.ErrorType.Error
if Form Field is not being used.
Alert
You must agree to the terms before proceeding
Error
You must agree to the terms before proceeding
Custom Styles
Checkbox supports custom styling via the cs
prop. For more information, check our
"How To Customize Styles".
Component API
Checkbox
Props
Props extend from input. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
checked | boolean | If true, set the Checkbox to the checked state. | false |
disabled | boolean | If true, set the Checkbox to the disabled state. | false |
error |
| The type of error associated with the Checkbox (if applicable). | |
id | string | The HTML |
|
indeterminate | boolean | If true, set the Checkbox to an indeterminate state. Use this on a Checkbox with nested child Checkboxes to denote that some (but not all) child Checkboxes are checked. | false |
label | string | The text of the Checkbox label. | '' |
onChange | (e: <>) => void | The function called when the Checkbox state changes. | |
value | string | The value of the Checkbox. | |
variant | 'inverse' | undefined | The variant for the checkbox | |
cs |
| The
| |
children | React.ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref<R = input> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
Checkbox.ErrorType
Basic type information:
ErrorType
Specifications
Given | When | Then |
---|---|---|
given the 'Basic' story is rendered |
| |
given the 'Basic' story is rendered |
|
|
given the 'Alert' story is rendered |
| |
given the 'Alert' story is rendered |
|
|
given the 'Error' story is rendered |
| |
given the 'Error' story is rendered |
|
|
given the 'Disabled' story is rendered |
| |
given the 'Disabled' story is rendered |
| |
given the 'Indeterminate' story is rendered |
| |
given the 'Indeterminate' story is rendered |
|
Accessibility Guidelines
How Checkboxes Impact the Accessible Experience
Checkboxes used to present a group of choices require context, such as, selecting your pizza toppings. Designing a clear legend and building the context of the group is a key foundation for accessible checkboxes when users cannot visually perceive the layout.
Keyboard Interaction
Each Checkbox must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.
Checkboxes must support the following keyboard interactions:
Tab
: focus a checkboxSpace
: select/unselect a focused checkbox
Screen Reader Interaction
Checkboxes must communicate the following to users:
- The name (Form Field Label) of the checkbox grouping, if applicable
- The accessible name (label) of the focused checkbox
- Whether the checkbox is selected or unselected
Design Annotations Needed
- Write the context (legend) of the checkbox grouping, if applicable.
Implementation Markup Needed
- Checkbox must have a
required
attribute when the Checkbox is required for submission. - Checkbox must have an
aria-invalid=”true”
attribute when it has an error condition. - [Included in component] A
<label>
element is required with afor
attribute referencing the uniqueid
value of the associated Checkbox. - [Included in component] A
<fieldset>
element establishes the group of related Checkboxes. The child<legend>
element describes the context of the grouping. - [Included in component] A
disabled
attribute is set when the Checkbox is disabled.
Content Guidelines
- Form Field Labels are written in title case.
- The Checkbox Label for each individual selection are kept as concise as possible and written in sentence case.
- When writing Checkbox Labels, refer to the Checkboxes section of the Content Style Guide.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for.
FAQ Section