TheariaControlsElements property of theElement interface is an array containing the elements that are controlled by the element it is applied to.For example, this might be set on acombobox to indicate the element that it pops up, or on ascrollbar to indicate the ID of the element it controls.

Thearia-controls topic contains additional information about how the attribute and property should be used.

Value

An array of subclasses ofHTMLElement, 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: subsequent changes to the array do not affect the value of the property.

Description

The property is a flexible alternative to using thearia-controls attribute to set the controlled elements.Unlikearia-controls, the elements assigned to this property do not have to have anid attribute.

The property reflects thearia-controls attribute when it is defined, but only for listed referenceid values that match valid in-scope elements.If the property is set, then the corresponding attribute is cleared.For more information about reflected element references and scope seeReflected element references in theReflected attributes guide.

Examples

Get the controlled elements

This example shows howariaControlsElements can be used to get the controlled elements that were set usingaria-controls.

HTML

The HTML defines first defines a<button> element and two<div> elements,panel1 andpanel2, that it controls.The references to the controlled panels are listed in the button'saria-controls attribute.

<button aria-controls="panel1 panel2" aria-expanded="false">  Show Details</button><div aria-hidden="true">  <p>Panel1 opened/closed by button.</p></div><div aria-hidden="true">  <p>Panel2 opened/closed by button.</p></div>

.panel {  display: none; /* Initially hidden */  border: 1px solid #cccccc;  padding: 5px;  margin-top: 5px;}

<pre></pre>

#log {  height: 70px;  overflow: scroll;  padding: 0.5rem;  border: 1px solid black;}

JavaScript

The code first sets up the panels to be toggled open or hidden based on thearia-expanded attribute of the button.

const logElement = document.querySelector("#log");function log(text) {  logElement.innerText = `${logElement.innerText}${text}\n`;  logElement.scrollTop = logElement.scrollHeight;}

const toggleButton = document.querySelector("#toggleButton");const panel1 = document.querySelector("#panel1");const panel2 = document.querySelector("#panel2");toggleButton.addEventListener("click", () => {  const isExpanded = toggleButton.getAttribute("aria-expanded") === "true";  toggleButton.setAttribute("aria-expanded", !isExpanded);  panel1.style.display = isExpanded ? "none" : "block";  panel1.setAttribute("aria-hidden", isExpanded); // true when hidden, false when shown.  panel2.style.display = isExpanded ? "none" : "block";  panel2.setAttribute("aria-hidden", isExpanded); // true when hidden, false when shown.});

Next the example gets the value of thearia-controls attribute withElement.getAttribute() (a string listing theid values of the referenced elements).It then checks whether theariaControlsElements property is supported, and if so, logs its value.Finally it returns and logs the inner text for each of the controlled elements.

log(`aria-controls: ${toggleButton.getAttribute("aria-controls")}`);// Feature test for ariaControlsElementsif ("ariaControlsElements" in Element.prototype) {  // Get ariaControlsElements  const controlledElements = toggleButton.ariaControlsElements;  log(`ariaControlsElements: ${controlledElements}`);  // List innerText for each of the ariaControlsElements  controlledElements.forEach((controlled) => {    log(` Controlled element text: ${controlled.textContent.trim()}`);  });} else {  log("element.ariaControlsElements: not supported by browser");}

Result

Click the button below to show and hide the panels.The log shows the original element references, the associated/returned elements, and the inner text of each element.

Specifications

Browser compatibility

See also

• aria-controls attribute
• ElementInternals.ariaControlsElements
• Reflected element references in theAttribute reflection guide