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 true, the component is checked. | boolean | false |
| disabled | disabled | When true, 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 true, 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 | |
| name | name | Specifies the name of the component.
Required to pass the component's value on form submission. | string | |
| required | required | When true 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-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(): Promise<void> |