JavaScript Element ariaDisabled Property

What You’ll Learn

Element.ariaDisabled is an instance property that reflects the aria-disabled attribute. Learn the "true" / "false" strings, when to prefer native disabled, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

A disabled control should still be visible (perceivable) but not operable—no clicks, no edits, no activation. Native form controls use the HTML disabled attribute for that.

Custom widgets that cannot use native disabled expose the same idea with aria-disabled. ariaDisabled is the JavaScript reflection of that attribute.

const el = document.getElementById("saveChanges");
console.log(el.ariaDisabled); // "true"
el.ariaDisabled = "false";

Understanding the Property

MDN: the ariaDisabled property of the Element interface reflects the value of the aria-disabled attribute, which indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

• Reflected attribute — mirrors aria-disabled.
• Get / set — readable and writable string.
• Two tokens — "true" and "false".
• Baseline — widely available since October 2023 (MDN).

📝 Syntax

ariaDisabled

Value

A string with one of the following values:

📋 Custom Save Button (MDN Shape)

MDN starts with a custom button marked disabled, then enables it with ariaDisabled:

<div id="saveChanges" tabindex="0" role="button" aria-disabled="true">
  Save
</div>

let el = document.getElementById("saveChanges");
console.log(el.ariaDisabled); // "true"
el.ariaDisabled = "false";
console.log(el.ariaDisabled); // "false"

When ariaDisabled is "true", also prevent click / Enter / Space handlers and apply disabled styling so the UI matches what assistive technologies hear.

⚖️ Native disabled vs aria-disabled

Examples Gallery

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

const el = document.getElementById("saveChanges");
console.log(el.ariaDisabled);

// HTML includes: aria-disabled="true"

true

let el = document.getElementById("saveChanges");
console.log(el.ariaDisabled); // true
el.ariaDisabled = "false";
console.log(el.ariaDisabled); // false

true
false

const el = document.getElementById("saveChanges");

function setDisabled(on) {
  el.ariaDisabled = on ? "true" : "false";
  // Also block handlers + update CSS when on === true
}

setDisabled(true);
console.log("after disable:", el.ariaDisabled);
setDisabled(false);
console.log("after enable:", el.ariaDisabled);

after disable: true
after enable: false

const el = document.createElement("div");
el.setAttribute("role", "button");
el.setAttribute("aria-disabled", "true");
document.body.appendChild(el);

el.ariaDisabled = "false";
console.log({
  fromProperty: el.ariaDisabled,
  fromAttribute: el.getAttribute("aria-disabled"),
  same: el.ariaDisabled === el.getAttribute("aria-disabled")
});

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

console.log({
  supported: "ariaDisabled" in Element.prototype,
  allowed: ["true", "false"],
  tip: "Prefer native button/input disabled when possible (MDN)",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "allowed": ["true", "false"],
  "tip": "Prefer native button/input disabled when possible (MDN)",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Custom buttons that cannot use HTML disabled.
• Composite widgets where a region is temporarily inoperable but still visible.
• Enabling a Save / Submit control after form validation.
• Keeping script and markup aligned without manual setAttribute.
• Teaching the difference between native disabled and ARIA disabled.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• Values are strings: true and false.
• Prefer native disabled on buttons and form controls when possible (MDN).
• Related: ariaErrorMessageElements, ariaDetailsElements, EventTarget, JavaScript hub.

💡 Best Practices