incorrect-root-element
Web validation
Assistive technology describes a component, such as a button, a checkbox, a text field, or a navigation area, through its role. The role belongs on the component's root element: the element users focus and operate, which also holds the component's accessible name, its state, and its keyboard and click handling.
When the role sits on a descendant instead, the parts of the component are split between elements. For example, a wrapper <div> receives focus and handles clicks, while a <span> inside it has role="button". Screen readers announce the focused element without a role, or announce a button that isn't the element users operate. A state set on one element and a role set on another may not be reported together at all, so users can't tell what the component is or what state it's in.
Evinced runs this check on every UI pattern it tests, and on elements it identifies as a UI pattern during a scan. It reports the issue when the element tested as the component doesn't have the pattern's role itself, but one of its descendants does.
To fix the issue:
- Put the role, the accessible name, the state, the ability to receive focus, and the event handling on the same element.
- Remove the role from the descendant, and keep any wrapper free of roles and event handlers.
- Where possible, use the native HTML element, which brings the correct role with it.
Testing a component with an Evinced SDK? If the role is already on the right element, the test may have selected a wrapper around the component. Update the test's locator so it selects the element that has the role, for example role: button, and run the test again.
Pass Patterns
Native button
The <button> element is the root of the component: it has the button role, its name, focus, and the click handler.
<button type="button" onclick="save()">Save</button>Custom checkbox with everything on one element
The role, the state, the name, and focus are all on the same element. It also needs keyboard support, added with script.
<div role="checkbox" aria-checked="false" tabindex="0" onclick="toggle(this)">Remember me</div>Fail Patterns
Button role on a child of the focused element
The wrapper receives focus and handles clicks, but the button role is on the <span> inside it.
<div class="save-button" tabindex="0" onclick="save()">
<span role="button">Save</span>
</div>Checkbox role and state on different elements
The wrapper has the checked state and receives focus, but the checkbox role is on a child, so the role and the state aren't reported together.
<div class="checkbox" tabindex="0" aria-checked="false" onclick="toggle(this)">
<span role="checkbox">Remember me</span>
</div>WCAG techniques
Sufficient techniques
- ARIA4: Using a WAI-ARIA role to expose the role of a user interface component
- G108: Using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes
- H91: Using HTML form controls and links
Try It Yourself
Using a screen reader
New to screen reader testing, or need a refresher?
Review this article first: Practical guides for using screen readers
- Load the page and open a screen reader.
- Press the Tab key until the component has focus.
- Listen to what the screen reader announces.
Expected results: The screen reader announces the component's name, role, and state together, for example "Remember me, checkbox, not checked".
Actual results: The screen reader announces the name without a role, or without the state, or describes an element other than the one that has focus.
Inspecting the browser dev-tools
- In your browser's dev tools, select the element that receives focus, and open the Accessibility panel.
- Check its role, and then the roles of its descendants.
Expected results: The element that receives focus has the component's role, such as button or checkbox.
Actual results: The focused element has a generic role, and the component's role is on one of its descendants.
FAQ
How does this issue relate to 4.1.2 Name, role, value?
SC 4.1.2 requires the name, role, and state of every user interface component to be programmatically determinable. When the role is on a child element while focus and state are on its parent, the component users operate doesn't expose its role, and its role and state can't be determined together.
Why is this issue marked as Serious?
Screen reader users depend on the announced role to understand what a component is and how to operate it. When the role is on a different element from the one they operate, they get an incomplete or misleading description, and may not be able to tell its state or use it with confidence, so the issue is rated serious.
What if the role is already on the right element?
The issue can also come from how the test selected the component. If you run Evinced tests on a component, check that the test selects the element with the role, rather than a wrapper around it. Update the locator and run the test again.
Standards and Regulations
| Standard | Success Criterion | Reference |
|---|---|---|
| WCAG 2.2 | 4.1.2 Name, Role, Value (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | 9.4.1.2 Name, Role, Value | Same as the WCAG text. |
| Section 508 | 1194.21(d) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |