This document gives information about the related Acquia Optimize 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.

What¶

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.

Why¶

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.

Affected users¶

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.

Examples¶

This section gives some examples of the issue.

Example – checkbox including the required aria-checked state¶

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).

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.

Example – checkbox missing the required aria-checked state¶

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.

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.

How¶

How to fix it¶

The Acquia Optimize 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.

Additional resources¶

WCAG success criteria¶

• 1.3.1 Info and Relationship

• 4.1.2 Name, Role, Value

ACT rules¶

Related accessibility conformance testing rules:

• 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

Other resources¶

• WAI-ARIA 1.2 Reference Documentation

• ARIA in HTML

• ARIA Authoring Practices