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 a merchant 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

checked
boolean | "indeterminate"
Checkbox is selected. `indeterminate` shows a horizontal line in the checkbox
disabled
boolean
Disable input
error
string | ReactElement | string | ReactElement[]
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

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 the merchant 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