Checkbox

In a list of one or more items, checkboxes are used when none, one or multiple options can be selected.

Examples

Contents

UsageAnatomyAPIs

Usage

Do

  • Use when none, one, or more options can be selected
  • Allow users to choose any combination of options
  • Use for positive actions (e.g. “I agree” instead of “I disagree”)
  • Use the indeterminate state to indicate that an option is set for some, but not all, child objects in a selection
  • Align options vertically when possible, for ease of reading. Indent child objects
  • Align options horizontally if needed, using existing spacing variables
  • Start label with a verb when possible

Don’t

  • Use when only one option can be selected
  • Use as an on/off control — use a toggle instead
  • Use the indeterminate state to represent a third option

Anatomy

Checkbox anatomy
  • (1) Checkbox
  • (2) Checkbox label
  • (3) Checkbox checked
  • (4) Checkbox indeterminate
  • (5) Disabled checkbox
  • (6) Disabled checkbox checked
  • (7) Disabled checkbox indeterminate
  • (8) Multi-line label

Focus states

Checkbox focus states
  • (1) Focused checkbox without label
  • (2) Focused checkbox with label
  • (3) Focused checkbox with multi-line label

Space and sizing

Checkbox space and sizing
  • (1) Default checkbox and label
  • (2) Focus area / hit target
  • (3) Spacing between multiple checkboxes (8 px)

Related

APIs

ITriStateCheckboxProps

ariaDescribedBy
string
Id of another element which describes this one for screen reader users.
ariaLabel
string
Aria Label for the Checkbox for screen reader users.
ariaLabelledBy
string
Id of another element which labels this one for screen reader users. Defaults to this checkbox's label element.
checkedrequired
IReadonlyObservableValue<boolean | undefined> | boolean | undefined
The checked state of the checkbox.
className
string
Optional class name to add to the checkbox element.
disabledfalse
boolean
If true, the checkbox cannot be interacted with.
excludeFocusZonefalse
boolean
Set to true if you don't want the checkbox's focus managed by a FocusZone.
excludeTabStopfalse
boolean
Set to true to omit setting the tab index to 0.
focuszoneId
string
Additional focuszoneId the checkbox should be included in.
id
string
An id to pass to the checkbox element.
label
React.ReactNode
An optional label to render next to the checkbox.
labelId
string
An id to pass to the label element.
onChange
(event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, checked: boolean | undefined) => void
An optional callback to handle checked state change events.
rolecheckbox
string
The aria role to put on the checkbox element.
tabIndex
number
Sets the tabindex on the button element.
tooltipProps
ITooltipProps
Optional tooltip to show when the checkbox is hovered.
triStatefalse
boolean
A triState checkbox means the checkbox can be in one of three states: 1) Unchecked - checked = false 2) Checked - checked = true 3) Indeterminate - checked = undefined If undefined is passed as the value a checkbox it will show in the indeterminate state, but when changed it will switch back and forth between unchecked and checked. If triState is set to true, the rotation will go through the states in the order above.

ICheckboxProps

ariaDescribedByInherited From: ITriStateCheckboxProps
string
Id of another element which describes this one for screen reader users.
ariaLabelInherited From: ITriStateCheckboxProps
string
Aria Label for the Checkbox for screen reader users.
ariaLabelledByInherited From: ITriStateCheckboxProps
string
Id of another element which labels this one for screen reader users. Defaults to this checkbox's label element.
checkedrequired
IReadonlyObservableValue<boolean> | boolean
The checked state of the checkbox.
classNameInherited From: ITriStateCheckboxProps
string
Optional class name to add to the checkbox element.
disabledfalseInherited From: ITriStateCheckboxProps
boolean
If true, the checkbox cannot be interacted with.
excludeFocusZonefalseInherited From: ITriStateCheckboxProps
boolean
Set to true if you don't want the checkbox's focus managed by a FocusZone.
excludeTabStopfalseInherited From: ITriStateCheckboxProps
boolean
Set to true to omit setting the tab index to 0.
focuszoneIdInherited From: ITriStateCheckboxProps
string
Additional focuszoneId the checkbox should be included in.
idInherited From: ITriStateCheckboxProps
string
An id to pass to the checkbox element.
labelInherited From: ITriStateCheckboxProps
React.ReactNode
An optional label to render next to the checkbox.
labelIdInherited From: ITriStateCheckboxProps
string
An id to pass to the label element.
onChange
(event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, checked: boolean) => void
An optional callback to handle checked state change events.
rolecheckboxInherited From: ITriStateCheckboxProps
string
The aria role to put on the checkbox element.
tabIndexInherited From: ITriStateCheckboxProps
number
Sets the tabindex on the button element.
tooltipPropsInherited From: ITriStateCheckboxProps
ITooltipProps
Optional tooltip to show when the checkbox is hovered.
triStatefalseInherited From: ITriStateCheckboxProps
boolean
A triState checkbox means the checkbox can be in one of three states: 1) Unchecked - checked = false 2) Checked - checked = true 3) Indeterminate - checked = undefined If undefined is passed as the value a checkbox it will show in the indeterminate state, but when changed it will switch back and forth between unchecked and checked. If triState is set to true, the rotation will go through the states in the order above.