JavaScript Element ariaChecked Property

What You’ll Learn

Element.ariaChecked is an instance property that reflects the aria-checked attribute. Learn the true, mixed, false, and undefined values, when to prefer a native checkbox, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

Custom checkboxes, radios, and menu items need a clear checked state for assistive technologies. That state is what aria-checked communicates.

The DOM property ariaChecked lets you read and update the same value from JavaScript—useful when you toggle a custom widget with script.

const el = document.getElementById("checkBoxInput");
console.log(el.ariaChecked); // "false"
el.ariaChecked = "true";

Understanding the Property

MDN: the ariaChecked property of the Element interface reflects the value of the aria-checked attribute, which indicates the current “checked” state of checkboxes, radio buttons, and other widgets that have a checked state.

• Reflected attribute — mirrors aria-checked.
• Get / set — readable and writable string.
• Four tokens — true, mixed, false, undefined.
• Baseline — widely available since October 2023 (MDN).

📝 Syntax

ariaChecked

Value

A string with one of the following values:

📋 Custom Checkbox (MDN Shape)

MDN starts with an unchecked custom checkbox (aria-checked="false"), then updates to "true" with the property:

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

Also wire keyboard activation (Space / Enter) and visible checked styling so the control matches what ariaChecked reports.

Examples Gallery

Examples follow MDN Element: ariaChecked. Labs use a custom role="checkbox" widget so you can safely read and write the property.

const el = document.getElementById("checkBoxInput");
console.log(el.ariaChecked);

// HTML includes: aria-checked="false"

false

let el = document.getElementById("checkBoxInput");
console.log(el.ariaChecked); // false
el.ariaChecked = "true";
console.log(el.ariaChecked); // true

false
true

const parent = document.createElement("span");
parent.setAttribute("role", "checkbox");
parent.setAttribute("aria-checked", "false");
document.body.appendChild(parent);

parent.ariaChecked = "mixed";
console.log({
  ariaChecked: parent.ariaChecked,
  attr: parent.getAttribute("aria-checked")
});

{
  "ariaChecked": "mixed",
  "attr": "mixed"
}

const el = document.createElement("span");
el.setAttribute("role", "checkbox");
el.setAttribute("aria-checked", "false");
document.body.appendChild(el);

el.ariaChecked = "true";
console.log({
  fromProperty: el.ariaChecked,
  fromAttribute: el.getAttribute("aria-checked"),
  same: el.ariaChecked === el.getAttribute("aria-checked")
});

{
  "fromProperty": "true",
  "fromAttribute": "true",
  "same": true
}

console.log({
  supported: "ariaChecked" in Element.prototype,
  allowed: ["true", "mixed", "false", "undefined"],
  tip: "Prefer native type=checkbox when possible (MDN)",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "allowed": ["true", "mixed", "false", "undefined"],
  "tip": "Prefer native type=checkbox when possible (MDN)",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Custom checkbox widgets built with role="checkbox".
• Radio-like widgets that expose a checked state via ARIA.
• Tri-state parent checkboxes with "mixed".
• Menu item checkboxes (menuitemcheckbox).
• Keeping script and markup aligned without manual setAttribute.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• Values are strings: true, mixed, false, undefined.
• Prefer native type="checkbox" when possible (MDN).
• Related: ariaColCount, ariaBusy, EventTarget, JavaScript hub.

💡 Best Practices