Learn Measure Blog About

[role]s are not contained by their required parent element

Updated

Users of screen readers and other assistive technologies need information about the behavior and purpose of controls on your web page. Native HTML controls like buttons and radio groups come with that information built in. For custom controls you create, however, you must provide the information with ARIA roles and attributes. (Learn more in the Introduction to ARIA.)

Some ARIA roles must be owned by specific parent roles. For example, the tab role must have an element with the tablist role as a parent. If the required parent role isn't present, assistive technologies may announce the child roles as plain text content rather than the intended control.

How Lighthouse identifies missing parent roles

Lighthouse flags ARIA child roles that aren't contained by the required parent:

Lighthouse audit showing ARIA role missing required parent role

Lighthouse uses the role definitions from the WAI-ARIA specification to check for required context roles—that is, required parent roles. A page fails this audit when it contains a child role that's missing its required parent role.

In the example Lighthouse audit above, the listitem role requires a parent group or list. Since there's no parent role defined, the audit fails. This makes sense, as it would be confusing to have a list item that isn't part of a list.

This issue is important to fix and may break the experience for users. In the example above, the element would be announced as plain text content, and its listitem role would be ignored.

The Lighthouse Accessibility score is a weighted average of all the accessibility audits. See the Lighthouse accessibility scoring post for more information.

How to add missing parent roles

Refer to the WAI-ARIA role definitions to see which parent roles are required for the elements that Lighthouse flagged. (The spec refers to required parents as required context roles.)

There are two ways to set up the required relationships between ARIA parent and child roles.

Option 1: Place the child elements within the parent in the DOM

Placing elements with child roles within the parent role element in your HTML is usually the easiest and most maintainable solution. For example:

<div role="tablist">
<button role="tab" aria-selected="true" aria-controls="tab-1-pane" active>
Tab 1
</button>
<button role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-2-pane">
Tab 2
</button>
<button role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-3-pane">
Tab 3
</button>
</div>

Option 2: Associate the child roles with the parent role using aria-owns

If you can't place child role elements inside the parent role element, you can use the aria-owns attribute to associate them:

<div role="tablist" aria-owns="tab-1 tab-2 tab-3"></div>

<button id="tab-1" role="tab" aria-selected="true" aria-controls="tab-1-pane" active>
Tab 1
</button>
<button id="tab-2" role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-2-pane">
Tab 2
</button>
<button id="tab-3" role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-3-pane">
Tab 3
</button>

If an element with the aria-owns attribute contains DOM children, assistive technologies will announce the DOM children before the elements listed in aria-owns.

Resources

Last updated: Improve article