Checkbox is used for multiple choice selection. They are independent of each other in a list, and therefore, different from RadioButton, one selection does not affect other checkboxes in the same list.

Web:

iOS:

Android:

A11y:

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
-

Indicates whether or not Checkbox is checked. See the state variant to learn more.

disabled
boolean
-

Indicates whether or not Checkbox is disabled. Disabled Checkboxes do not respond to mouse events and cannot be reached by the keyboard. See the state variant to learn more.

errorMessage
string
-

Displays an error message and error state. See the accessibility section to learn more.

helperText
string
-

Optional description for Checkbox, used to provide more detail about an option. See the with helperText variant to learn more.

image
React.Node
-

An optional Image can be supplied to add an image to each Checkbox. See the with Image variant to learn more.

indeterminate
boolean
-

Indicates a state that is neither checked nor unchecked. See the state variant to learn more.

label
string
-

The label for the input. Be sure to localize the text. See the accessibility section to learn more.

labelDisplay
"visible" | "hidden"
-

Whether the label should be visible or not. If hidden, the label is still available for screen reader users, but does not appear visually. See the label visibility variant for more info.

name
string
-

A unique name for the input used to reference form data after it’s submitted. If the name attribute is not specified then the data of the checkbox would not be sent in the form submission.

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"
-

Determines the Checkbox size: sm = 16px, md = 24px. See the size variant to learn more.

Usage guidelines

When to use
  • In a list, form or a Table, to present users with multiple, related options where more than one option can be selected. Users must be able to select all, none or some of the presented options.
  • In a Form, along with a TextField, or other spaces that are too small for a Switch
  • When selection doesn’t take immediate effect and requires form submission
When not to use
  • Situations where users can only choose one out of multiple, related options. Use RadioGroup instead.
  • When a selection takes immediate effect, especially on mobile. Use Switch instead.
  • When visually, it’s hard to tell that a checkbox turns something on or off. Use Switch instead.

Best practices

Do

Use checkboxes for multi-selection of related list items

Don't

Use checkboxes for one selection. Use RadioGroup instead.

Do

Use a single Checkbox in forms where the selection only takes effect after submitting the form

Don't

Use a Checkbox to turn a state on and off with immediate effect. Use Switch instead.

Do

Keep labels and legends clear and brief to avoid too many lines of text that are hard to scan and slow the user down. If clarification is needed, use info Tooltips or helperText.

Don't

Use lengthy text that truncates and doesn’t offer clear instructions for what you are expected to select

Do

Use Checkbox at the start of a table row to make it clear which rows are multi-selectable

Don't

Use numerous checkboxes in table rows that make it hard to tell what items apply to multi-select actions

Do

Use vertical alignment of multi-line labels so that the first line is vertically centered with the checkbox input

Don't

Vertically center checkbox inputs with their respective custom labels

Accessibility

Labels

Checkboxes should have labels that can be read by screen readers, and that can be clicked or tapped to make it easier for users to select and deselect options. Therefore, make sure to supply the label prop. If that’s not possible, make sure your standalone Label has an htmlFor prop that matches the id of the checkbox. Test that a checkbox and label are properly connected by clicking or tapping on the label and confirming that it activates the checkbox next to it.

If Checkbox is labeled by content elsewhere on the page, or a more complex label is needed, the labelDisplay prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen. See the Label visibility example for more detail.

Legends

All groups of related Checkboxes should have a legend, which is provided by wrapping them in Fieldset component.

Keyboard navigation

Checkbox has conventional keyboard support.

  • Users relying on the keyboard expect to move focus to each Checkbox by using the tab key or shift+tab when moving backwards
  • Setting disabled will prevent Checkbox from receiving keyboard focus or input

In order to ensure proper tab order, wrap a group of related Checkboxes in Fieldset.

Error message

Checkbox’s error state displays an error-themed color border. Checkbox must always show an error message to indicate error status to ensure color is not the only indicator of status or information. Use errorMessage prop to display the appropriate error message that helps the user resolve the problem. Error messages should be clear, direct and conversational. For an example, see Writing.

Localization

Be sure to localize label and any helperText. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.

Variants

Size

Checkbox has size="sm" (16px) and size='md' (24px).

State

Checkbox has unchecked, checked, error, indeterminate and disabled states.

Indeterminate is 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.

With helperText

Checkbox supports helperText

With Image

Checkbox supports images. When including images, you can use the helperText property to clearly describe the information being presented by the image, or use the image's alt text to provide more context.

Spacing is already accounted for; simply specify the width and height.

Label visibility

In some cases, the label for a Checkbox is represented in a different way visually, as demonstrated below. In these instances, you can set labelDisplay="hidden" to ensure Checkbox is properly labeled for screen readers while using a different element to represent the label visually.

Writing

Do
  • Be clear and brief with checkbox labels so they are easily scanned
Don't
  • Include lengthy text labels that make it hard for a user to scan a list of choices

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Partially ready
Component is live in Figma, however may not be available for all platforms.
Responsive Web
Ready
Component is available in code for web and mobile web.
iOS
Component is not currently available in code for iOS.
Android
Planned
Component is slotted to be built for Android.

RadioGroup
Use when presenting a user with a list of choices for which there can only be one selection.

Switch
Use for single-cell options that can be turned on or off. Examples include a list of settings that take effect immediately without having to confirm Form submission.

Fieldset
Use to group a list of related Checkboxes with a legend that describes the list.