<Checkbox /> component renders a single checkbox element on the page, with no accompanying label. It is generally used to construct higher-order components like the
<FieldCheckbox />. If you are building a form, you probably want to use
<FieldCheckbox /> instead as it provides label support.
<Checkbox /> component can be rendered in three different states: checked, unchecked, and "mixed". In addition to the standard boolean, rendering a "mixed" value can be used to indicate that only a fraction of related sub-options have been selected.
Note: The "mixed" value is only available to the
checked property and not available to
Checkbox accepts an onChange callback, which can be used for toggling checkbox state.
Advanced Use: Controlling parent/child mixed states
Using a mixed state checkbox can be used to establish a parent and child relationship between multiple options. This is an advanced use and will likely require bespoke state management. In an attempt to facilitate a standard UX, we've create a hook and state pattern.
This may not be sufficient for your own use case, but it may provide a good starting point and reference for how it should work.
Name and ID
A name and ID can be specified in the
<Checkbox /> component. Names are important if the checkbox is used in the context of a form, in which case a name is required for the value of the checkbox to be captured.
Use the disable property to gray out the checkbox, making it unclickable.
Checkbox will ignore user-actions on a
Checkbox with the
readOnly property enabled, similar to
disabled but without greying out the option.
NOTE: In HTML specifying
readonly on only prevents changes to
value attribute of the checkbox and therefore allowing the user to still check and uncheck the checkbox.
In most cases we emulate the HTML specification where it has an existing decision or feature. However, the specification's behavior around checkboxes with a
readonly attribute is rather unintuitive.
- Individual checkboxes must have an onscreen
- Groups of checkboxes must have group label, using the
- See related ARIA attributes
- Always include an unique id on the checkbox element so it can be referenced by a label
- Use clear and descriptive labels that avoid ambiguity.
- Always include a
forproperty that matches the checkbox
- Groups of checkboxes must be wrapped in a
<legend>that describes the group. We recommend utilizing
CheckboxGroupfor these use cases.
- checkboxes with
:focusshould have an outline and/or a visible change to show it has focus.
- If the checkbox with
:focushas an error, the error should be read by a screen reader
- If checkbox has focus the
SPACEkey should toggle the state.
- If checkbox has focus the
Enterkey should submit the form.
- If checkbox has focus,
SHIFT+TABshould move focus to next focusable element.
Related Aria Attributes
Use this to provide a detailed descriptions of a field that contains errors.
This would announce "Approve, unchecked checkbox. Confirm you approve these changes."