Components menu
  2. components
  3. forms
  4. checkbox

Checkbox

Checkboxes are most commonly used to give merchants a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have merchants indicate they agree to specific terms and services.

Examples

Use in forms to toggle the state of something on or off. Default checkboxes can appear in two states: selected and disabled, or unselected.

Drag to resize example

Props

ariaDescribedBy
string
Indicates the ID of the element that describes the checkbox
checked
boolean | "indeterminate"
Checkbox is selected. `indeterminate` shows a horizontal line in the checkbox
disabled
boolean
Disable input
error
string | ReactElement | (string | ReactElement)[] | boolean
Display an error message
helpText
React.ReactNode
Additional text to aide in use
id
string
ID for form input
labelRequired
React.ReactNode
Label for the checkbox
labelHidden
boolean
Visually hide the label
name
string
Name for form input
value
string
Value for form input
onBlur
() => void
Callback when focus is removed
onChange
(newChecked: boolean, id: string) => void
Callback when checkbox is toggled
onFocus
() => void
Callback when checkbox is focussed

Accessibility

Screen readers convey the state of the checkbox automatically.

  • Use the disabled prop to apply the HTML disabled attribute to the checkbox <input>. This prevents merchants from being able to interact with the checkbox, and conveys its inactive state to assistive technologies.
  • Use the id prop to provide a unique id attribute value for the checkbox. If an id isn’t provided, then the component generates one. All checkboxes must have unique id values to work correctly with assistive technologies.
  • Setting checked="indeterminate" conveys the state of the checkbox using aria-checked="mixed".

Labeling

  • The required label prop conveys the purpose of the checkbox to all merchants
  • Use the labelHidden prop to visually hide the label but make it available to assistive technologies
  • When you provide help text via the helpText prop or an inline error message via the error prop, the help or error content is conveyed to screen reader users with the aria-describedby attribute

Keyboard support

  • Move focus to each checkbox using the tab key (or shift + tab when tabbing backwards)
  • To interact with the checkbox when it has keyboard focus, press the space key

Default checkboxes

Use in forms to toggle the state of something on or off. Default checkboxes can appear in two states: selected and disabled, or unselected.

Default checkbox on Android

Accessibility

See Material Design and development documentation about accessibility for Android:

Default checkboxes

Use in forms to toggle the state of something on or off. Default checkboxes can appear in two states: selected and disabled, or unselected.

Default checkbox on iOS

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Best practices

Checkboxes should:

  • Work independently from each other: selecting one checkbox shouldn’t change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection of multiple items.
  • Be framed positively: for example, Turn on notifications instead of Turn off notifications
  • Always have a label when being used to toggling a setting on or off
  • Be listed according to a logical order, whether it’s alphabetical, numerical, time-based, or some other clear system.
  • Link to more information or include a subtitle as required to provide more explanation. Don’t rely on tooltips to explain a checkbox.

Content guidelines

Lists with checkboxes

Lists that use checkboxes should:

  • Start with a capital letter

Do

  • Option 1
  • Option 2
  • Option 3

Don’t

  • option 1
  • option 2
  • option 3
  • Not use commas or semicolons at the end of each line

Do

  • Red
  • Yellow
  • Blue

Don’t

  • Red;
  • Yellow;
  • Blue.
  • In the rare case where the checkbox is asking merchants to agree to terms or service, use the first person

Do

I agree to the Terms of Service.

Don’t

You agree to the Terms of Service

View source on GitHub · Preview examples in Chromatic