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
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 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,
radiogroup role requires child elements with the
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
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:
<button role="tab" aria-selected="true" aria-controls="tab-1-pane" active>
<button role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-2-pane">
<button role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-3-pane">
Option 2: Associate the child roles with the parent role using
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>
<button id="tab-2" role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-2-pane">
<button id="tab-3" role="tab" aria-selected="false" tabindex="-1" aria-controls="tab-3-pane">
If an element with the
aria-owns attribute contains DOM children,
assistive technologies will announce the DOM children before the elements
- Source code for Elements with an ARIA
[role]that require children to contain a specific [role] are missing some or all of those required children audit
- Certain ARIA roles must contain particular children (Deque University)
- Role definitions from the WAI-ARIA specification