JavaScript Element ariaControlsElements Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word ARIACONTROLSELEMENTS

Definition

In JavaScript, the ariaControlsElements property of Element is an array of elements controlled by this element — for example panels a button toggles, or a combobox popup (MDN).

Read the notes below before you get or set this property. Prefer feature detection when support is limited.

Syntax

Use el.ariaControlsElements. Start with this line.

JavaScript
btn.ariaControlsElements
CallWhat it does
btn.ariaControlsElementsPrimary signature.

Built into the browser. Read or assign el.ariaControlsElements — no import required.

Library declarations
JavaScript
btn.ariaControlsElements

Parameters

ParameterDescription
Controlling elementRequired. Button, tab, combobox, scrollbar, ...
Controlled elementsRequired. Panels, popup, tabpanels, scroll target

Return Value

Return ValueDescription
*The current value of el.ariaControlsElements.

JavaScript Examples

Example 1 — Read Controlled Elements

MDN-style: resolve aria-controls ids into Element objects.

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

if ("ariaControlsElements" in Element.prototype) {
  const controlled = btn.ariaControlsElements;
  controlled.forEach((el) => {
    console.log(el.textContent.trim());
  });
}
Try It Yourself

How It Works

  1. Select the control. It should have aria-controls ids.
  2. Feature-detect the property (Newly available).
  3. Read the array. Valid in-scope ids become Element objects.
  4. Use the elements — no manual getElementById loop needed.

Example 2 — Set Without Ids

Assign Element references directly; targets do not need an id.

JavaScript
const btn = document.getElementById("toggleButton");
const p1 = document.getElementById("panel1");
const p2 = document.getElementById("panel2");

btn.ariaControlsElements = [p1, p2];
console.log(btn.ariaControlsElements.length); // 2
console.log(btn.getAttribute("aria-controls")); // null (cleared)
Try It Yourself

How It Works

  1. Grab the panels as Element objects.
  2. Assign an array. The browser copies it (later push/pop won’t stick).
  3. Attribute clears. MDN: setting the property clears aria-controls.
  4. Relationship remains via the property for AT.

Example 3 — Feature-Detect Fallback

Support older browsers with the classic id-string attribute.

JavaScript
function getControlled(el) {
  if ("ariaControlsElements" in Element.prototype) {
    return Array.from(el.ariaControlsElements);
  }
  const ids = (el.getAttribute("aria-controls") || "").trim().split(/\s+/);
  return ids.map((id) => document.getElementById(id)).filter(Boolean);
}

console.log(getControlled(document.getElementById("toggleButton")).length);
Try It Yourself

How It Works

  1. Prefer the property when supported.
  2. Else parse ids from aria-controls.
  3. Resolve with getElementById and drop missing ids.
  4. Same call site works across Baseline and older engines.
Compatibility

Browser Support

Element.ariaControlsElements is Baseline Newly available (MDN: since April 2025). It is not Deprecated, Experimental, or Non-standard — still feature-detect for older clients.

✓ Baseline Newly available

Element.ariaControlsElements

Array of elements controlled by this element. Flexible alternative to aria-controls id strings; assigned elements need no id.

New Newly available (Apr 2025)
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
ariaControlsElements New

Bottom line: Use for button→panel, tab→tabpanel, and combobox popup links. Detect support; fall back to aria-controls ids when needed.

Frequently Asked Questions

An array of HTMLElement subclasses representing the elements controlled by this element — for example panels a button toggles, or a combobox popup (MDN).
No. MDN marks Element.ariaControlsElements as Baseline Newly available (since April 2025). It is not Deprecated, Experimental, or Non-standard. Feature-detect on older browsers.
The attribute uses space-separated id strings. The property uses Element references. Assigned elements do not need an id. Setting the property clears the corresponding attribute (MDN).
No. When read, the array is static and read-only. When written, the assigned array is copied — later changes to that array do not update the property (MDN).
For widgets that control other regions: disclosure buttons, accordion panels, combobox popups, tab → tabpanel, and scrollbars (MDN aria-controls).
Yes. Assign an array of elements. Feature-detect first — Baseline Newly available since April 2025.

Next: ariaCurrent

Learn the Element property that reflects aria-current for the current item in a set.

ariaCurrent tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

JavaScript Element ariaColSpan Property JavaScript Element ariaCurrent Property