We recommending using a Checkbox over a Switch when you have a long list (>3) of toggles.

Props

Component props
Name
Type
Default
id
Required
string
-
onChange
Required
({ event: SyntheticInputEvent<>, checked: boolean }) => void
-
boolean
false
boolean
false
errorMessage
string
-
boolean
false
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.

boolean
false

Indeterminism is
purely presentational - the value of
a checkbox and its indeterminism are independent.

label
string
-
name
string
-
onClick
({ event: SyntheticInputEvent<HTMLInputElement>, checked: boolean }) => void
-
React.Ref<"input">
-

Forward the ref to the underlying input element

"sm" | "md"
"md"

"sm" is 16px & "md" is 24px

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.

What languages would you like to learn?

Example: With Subtext

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

What languages would you like to learn?

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.

Which backgrounds would you like to use?

Example: Error state

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

This checkbox has an error

Example: ref

The underlying input element can be accessed via ref.

Combinations