Web Governance
Correct use of ARIA in HTML
4.1.2 Name, Role, Value
This document gives information about the related accessibility checks:
Element with role attribute has required states and properties
ARIA state or property is permitted
Role attribute has valid value
State or property has valid value.
When you add ARIA (Accessible Rich Internet Applications) codes to a website, it is important to follow the rules for using ARIA. ARIA are codes that can be added to website elements to improve accessibility beyond what can be achieved with the HTML code that is typically used to build webpages.
When an ARIA role is added, the associated states and properties must be used correctly. When using ARIA states and properties, they must be assigned valid values and be applicable to the elements to which they are assigned. When you use the ARIA role attribute, it must be given a valid value.
The use of ARIA code typically changes how the elements in a website are conveyed by assistive technologies. For example, an ARIA code can alter what is read aloud when a visually impaired user navigates the page with screen reader software. This can make the difference between an element being read as a list of items or being presented as tabs in a tabbed structure. This distinction is crucial for the user to understand how to interact with the content on the page.
If the page contains ARIA codes that do not follow the guidelines for using ARIA, it is a strong indication that the developer intended to improve accessibility but something went wrong in the process. In the worst case, incorrect use of ARIA can mean that some users are unable to perceive or interact with the affected elements on the website.
This check affects the following users who have:
Visual impairments: Who access the site contents with a screen reader or screen magnification software.
Mobility impairments: Who navigate the page with speech recognition software.
Bridgit is a blind mother to a five-year-old girl and an 11-year-old boy:
“Honestly, there are so many times when I am shopping online, and I found exactly what I want to buy. I have spent a ton of time picking it out, going through everything, and then when I get to the very end, ready to pay, that 'Accept terms and conditions' box pops up. My screen reader tells me it is a checkbox, but when I try to click it, nothing happens. It just keeps telling me I have not checked it. It is so frustrating because I know that sometimes it actually gets marked, even though I cannot see it with my screen reader, but other times it does not work at all. It is incredibly annoying.”
This section gives some examples of the issue.
In the example, the developer has chosen not to use a standard HTML checkbox but instead to create their own version. Therefore, ARIA attributes are used to convey to assistive technologies that the element should be recognized as a checkbox (using the role attribute) and to indicate whether it is currently checked (using the aria-checked attribute).
Web Governance<label id="termsLabel" for="termsCheckbox">
<div id="termsCheckbox" class="checkbox checked" role="checkbox" aria-checked="true" tabindex="0"></div>
Accept terms and conditions
</label>Here, screen reader software will announce "Accept terms and conditions, checkbox, checked." This allows users with screen readers to understand and interact with the checkbox effectively.
In the example, the developer has chosen not to use a standard HTML checkbox but instead to create their own version. Therefore, ARIA attributes are used to convey to assistive technologies that the element should be recognized as a checkbox (using the role attribute).
Unfortunately, the developer forgot to include the required aria-checked state in the implementation.
<label id="termsLabel" for="termsCheckbox">
<div id="termsCheckbox" class="checkbox checked" role="checkbox" tabindex="0"></div>
Accept terms and conditions
</label>Here, screen reader software announces "Accept terms and conditions, checkbox."
This means that screen reader users will miss the important information that the checkbox is currently checked.
The Web Governance platform flags instances where the role attribute is used with an invalid value, where the role attribute is used without required states or properties, and cases where ARIA states or properties have been assigned an invalid value or are assigned to an inapplicable element.
In your HTML code:
Roles will appear as role="rolename".
States and properties will appear as aria-xyz="value".
For cases of "Element with role attribute has required states and properties" look up the role in the WAI-ARIA reference documentation. In the "Required States and Properties" section, you can see which states and properties are required for that role. Adjust your code accordingly.
For cases of "state or property has valid value" look up the state or property in the WAI-ARIA reference documentation. In the "Value" section, you can see which values are valid for the state or property. Adjust your code accordingly.
For cases of "ARIA state or property is permitted" refer to the ARIA in HTML reference documentation for info on which states and properties are allowed for specific HTML elements. Adjust your code accordingly.
For cases of "Role attribute has valid value," look up the list of allowed role names in the WAI-ARIA reference documentation. Adjust your code accordingly.
Related accessibility conformance testing rules:
If this content did not answer your questions, try searching or contacting our support team for further assistance.
If this content did not answer your questions, try searching or contacting our support team for further assistance.