Checkboxes are small, square decision making components used for optional choice or multi-selectable lists.
Overview
Checkboxes are designed to be used for "yes" and "no" interactions, or interactions where a choice is optional. Use Checkbox for interactions when a multi-select list is needed.
For single choice interactions, please consider Radio Button or Segmented Control. The key difference between a Checkbox and Radio is Radios must always have something active, whereas the Checkbox utility is optional.
For "on" and "off" interactions, also consider Switch.
Usage
- "Yes" and "no" interactions
- Boolean
- Workflows where multi-selection is needed
- Form elements
Sample
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Space | Toggle the component's checked value. |
Space | Toggle component's checked value. |
Tab | Moves focus in and out of component. |
Tab and Shift | Moves focus in and out of component. |
Writing and copy
Keep labels for Checkboxes simple and succinct. Do not use contractions, such as "you're", "aren't", "can't", and "haven't" for Checkbox labels in order to reduce confusion. Avoid writing Checkbox text as a question.
A label for a Checkbox can denote its action as additive or subtractive. For example:
- Save info for later (additive)
- Invite me to the user testing group (additive)
- Delete locally after upload (subtractive)
- Remove user metadata (subtractive)
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| checked | checked | When present, the component is checked. | boolean | false |
| disabled | disabled | When present, interaction is prevented and the component is displayed with lower opacity. | boolean | false |
| form | form | The id of the form that will be associated with the component.
When not set, the component will be associated with its ancestor form element, if any. | string | |
| indeterminate | indeterminate | When present, the component is initially indeterminate, which is independent from its checked value.
The state is visual only, and can look different across browsers. | boolean | false |
| label | label | Accessible name for the component. | string | |
| labelText | label-text | When provided, displays label text on the component. | string | |
| messageOverrides | Use this property to override individual strings used by the component. | Record<string, unknown> | ||
| name | name | Specifies the name of the component.
Required to pass the component's value on form submission. | string | |
| required | required | When present and the component resides in a form, the component must have a value in order for the form to submit. | boolean | false |
| scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
| status | status | Specifies the status of the input field, which determines message and icons. | "idle" | "invalid" | "valid" | "idle" |
| validity | The current validation state of the component. | {
valid: boolean;
badInput: boolean;
customError: boolean;
patternMismatch: boolean;
rangeOverflow: boolean;
rangeUnderflow: boolean;
stepMismatch: boolean;
tooLong: boolean;
tooShort: boolean;
typeMismatch: boolean;
valueMissing: boolean;
} | ||
| value | value | The component's value. | any |
Styles
| Name | Description |
|---|---|
| --calcite-checkbox-size | Specifies the component's height and width. |
| --calcite-checkbox-border-color | Specifies the component's color. |
| --calcite-checkbox-border-color-hover | Specifies the component's color when hovered. |
| --calcite-checkbox-border-color-press | Specifies the component's color when pressed. |
| --calcite-checkbox-icon-color | Specifies the component's icon color. |
Events
| Name | Description | Behavior |
|---|---|---|
| calciteCheckboxChange | Fires when the component's checked status changes. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
| setFocus | Sets focus on the component. | setFocus(options?: FocusOptions): Promise<void> |