The checkbox role is used for checkable interactive controls. Elements containing role="checkbox"
must also include the aria-checked
attribute to expose the checkbox's state to assistive technology.
<span role="checkbox" aria-checked="false" tabindex="0" aria-labelledby="chk1-label"> </span> <label id="chk1-label">Remember my preferences</label>
The first rule of ARIA is if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding ARIA. Instead use the native HTML checkbox of <input type="checkbox">
, which natively provides all the functionality required:
<input type="checkbox" id="chk1-label"> <label for="chk1-label">Remember my preferences</label>
Description
The native HTML checkbox form control can only have two checked states ("checked" or "not checked"), with an indeterminate state settable via JavaScript. Similarly, an element with role="checkbox"
can expose three states through the aria-checked
attribute: true
, false
, or mixed
.
Since a checkbox is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the tabindex
attribute to change this. The expected keyboard shortcut for activating a checkbox is the Space key.
The developer is required to change the value of the aria-checked
attribute dynamically when the checkbox is activated.
Associated WAI-ARIA Roles, States, and Properties
- aria-checked
-
The value of
aria-checked
defines the state of a checkbox. This attribute has one of three possible values:true
The checkbox is checked
false
The checkbox is not checked
mixed
The checkbox is partially checked, or indeterminate - tabindex="0"
- Used to make it focusable so the assistive technology user can tab to it and start reading right away.
Keyboard interactions
Key | Function |
---|---|
Space | Activates the checkbox |
Required JavaScript
Required event handlers
- onclick
- Handle mouse clicks that will change the state of the checkbox by changing the value of the
aria-checked
attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user - onKeyPress
- Handle the case where the user presses the Space key to change the state of the checkbox by changing the value of the
aria-checked
attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user
Examples
The following example creates a simple checkbox element using CSS and JavaScript to handle the checked or unchecked status of the element.
HTML
<span role="checkbox" id="chkPref" aria-checked="false" onclick="changeCheckbox()" onKeyPress="changeCheckbox()" tabindex="0" aria-labelledby="chk1-label"></span> <label id="chk1-label" onclick="changeCheckbox()" onKeyPress="changeCheckbox()">Remember my preferences</label>
CSS
[role="checkbox"] { padding:5px; } [aria-checked="true"]::before { content: "[x]"; } [aria-checked="false"]::before { content: "[ ]"; }
JavaScript
function changeCheckbox(event) { let item = document.getElementById('chkPref'); switch(item.getAttribute('aria-checked')) { case "true": item.setAttribute('aria-checked', "false"); break; case "false": item.setAttribute('aria-checked', "true"); break; } }
Accessibility concerns
When the checkbox
role is added to an element, the user agent should do the following:
- Expose the element as having a checkbox role in the operating system's accessibility API.
- When the aria-checked value changes, send an accessible state changed event.
Assistive technology products should do the following:
- Screen readers should announce the element as a checkbox, and optionally provide instructions on how to activate it.
Best practices
The first rule of ARIA is: if a native HTML element or attribute has the semantics and behavior you require, use it instead of re-purposing an element and adding an ARIA role, state or property to make it accessible. As such, it is recommended to use the native HTML checkbox using form control instead of recreating a checkbox's functionality with JavaScript and ARIA.