JavaScript Element ariaControlsElements Property

What You’ll Learn

Element.ariaControlsElements is an instance property that holds an array of elements controlled by the current element. Learn how it relates to aria-controls, why 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

Many widgets control other parts of the page: a button that reveals panels, a combobox that opens a popup list, a scrollbar that scrolls a region. ARIA describes that link with aria-controls.

ariaControlsElements is the modern element-reference form: you work with real DOM nodes instead of managing id strings.

const controlled = toggleButton.ariaControlsElements;
controlled.forEach((el) => console.log(el.textContent.trim()));

Understanding the Property

MDN: the ariaControlsElements property of the Element interface is an array containing the elements that are controlled by the element it is applied to. For example, this might be set on a combobox to indicate the element that it pops up, or on a scrollbar to indicate the element it controls.

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

📝 Syntax

ariaControlsElements

Value

An array of subclasses of HTMLElement, representing the elements that are controlled by this element.

• 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-controls Attribute

📋 Button Controls Panels (MDN Shape)

MDN’s example uses a button that controls two panels listed in aria-controls:

<button id="toggleButton" aria-controls="panel1 panel2" aria-expanded="false">
  Show Details
</button>

<div class="panel" id="panel1" aria-hidden="true">
  <p>Panel1 opened/closed by button.</p>
</div>

<div class="panel" id="panel2" aria-hidden="true">
  <p>Panel2 opened/closed by button.</p>
</div>

Related element-reference property: ariaActiveDescendantElement (single active descendant, not a controls list).

Examples Gallery

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

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

ariaControlsElements is supported

const toggleButton = document.getElementById("toggleButton");

console.log("aria-controls:", toggleButton.getAttribute("aria-controls"));

if ("ariaControlsElements" in Element.prototype) {
  const controlled = toggleButton.ariaControlsElements;
  console.log("count:", controlled.length);
  controlled.forEach((el) => {
    console.log("text:", el.textContent.trim());
  });
} else {
  console.log("ariaControlsElements not supported by browser");
}

aria-controls: panel1 panel2
count: 2
text: Panel1 opened/closed by button.
text: Panel2 opened/closed by button.

const btn = document.createElement("button");
const a = document.createElement("div");
const b = document.createElement("div");
a.textContent = "Panel A";
b.textContent = "Panel B";
document.body.append(btn, a, b);

if ("ariaControlsElements" in Element.prototype) {
  btn.ariaControlsElements = [a, b];
  console.log({
    count: btn.ariaControlsElements.length,
    attrAfterSet: btn.getAttribute("aria-controls"), // cleared when property is set (MDN)
    texts: btn.ariaControlsElements.map((el) => el.textContent)
  });
} else {
  console.log("ariaControlsElements not supported by browser");
}

{
  "count": 2,
  "attrAfterSet": null,
  "texts": ["Panel A", "Panel B"]
}

const btn = document.getElementById("toggleButton");

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

{
  "fromAttribute": "panel1 panel2",
  "supported": true,
  "fromProperty": ["panel1", "panel2"]
}

console.log({
  supported: "ariaControlsElements" in Element.prototype,
  tip: "Returned array is static/read-only; assigned arrays are copied",
  pairsWith: "aria-expanded for open/close widgets",
  status: "Baseline Newly available (MDN, Apr 2025)"
});

{
  "supported": true,
  "tip": "Returned array is static/read-only; assigned arrays are copied",
  "pairsWith": "aria-expanded for open/close widgets",
  "status": "Baseline Newly available (MDN, Apr 2025)"
}

🚀 Common Use Cases

• Disclosure buttons that show or hide one or more panels.
• Combobox widgets that control a popup listbox.
• Tabs that control their associated tabpanels.
• Scrollbars or other widgets that control a scroll region.
• Custom elements via ElementInternals.ariaControlsElements.

🔧 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: ariaCurrent, ariaColSpan, EventTarget, JavaScript hub.

💡 Best Practices