Checkbox
Checkboxes are selection controls that allow users select one or multiple items.

Other available selection types:

Usage

Checkbox component works like native checkboxes, which means you can either use its value property to define what's going to be passed to the form when it's checked.

Like all native inputs in React, Checkbox supports controlled and uncontrolled variant. It becomes controlled when you use checked property, which means that you have to control it with your state. Uncontrolled variant is used when you use defaultChecked property, which lets you define the default state but let the browser control the rest.

Note: You shouldn't be using both properties at the same time and React will throw warning if that happens.

States

If there is an error related to the checkbox field, you can use an hasError flag.

In order to make Checkbox non-interactive, you can use disabled flag. Like in native checkbox, it will prevent onChange handler from triggering.

Note: Disabled state fades the component content. Even though it's not required to have regular contrast ratio for disabled elements, still make sure it's not used over gray backgrounds.

When a checkbox is used as a parent field for another list of items, indeterminate flag can be used to display that some items in the children list are selected. indeterminate state is controlled by the JS API of the inputs, so by default it will check the Checkbox on the moment you click it. If you want to avoid that – use controlled variant of the component.

Composition

In products, we are sometimes working with checkbox groups to select multiple values from a list of options. CheckboxGroup handles this kind of interaction and lets you work with multiple checkboxes as with an array of values. At the same time it doesn't enforce any specific layout so you're free to use any layout components together with it.

As you can see, name and onChange properties apply to all Checkbox components within its scope. By selecting a specific Checkbox, you will get an array with the selected value logged into console.

Same way as Checkbox can define it's checked value, CheckboxGroup supports value and defaultValue to control the selection in the options list.

If you need to provide a label for a group of checkboxes, you can use the FormControl utility with group flag turned on.

Favorite animals:

Most of the time products are using simple checkbox with text labels but sometimes you might want to display rich content and make it selectable. Checkbox and CheckboxGroup support this use case with its composition approach, as CheckboxGroup supports any layout components and Checkbox renders any children as its content.

Accessibility

When using Checkbox without children – make sure to wrap it with a label element.

Properties

Checkbox properties:

NameTypeDefaultRequiredComment
idstring-falseCustom id
childrenReactNode-false
onChange({ event, name, value }) => {}-falseChange handler
namestring-true
valuestring-false
checkedboolean, null-falseControlled checked state
defaultCheckedboolean-falseUncontrolled checked state
disabledboolean-false
hasErrorboolean-false
indeterminateboolean-false
classNamestring-falseclassName for the root element
attributesobject-falseAttributes for the root element
inputAttributesobject-falseAttributes for the input element

CheckboxGroup properties:

NameTypeDefaultRequiredComment
childrenReactNode-false
onChange({ event, name, value }) => {}-falseChange handler
namestring-true
valuestring[]-false
defaultValuestring[]-false
disabledboolean-false
hasErrorboolean-false