Checkbox

Checkboxes are selection controls that allow users select one or multiple items.
Supports indeterminate state
Full keyboard navigation
Can be controlled and uncontrolled
Supports checkbox groups with custom rendering
Similar components:
SelectSwitchRadio


Usage

Checkbox component works like native checkboxes, which means you can use its value property to define what's going to be passed to the form when submitted. Note that it's required to pass a name to the Checkbox.

Like all native inputs in React, Checkbox supports controlled and uncontrolled options. 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 a warning if that happens.

States

If there is an error related to the checkbox field, you can use a 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, make sure it's not used on gray background.

When a checkbox is used as a parent field for another checkbox group, indeterminate flag can be used to display that some items in that group are selected. indeterminate state is controlled by the JS API of the inputs, so by default it will check the Checkbox at the moment you click on 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 represented 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. That will resolve FormControl html tags correctly for a group of input fields.

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
Previous