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.
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
disabledwill prevent Checkbox from receiving keyboard focus or input
In order to ensure proper tab order, wrap a group of related Checkboxes in Fieldset.
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.
size="sm" (16px) and
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.
Checkbox supports subtexts
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.
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.
Component quality checklist
Component is live in Figma, however may not be available for all platforms.
Component is available in code for web and mobile web.
Component is not currently available in code for iOS.
Component is slotted to be built for Android.