JavaScript Element ariaDescribedByElements Property

What You’ll Learn

Element.ariaDescribedByElements is an instance property that holds an array of elements providing an accessible description. Learn how it relates to aria-describedby, why description targets do not need an id when you set the property, and how to get or set the relationship from JavaScript—with five examples and try-it labs.

Introduction

Controls often need extra help text: a warning under a destructive button, a hint next to a field, or longer context that is not part of the short accessible name. ARIA exposes that with aria-describedby.

ariaDescribedByElements is the modern element-reference form: you work with real DOM nodes instead of only managing id strings. The accessible description is similar to a label, but usually more verbose.

const describedBy = button.ariaDescribedByElements;
const text = describedBy.map((e) => e.textContent.trim()).join(" ");
console.log(text);

Understanding the Property

MDN: the ariaDescribedByElements property of the Element interface is an array containing the element (or elements) that provide an accessible description for the element it is applied to. The accessible description is similar to the accessible label (see ariaLabelledByElements), but provides more verbose information.

• Get / set — read or assign an array of elements.
• Flexible alternative to the aria-describedby attribute.
• No id required on description nodes when you set the property (MDN).
• Reflection — reads valid in-scope id refs from the attribute; setting the property clears the attribute.

📝 Syntax

ariaDescribedByElements

Value

An array of subclasses of HTMLElement. The inner text of these elements can be joined with spaces to get the accessible description.

• When read, the returned array is static and read-only.
• When written, the assigned array is copied—later edits to that array do not change the property.

⚖️ Property vs aria-describedby Attribute

📋 Button With Descriptions (MDN Shape)

MDN’s example links a button to two description spans via aria-describedby. Those spans can be visually hidden while still providing the accessible description:

<button aria-describedby="trash-desc1 trash-desc2">Move to trash</button>

<span id="trash-desc1">Trash will be permanently removed after 30 days.</span>
<span id="trash-desc2">Or Else!</span>

Related element-reference property: ariaControlsElements (controlled regions, not description text).

Examples Gallery

Examples follow MDN Element: ariaDescribedByElements. Labs feature-detect first so older browsers still show a clear message.

if ("ariaDescribedByElements" in Element.prototype) {
  console.log("ariaDescribedByElements is supported");
} else {
  console.log("ariaDescribedByElements not supported by browser");
}

ariaDescribedByElements is supported

const buttonElement = document.querySelector("button");

console.log("aria-describedby:", buttonElement.getAttribute("aria-describedby"));

if ("ariaDescribedByElements" in Element.prototype) {
  const buttonElements = buttonElement.ariaDescribedByElements;
  console.log("count:", buttonElements.length);
  const text = buttonElements.map((e) => e.textContent.trim()).join(" ");
  console.log("Accessible description:", text.trim());
} else {
  console.log("ariaDescribedByElements not supported by browser");
}

aria-describedby: trash-desc1 trash-desc2
count: 2
Accessible description: Trash will be permanently removed after 30 days. Or Else!

const btn = document.createElement("button");
const d1 = document.createElement("span");
const d2 = document.createElement("span");
d1.textContent = "Files stay in trash for 30 days.";
d2.textContent = "This cannot be undone.";
document.body.append(btn, d1, d2);

if ("ariaDescribedByElements" in Element.prototype) {
  btn.ariaDescribedByElements = [d1, d2];
  console.log({
    count: btn.ariaDescribedByElements.length,
    attrAfterSet: btn.getAttribute("aria-describedby"),
    text: btn.ariaDescribedByElements.map((e) => e.textContent).join(" ")
  });
} else {
  console.log("ariaDescribedByElements not supported by browser");
}

{
  "count": 2,
  "attrAfterSet": null,
  "text": "Files stay in trash for 30 days. This cannot be undone."
}

const btn = document.querySelector("button");

console.log({
  fromAttribute: btn.getAttribute("aria-describedby"),
  supported: "ariaDescribedByElements" in Element.prototype,
  fromProperty: "ariaDescribedByElements" in Element.prototype
    ? btn.ariaDescribedByElements.map((el) => el.id)
    : null
});

{
  "fromAttribute": "trash-desc1 trash-desc2",
  "supported": true,
  "fromProperty": ["trash-desc1", "trash-desc2"]
}

console.log({
  supported: "ariaDescribedByElements" in Element.prototype,
  tip: "Returned array is static/read-only; assigned arrays are copied",
  pairsWith: "ariaLabelledByElements for the accessible name",
  status: "Baseline Newly available (MDN, Apr 2025)"
});

{
  "supported": true,
  "tip": "Returned array is static/read-only; assigned arrays are copied",
  "pairsWith": "ariaLabelledByElements for the accessible name",
  "status": "Baseline Newly available (MDN, Apr 2025)"
}

🚀 Common Use Cases

• Destructive actions with warning text (trash, delete, reset).
• Form fields linked to hint or error message elements.
• Icon-only buttons that need longer spoken help beyond a short name.
• Dynamic UIs that attach description nodes without assigning ids.
• Custom elements via ElementInternals.ariaDescribedByElements.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Newly available, Apr 2025).
• Feature-detect on older browsers.
• Returned arrays are static; assigned arrays are copied.
• Related: ariaDescription, ariaCurrent, EventTarget, JavaScript hub.

💡 Best Practices