JavaScript Element ariaRoleDescription Property

What You’ll Learn

Element.ariaRoleDescription is an instance property that reflects the aria-roledescription attribute. Learn how a short custom role description works with a real ARIA role, when to use it carefully, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

Assistive technologies usually announce a role by its standard name—button, dialog, application. Sometimes authors want a clearer, localized phrase for a specialized widget, such as calling an article a “slide” in a deck.

aria-roledescription provides that human-readable description. ariaRoleDescription is the JavaScript reflection of that attribute.

const el = document.getElementById("myApplication");
console.log(el.ariaRoleDescription); // "a description of this widget"
el.ariaRoleDescription = "an updated description of this widget";

Understanding the Property

MDN: the ariaRoleDescription property of the Element interface reflects the value of the aria-roledescription attribute, which defines a human-readable, author-localized description for the role of an element.

• Reflected attribute — mirrors aria-roledescription.
• Get / set — readable and writable string.
• Free-form text — author-localized role wording.
• Baseline — widely available since October 2023 (MDN).

📝 Syntax

ariaRoleDescription

Value

A string—the human-readable description of the element’s role.

📋 MDN Example Shape

MDN starts with an application widget that already has a role description, then updates the string with the property:

<div
  id="myApplication"
  role="application"
  aria-roledescription="a description of this widget"
>
  …
</div>

let el = document.getElementById("myApplication");
console.log(el.ariaRoleDescription); // "a description of this widget"
el.ariaRoleDescription = "an updated description of this widget";
console.log(el.ariaRoleDescription); // "an updated description of this widget"

Notice role="application" stays in place. The description only changes how that role is presented.

Examples Gallery

Examples follow MDN Element: ariaRoleDescription. Labs use an application widget so you can safely read and write the property.

const el = document.getElementById("myApplication");
console.log(el.ariaRoleDescription);

// HTML includes: role="application" aria-roledescription="…"

a description of this widget

let el = document.getElementById("myApplication");
console.log(el.ariaRoleDescription); // "a description of this widget"
el.ariaRoleDescription = "an updated description of this widget";
console.log(el.ariaRoleDescription); // "an updated description of this widget"

a description of this widget
an updated description of this widget

const slide = document.createElement("article");
slide.id = "article";
slide.setAttribute("aria-labelledby", "slide1heading");
slide.innerHTML = "<h1 id=\"slide1heading\">Welcome to my talk</h1>";
document.body.appendChild(slide);

slide.ariaRoleDescription = "slide";
console.log({
  ariaRoleDescription: slide.ariaRoleDescription,
  attr: slide.getAttribute("aria-roledescription")
});

{
  "ariaRoleDescription": "slide",
  "attr": "slide"
}

const el = document.createElement("div");
el.setAttribute("role", "application");
el.setAttribute("aria-roledescription", "a description of this widget");
document.body.appendChild(el);

el.ariaRoleDescription = "an updated description of this widget";
console.log({
  fromProperty: el.ariaRoleDescription,
  fromAttribute: el.getAttribute("aria-roledescription"),
  same: el.ariaRoleDescription === el.getAttribute("aria-roledescription")
});

{
  "fromProperty": "an updated description of this widget",
  "fromAttribute": "an updated description of this widget",
  "same": true
}

console.log({
  supported: "ariaRoleDescription" in Element.prototype,
  type: "string",
  tip: "Keep a valid role; use description for wording only",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "type": "string",
  "tip": "Keep a valid role; use description for wording only",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Slideshows that announce an article as a “slide.”
• Custom application widgets with a localized role phrase.
• Map or canvas tools that need clearer role wording than the base role alone.
• Updating role descriptions when the widget mode changes.
• Keeping script and markup aligned without manual setAttribute.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• Keep a valid role; do not use role description as a substitute for semantics.
• Optional braille short form: ariaBrailleRoleDescription.
• Related: ariaRequired, ariaLabel, ariaBrailleRoleDescription, JavaScript hub.

💡 Best Practices