Accessibility Insights

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 identify composite controls that always include 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.

How to fix

  1. Identify the ARIA role that best identifies the element’s function.
  2. In the Chrome or Edge accessibility pane, examine the element serving as the managing control to verify it has the correct "parent" role attribute.
  3. Identify the elements serving as managed controls and add the appropriate "child" roles to them.
  4. Apply any ARIA state and property attributes that are required for the given roles.
  5. Make sure the value of each ARIA property attribute is correct.
  6. 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

This code functions together as a radio group (composite) control. The managing <div> element has the correct "parent" role (radiogroup), but the managed <div> elements that serve as radio buttons are missing the required "child" role (radio). Because assistive technologies can’t identify the radio buttons, some users can’t use the radiogroup.

<div role="radiogroup" aria-labelledby="size"
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

The children of the radiogroup parent are marked with role="radio". Assistive technologies can identify the managed controls as radio buttons. In addition, an attribute required by the radio role (aria-checked) has been added to each radio button. These attribute values are updated through scripting (not shown) to ensure they always communicate the correct current state to assistive technologies.

<div role="radiogroup" aria-labelledby="size" id="rg1">
<h3 id="size">T-shirt size:</h3>
<div role="radio" aria-checked="false" tabindex="0">Small</div>
<div role="radio" aria-checked="true" tabindex="-1">Medium</div>
<div role="radio" aria-checked="false" tabindex="-1">Large</div>
</div>

About this rule

This rule passes if:

  • Required ARIA child roles are present

More examples