- Components
- Inputs
- Checkbox
Checkbox
Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
Installation
Install the following dependencies:
Copy and paste the following code into your project.
Update the import paths to match your project setup.
Usage
Use checkbox to allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
Options
Variant
Use the variant prop to control the visual style of the checkbox.
Indeterminate
A checkbox can be in an indeterminate state, controlled using the isIndeterminate prop.
Disabled
Use the isDisabled prop to disable the checkbox.
Read only
The isReadOnly prop makes the selection immutable. Unlike isDisabled, the Checkbox remains focusable.
Uncontrolled
The defaultSelected prop can be used to set the default state.
Controlled
Use the isSelected and onChange props to control the value of the input.
API Reference
Prop | Type | Default | Description |
---|---|---|---|
variant | "default" | "card" | "default" | The visual style of the checkbox group. |
inputRef | MutableRefObject<HTMLInputElement> | - | A ref for the HTML input element. |
isIndeterminate | boolean | - | Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction. |
defaultSelected | boolean | - | Whether the element should be selected (uncontrolled). |
isSelected | boolean | - | Whether the element should be selected (controlled). |
value | string | - | The value of the input element, used when submitting an HTML form. |
isDisabled | boolean | - | Whether the input is disabled. |
isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
isRequired | boolean | - | Whether user input is required on the input before form submission. |
isInvalid | boolean | - | Whether the input value is invalid. |
validate | (value: boolean) => ValidationError| true| null| undefined | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
autoFocus | boolean | - | Whether the element should receive focus on render. |
name | string | - | The name of the input element, used when submitting an HTML |
validationBehavior | 'native' | 'aria' | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
children | ReactNode | (values: CheckboxRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
className | string | - | The CSS className for the element. |
style | CSSProperties | (values: CheckboxRenderProps & {defaultStyle: CSSProperties}) => CSSProperties | - | The inline style for the element. A function may be provided to compute the style based on component state. |
Event | Type | Description |
---|---|---|
onChange | (isSelected: boolean) => void | Handler that is called when the element's selection state changes. |
onFocus | (e: FocusEvent<Target>) => void | Handler that is called when the element receives focus. |
onBlur | (e: FocusEvent<Target>) => void | Handler that is called when the element loses focus. |
onFocusChange | (isFocused: boolean) => void | Handler that is called when the element's focus status changes. |
onKeyDown | (e: KeyboardEvent) => void | Handler that is called when a key is pressed. |
onKeyUp | (e: KeyboardEvent) => void | Handler that is called when a key is released. |
onHoverStart | (e: HoverEvent) => void | Handler that is called when a hover interaction starts. |
onHoverEnd | (e: HoverEvent) => void | Handler that is called when a hover interaction ends. |
onHoverChange | (isHovering: boolean) => void | Handler that is called when the hover state changes. |
Data attribute | Description |
---|---|
[data-selected] | Whether the checkbox is selected. |
[data-indeterminate] | Whether the checkbox is indeterminate. |
[data-hovered] | Whether the checkbox is currently hovered with a mouse. |
[data-pressed] | Whether the checkbox is currently in a pressed state. |
[data-focused] | Whether the checkbox is focused, either via a mouse or keyboard. |
[data-focus-visible] | Whether the checkbox is keyboard focused. |
[data-disabled] | Whether the checkbox is disabled. |
[data-readonly] | Whether the checkbox is read only. |
[data-invalid] | Whether the checkbox invalid. |
[data-required] | Whether the checkbox is required. |
Accessibility
Keyboard interactions
Key | Description |
---|---|
Space | Toggles the checkbox between selected and not selected |