The aria-required-children rule flags an element whose ARIA role promises a structure it does not contain: a tablist with no tab, a listbox with no option, a menu with no menuitem. Assistive technology announces the container and then finds nothing it can use in it. The fix is to give the children the roles the container requires – or to drop the container's role.
What the rule means
Some ARIA roles are containers that only make sense with particular children, defined in WAI-ARIA as "required owned elements". A few common pairs:
tablist→tablistbox→option(optionally in agroup)menu/menubar→menuitem,menuitemcheckbox,menuitemradiolist→listitemgrid/table→row(in arowgroupor directly)
The rule fails when a container with one of these roles has no child with a required role, or has children with other roles in between. Children can be real descendants or be attached with aria-owns.
Who is affected
Screen reader users. A tablist announces "tab list" and a count of tabs; a listbox announces options and lets people move between them with the arrow keys. When the children do not carry the roles, the count is zero, the arrow-key navigation has nothing to move to, and the widget becomes a set of unlabelled buttons or plain text – often with no indication that anything is selected.
Why the check fails
- Tabs built from buttons inside
role="tablist", withoutrole="tab"on each button. - Custom selects with
role="listbox"whose items are plain<div>s or<li>s. - Wrappers in between: a
<div class="tab-wrapper">between the tablist and its tabs, withoutrole="presentation". - Empty containers rendered before the items load, for example search suggestions – mark them
aria-busy="true"until they are filled. - Copied markup where the container role survived and the item roles did not.
How to fix it
Give each child the role the container expects, with the states that belong to it.
<!-- Before: a tablist with plain buttons -->
<div role="tablist" aria-label="Product details">
<button type="button" class="tab is-active">Description</button>
<button type="button" class="tab">Reviews</button>
</div><!-- After: real tabs, with their selected state and their panels -->
<div role="tablist" aria-label="Product details">
<button type="button" role="tab" id="tab-desc" aria-selected="true" aria-controls="panel-desc">Description</button>
<button type="button" role="tab" id="tab-rev" aria-selected="false" aria-controls="panel-rev" tabindex="-1">Reviews</button>
</div>
<div role="tabpanel" id="panel-desc" aria-labelledby="tab-desc">…</div>
<div role="tabpanel" id="panel-rev" aria-labelledby="tab-rev" hidden>…</div>The roles are only half of it: a tablist also needs the arrow keys to move between tabs. The ARIA Authoring Practices Guide describes the keyboard behaviour for each pattern. If you do not want to build that, drop the ARIA roles and use plain buttons and headings – that is better than a half-built widget.
How to test it manually
- In the browser's developer tools, open the accessibility tree and select the container. Are its children listed with the expected roles?
- With a screen reader, move onto the widget. Does it announce the number of tabs, options or items?
- Use the arrow keys inside the widget. Does focus move between the items as the pattern describes?
- Check the widget in every state – empty, loading, filtered – not just with content.
Related WCAG criterion
1.3.1 Info and Relationships, Level A. Related: 4.1.2 Name, Role, Value, because each item also needs its own role and state.
How Reviseberg reports it
Reviseberg runs aria-required-children on every crawled page. The issue list shows the rule with its severity, WCAG 1.3.1, the number of affected elements and pages, and the points a fix gets you back; the detail view shows the container's selector and HTML snippet. Components are usually shared, so one fix in the component library often clears the rule on every page. Where axe cannot decide – some containers, such as a listbox, that are completely empty – the case goes to the Potential issues queue for a person to look at. A container marked aria-busy="true" while its items load is not failed.