Digital Accessibility Knowledge Base

aria-required-children

Certain ARIA roles must contain particular children

Who might be affected
Screen Reader

Description

Sometimes it is necessary to use non-semantic elements to extend semantics that do not exist naturally in HTML or other constraints. Elements that have an ARIA role that requires specific owned elements such as list, table, row etc., should contain at least one instance of its required owned element. For example, an element that has a role="list", MUST contain at least one element with role="listitem". There may be cases that the "required owned elements" are "currently not present", for example, while editing or while loading data. When a widget is missing, required owned elements due to script execution or loading, the containing element should be marked with aria-busy="true" until the "required owned elements" are filled.

Quick Fixes

Make sure that all the elements that require a specific children type contain at least one instance of the required owned element.
If you are not sure if and which children type an element requires, check out this roles list on the WAI ARIA spec.
1✗    <div role="list">
2        <div><!-- div content --></div>
3        <div><!-- div content --></div>
4        <div><!-- div content --></div>
5    </div>
6

7✓    <div role="list">
8        <div role="listitem"><!-- List item content --></div>
9        <div role="listitem"><!-- List item content --></div>
10        <div role="listitem"><!-- List item content --></div>
11    </div>
12

13✓    <div role="list">
14        <div role="listitem"><!-- List item content --></div>
15        <div><!-- div content --></div>
16        <div><!-- div content --></div>
17    </div>
18
If the data is loading, calculated, etc. and still not available to populate the required element/s, you can use the "aria-busy" attribute and make it equal to "true". Just remember to remove it when the elements are populated.
1✓   <div role="list" aria-busy="true">
2        <!-- Content Is Loading -->
3    </div>
4

How Users Are Affected

When a screen reader fails to parse the semantic meaning of UI elements, it cannot mediate it correctly to the user. As a result, the user receives a partial or even incorrect mental image of the UI and might fail to use it.

WCAG Success criteria

This issue might cause elements to fail one or more of the following Success criteria:
1.3.1 Info and relationships (A)