Back to Info and Examples for Accessibility Insights for Web
aria-required-children
Certain ARIA roles must contain particular children.
Why it matters
An ARIA role attribute can be added to an element to instruct assistive technologies to treat the element as something other than its native HTML element type.
For example, a <ul> element with role="listbox" is to be treated as a listbox control, not as a static list.
Some ARIA "parent" roles have Required Owned Elements. These "parent" roles identify composite controls that always include only managed controls, identified by "child" roles.
For example, role="listbox" identifies a composite control that manages a set of managed controls identified by role="option".
People who use assistive technologies might find it difficult or impossible to use a composite control if its managed controls lack the required child role or if it contains unexpected types of children.
How to fix
- Identify the ARIA role that best identifies the element’s function.
- In the Chrome or Edge accessibility pane, examine the element serving as the managing control to verify it has the correct "parent" role attribute.
- Identify the elements serving as managed controls and add the appropriate "child" roles to them.
- Remove any child elements of the managing control which are not serving as managed controls.
- Apply any ARIA state and property attributes that are required for the given roles.
- Make sure the value of each ARIA property attribute is correct.
- Make sure the value of each ARIA state attribute updates as needed to reflect the element’s current state.
For details about composite widgets and their required roles, see WAI-ARIA Authoring Practices 1.1: Design Patterns and Widgets.
Example
Fail
<div> element has the correct "parent" role (listbox), but the managed <div> elements are missing the required "child" role (option). Additionally, the managing <div> element has a child element that should not be present (h3).id="rg1">
<h3 id="size">T-shirt size:</h3>
<div tabindex="0">Small</div>
<div tabindex="-1">Medium</div>
<div tabindex="-1">Large</div>
</div>
Pass
listbox parent which represent listbox-managed controls are marked with role="option".
In addition, an attribute required by the listitem role (aria-selected) has been added to each list item. These attribute values are updated through scripting (not shown) to ensure they always communicate the correct current state to assistive technologies.<div role="listbox" aria-labelledby="size" >
<div role="option" aria-selected="false" tabindex="0">Small</div>
<div role="option" aria-selected="true" tabindex="-1">Medium</div>
<div role="option" aria-selected="false" tabindex="-1">Large</div>
</div>
About this rule
This rule passes if ALL of the following are true:
- At least one child has an ARIA role which is one of the parent ARIA role's Required Owned Elements.
- All children either:
- have an ARIA role which is one of the parent ARIA role's Required Owned Elements, OR
- Are not present in the browser's accessibility tree