Thecheckbox role is for checkable interactive controls. Elements containingrole="checkbox" must also include thearia-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>Remember my preferences</label>

<input type="checkbox" name="RememberPreferences" /><label for="chk1-label">Remember my preferences</label>

Description

The native HTML checkbox (<input type="checkbox">) form control had two states ("checked" or "not checked"), with anindeterminate state settable via JavaScript. Similarly, an element withrole="checkbox" can expose three states through thearia-checked attribute:true,false, ormixed.

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 thetabindex attribute to change this. The expected keyboard shortcut for activating a checkbox is theSpace key.

The developer is required to change the value of thearia-checked attribute dynamically when the checkbox is activated.

All descendants are presentational

There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in acheckbox. To deal with this limitation, browsers, automatically apply rolepresentation to all descendant elements of anycheckbox element as it is a role that does not support semantic children.

For example, consider the followingcheckbox element, which contains a heading.

<div role="checkbox"><h6>Name of my checkbox</h6></div>

Because descendants ofcheckbox are presentational, the following code is equivalent:

<div role="checkbox"><h6 role="presentation">Name of my checkbox</h6></div>

From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in theaccessibility tree:

<div role="checkbox">Name of my checkbox</div>

Associated WAI-ARIA roles, states, and properties

aria-checked

The value ofaria-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

Required JavaScript

Required event handlers

onclick

Handle mouse clicks on both the checkbox and the associated label that will change the state of the checkbox by changing the value of thearia-checked attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user

onKeyDown

Handle the case where the user presses theSpace key to change the state of the checkbox by changing the value of thearia-checked attribute and the appearance of the checkbox so it appears checked or unchecked to the sighted user

Examples

The following example creates an otherwise non-semantic checkbox element using CSS and JavaScript to handle the checked or unchecked status of the element.

HTML

<span  role="checkbox"   aria-checked="false"  tabindex="0"  aria-labelledby="chk1-label"></span><label>Remember my preferences</label>

CSS

[role="checkbox"] {  padding: 5px;}[role="checkbox"]:focus {  border: 2px solid #0198e1;}[aria-checked="true"]::before {  content: "[x]";}[aria-checked="false"]::before {  content: "[ ]";}

JavaScript

const item = document.getElementById("chkPref");const label = document.getElementById("chk1-label");function changeCheckbox(code) {  const checked = item.getAttribute("aria-checked");  if (code && code !== "Space") {    return;  }  if (checked === "true") {    item.setAttribute("aria-checked", "false");  } else {    item.setAttribute("aria-checked", "true");  }}item.addEventListener("keydown", (event) => {  changeCheckbox(event.code);});label.addEventListener("keydown", (event) => {  changeCheckbox(event.code);});item.addEventListener("click", changeCheckbox);label.addEventListener("click", changeCheckbox);

Accessibility concerns

When thecheckbox role is added to an element, the user agent should do the following:

• Expose the element as having acheckbox role in the operating system's accessibility API.
• When thearia-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.

People implementing checkboxes should do the following:

• Ensure that the checkbox can be reached and interacted with by both keyboard controls and clicks
• Keep thearia-checked attribute up to date following user interactions
• Provide styles that indicate when the checkbox has focus

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 nativeHTML checkbox using form control instead of recreating a checkbox's functionality with JavaScript and ARIA.

See also

• <input type="checkbox">
• ARIA:radio role
• ARIA:menuitem role
• ARIA:menuitemcheckbox role
• ARIA:menuitemradio role
• ARIA:switch role
• ARIA:option role