wrong-semantic-role-detection
Web validation
The role of an element tells assistive technology what the element is: a checkbox, a button, a text field, and so on. Two roles take that information away:
role="none"(the same asrole="presentation") removes the element's semantics.role="listitem"replaces them, so the element is exposed as an item in a list.
When either role is on an element that looks and works like a control, such as a checkbox, a combobox, a text field, a submit button, a switch, a disclosure button, or a hamburger menu button, assistive technology doesn't expose it as a control. Screen reader users aren't told that they can interact with it, or what type of control it is, so they may not realize they can use it, or know how to operate it. Voice input users may not be able to activate it by name, because their software doesn't recognize it as a control.
Evinced reports this issue when an element that looks like one of these controls has role="none" or role="listitem".
To fix the issue:
- Use the native HTML element that matches the control, such as
<input type="checkbox">,<button>, or<input type="text">. - If a custom element is necessary, give it the matching ARIA role, such as
checkbox,combobox,textbox,button, orswitch, and the states it needs, such asaria-checkedoraria-expanded. - If the control sits inside a list, apply
role="listitem"to the element that wraps the control, not to the control itself.
Pass Patterns
Native checkbox
The native element exposes the checkbox role and its checked state.
<input type="checkbox" id="newsletter" />
<label for="newsletter">Send me the newsletter</label>Custom switch with the matching role
The custom element has the switch role and the aria-checked state. It also needs tabindex="0" and keyboard support, added with script.
<div role="switch" aria-checked="false" tabindex="0">Dark mode</div>Menu button inside a list item
The list item semantics are on the wrapping element, and the button keeps its own role.
<ul>
<li>
<button aria-expanded="false" aria-controls="site-menu">Menu</button>
</li>
</ul>Fail Patterns
Custom checkbox with role="none"
The element is styled and scripted as a checkbox, but role="none" means assistive technology doesn't expose it as one.
<span class="checkbox" role="none">Send me the newsletter</span>Menu button with role="listitem"
The listitem role replaces the button role, so the button is announced as a list item.
<div role="list">
<button role="listitem">Menu</button>
</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
Failure techniques
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.
- Move to the control, and listen to what the screen reader announces.
Expected results: The screen reader announces the control's name, role, and state, for example "Send me the newsletter, checkbox, not checked".
Actual results: The screen reader announces the text only, or announces a list item, with no control role or state.
Inspecting the browser dev-tools
- In your browser's dev tools, select the control and open the Accessibility panel.
- Check the element's role.
Expected results: The role matches the control, for example checkbox, button, or switch.
Actual results: The role is none, presentation, generic, or listitem.
FAQ
How does this issue relate to 4.1.2 Name, role, value?
SC 4.1.2 requires the role of every user interface component to be programmatically determinable. When role="none" or role="listitem" is on a control, its role is hidden or replaced, so assistive technology can't tell users what the control is or how to operate it.
Why is this issue marked as Moderate?
The control is still visible and may still work with a mouse, but screen reader users aren't told what it is, and voice input users may not be able to target it by name. Users can often work it out from the surrounding content, though it takes extra effort, so the issue is rated moderate.
What happens when role="none" is on a native button or input?
Browsers ignore role="none" on elements that can receive focus, such as <button> and <input>, and keep exposing their native role. The control is still exposed, but the conflicting role is unreliable and confusing to anyone reading the code, so remove it. See presentation-role-conflict.
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. |