aria-controls

The global aria-controls property identifies the element (or elements) whose contents or presence are controlled by the element on which this attribute is set.

Description

When an interactive or input control, be it a checkbox, radio button, tab panel, icon, toggles, or other, has an impact on another element in a document or application, the aria-control attributes should be included to indicate which element or elements the user interface widget controls. The aria-controls attribute identifies the element (or elements) whose contents or presence are controlled by the element on which the attribute is set, regardless of what type of interaction initiates the impacted behavior.

A combobox element has aria-controls set to a value that refers to the element that serves as the popup. The aria-controls only needs to be set when the popup is visible, but it is valid and easier to program to reference an element that is not visible.

Other examples of controls include:

  • An accordion header button toggling the visibility of the accordion panel's content: the accordion header button would have aria-controls set to the ID of the element containing the accordion panel content.
  • A link with an icon that shows and hides a menu: the link would have aria-controls set to the ID of the element containing the menu.
  • A group of tabs that each display a different tabpanels: each element with role="tab" has the property aria-controls referring to its associated tabpanel.

Example

In this tabs example, each tab controls one tabpanel:

<div class="tab-interface">
  <div role="tablist" aria-label="Sample Tabs">
    <span role="tab" aria-selected="true" aria-controls="panel-1" 
      id="tab-1" tabindex="0">
          First Tab
        </span>
    <span role="tab" aria-selected="false" aria-controls="panel-2" 
      id="tab-2" tabindex="-1">
          Second Tab
        </span>
    <span role="tab" aria-selected="false" aria-controls="panel-3" 
      id="tab-3" tabindex="-1">
          Third Tab
        </span>
  </div>
  <div id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1">
    <p>Content for the first panel</p>
  </div>
  <div id="panel-2" role="tabpanel" tabindex="0" aria-labelledby="tab-2" hidden>
    <p>Content for the second panel</p>
  </div>
  <div id="panel-3" role="tabpanel" tabindex="0" aria-labelledby="tab-3" hidden>
    <p>Content for the third panel</p>
  </div>
</div>

Note: ARIA only modifies the accessibility tree for an element and how assistive technology presents the content to users. ARIA doesn't change anything about an elements function or behavior.

Values

id list

Space seperated list of one or more ID values referencing the elements being controlled by the current element

ARIAMixin API

Element.ariaBusy

The ariaControls property, part of the ARIAMixin interface, reflects the value of the aria-controls attribute, which indicates whether an element is being modified.

Associated roles

Used in ALL roles.

Specifications

Specification Status
Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'ARIA: aria-controls Attribute' in that specification.
Recommendation

See Also