Learn Measure Blog About

Elements with an ARIA [role] that require children to contain a specific [role] are missing some or all of those required children

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 require specific child roles. For example, the tablist role must own at least one element with the tab role. If the required child roles aren't present, assistive technologies may convey confusing information about your page, like announcing a tab set with no tabs.

How Lighthouse identifies missing child roles

Lighthouse flags ARIA roles that don't have the required child roles:

Lighthouse audit showing ARIA role missing required child role(s)

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

In the example Lighthouse audit above, the radiogroup role requires child elements with the radio role. Since there are no children with a radio role defined, the audit fails. This makes sense, as it would be confusing to have a radio group without any radio buttons.

This issue is important to fix and may break the experience for users. In the example above, the element may still be announced as a radio group, but users won't know how many radio buttons it contains.

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 child roles

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

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