JavaScript Element ariaDescription Property

What You’ll Learn

Element.ariaDescription is an instance property that reflects the aria-description attribute. Learn how a description string annotates an element, how it differs from aria-label and aria-describedby, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

An accessible name tells users what a control is (“Close”). An accessible description adds longer context—what will happen, a warning, or extra detail.

aria-description stores that longer string on the element itself. ariaDescription is the JavaScript reflection of that attribute.

const el = document.getElementById("close-button");
console.log(el.ariaDescription);
el.ariaDescription = "A different description";

Understanding the Property

MDN: the ariaDescription property of the Element interface reflects the value of the aria-description attribute, which defines a string value that describes or annotates the current element.

• Reflected attribute — mirrors aria-description.
• Get / set — readable and writable string.
• Annotation — extra context beyond the accessible name.
• Baseline — newly available since March 2024 (MDN).

📝 Syntax

ariaDescription

Value

A string that describes or annotates the element.

📋 Close Button (MDN Shape)

MDN pairs a short aria-label with a longer aria-description on an icon-only close button:

<button
  aria-label="Close"
  aria-description="A longer description of the function of this element"
  id="close-button">
  X
</button>

let el = document.getElementById("close-button");
console.log(el.ariaDescription);
// "A longer description of the function of this element"
el.ariaDescription = "A different description";
console.log(el.ariaDescription); // "A different description"

⚖️ ariaDescription vs ariaDescribedByElements

Examples Gallery

Examples follow MDN Element: ariaDescription. Labs use a close button so you can safely read and write the property.

const el = document.getElementById("close-button");
console.log(el.ariaDescription);

// HTML includes: aria-description="A longer description..."

A longer description of the function of this element

let el = document.getElementById("close-button");
console.log(el.ariaDescription);
// "A longer description of the function of this element"
el.ariaDescription = "A different description";
console.log(el.ariaDescription); // "A different description"

A longer description of the function of this element
A different description

const btn = document.createElement("button");
btn.textContent = "X";
btn.setAttribute("aria-label", "Close");
document.body.appendChild(btn);

btn.ariaDescription = "Closes the dialog without saving changes.";
console.log({
  name: btn.getAttribute("aria-label"),
  ariaDescription: btn.ariaDescription,
  attr: btn.getAttribute("aria-description")
});

{
  "name": "Close",
  "ariaDescription": "Closes the dialog without saving changes.",
  "attr": "Closes the dialog without saving changes."
}

const el = document.createElement("button");
el.setAttribute("aria-label", "Close");
el.setAttribute("aria-description", "Original help text");
document.body.appendChild(el);

el.ariaDescription = "Updated help text";
console.log({
  fromProperty: el.ariaDescription,
  fromAttribute: el.getAttribute("aria-description"),
  same: el.ariaDescription === el.getAttribute("aria-description")
});

{
  "fromProperty": "Updated help text",
  "fromAttribute": "Updated help text",
  "same": true
}

console.log({
  supported: "ariaDescription" in Element.prototype,
  tip: "Short name + longer description string",
  alt: "Use ariaDescribedByElements when text is in the DOM",
  status: "Baseline Newly available (MDN, Mar 2024)"
});

{
  "supported": true,
  "tip": "Short name + longer description string",
  "alt": "Use ariaDescribedByElements when text is in the DOM",
  "status": "Baseline Newly available (MDN, Mar 2024)"
}

🚀 Common Use Cases

• Icon-only buttons that need a short name plus longer spoken help.
• Destructive actions with a warning string in script.
• Dynamic UIs that update help text without creating extra DOM nodes.
• Keeping script and markup aligned without manual setAttribute.
• Teaching the difference between name, description string, and describedby.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Newly available, Mar 2024).
• Feature-detect on older browsers.
• Do not put the short name only in aria-description—use a proper accessible name.
• Related: ariaDetailsElements, ariaDescribedByElements, EventTarget, JavaScript hub.

💡 Best Practices