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.


Component props

A unique identifier for the input.

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

Callback triggered when the state of the input changes.


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


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.


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


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


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


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


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

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


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.

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

Callback triggered when the user clicks on the input.


Ref that is forwarded to the underlying input element.

"sm" | "md"

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


Optional description for Checkbox, used to provide more detail about an option. See the with subtext 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 RadioButton 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


Use checkboxes for multi-selection of related list items


Use checkboxes for one selection. Use RadioButton instead.


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


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


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 subtext.


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


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


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



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.


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.


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



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


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 subtext

Checkbox supports subtexts

With Image

Checkbox supports images. 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.

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.


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

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

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.

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