Use Checkbox instead of Switch when displaying 3 or more toggle inputs.

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier for the input.

onChange
Required
({| event: SyntheticInputEvent<HTMLInputElement>, checked: boolean |}) => void
-

Callback triggered when the state of the input changes.

checked
boolean
false

Is the element currently checked?

disabled
boolean
false

Is the element currently disabled? Disabled Checkboxes do not respond to mouse events and cannot be reached by the keyboard.

errorMessage
string
-

Displays an error message and error state. Be sure the error message helps the user resolve the problem.

hasError
boolean
false

This field is deprecated and will be removed soon. Please do not use.

image
React.Node
-

An optional Image component can be supplied to add an image to each checkbox. Spacing is already accounted for; simply specify the width and height.

indeterminate
boolean
false

Used to indicate a state that is neither checked nor unchecked — e.g. a "Select all" checkbox when not all items are selected or unselected.
Indeterminism is purely presentational - the value of a checkbox and its indeterminism are independent.

label
string
-

The label for the input. Be sure to localize the text.

name
string
-

A unique name for the input.

onClick
({| event: SyntheticInputEvent<HTMLInputElement>, checked: boolean |}) => void
-

Callback triggered when the user clicks on the input.

ref
React.Element<"input">
-

Ref that is forwarded to the underlying input element.

size
"sm" | "md"
"md"

sm: 16px, md: 24px

subtext
string
-

Optional description for the checkbox, used to provide more detail about an option.

Usage guidelines

When to Use
  • Presenting users with a list of multiple, related options where users can select all, some, or none of the options. With Checkboxes, users can select more than one option.
  • Presenting users with a single option that can be selected or not.
When Not to Use
  • Situations where users can only choose one out of multiple, related options. Use RadioButtons instead.
  • When a selection takes immediate effect, especially on mobile. Use Switch instead.

Example

Example: Group

Here is an example of an accessible group of checkboxes. When creating a group of Checkboxes, be sure to wrap them in a Fieldset.

Example: With Subtext

Here is an example of a group of checkboxes with additional subtext applied.

Example: With Images

Here is an example of a group of checkboxes with images included. When including images, you can use the subtext property to clearly describe the information being presented by the image, or use the image's alt text to provide more context.

Example: Error state

Here is an example of a checkbox showing an error message.

Example: ref

The underlying input element can be accessed via ref.

Combinations