Rule ID: ace-aria-allowed-attr

Check that ARIA attributes applied to an element are compatible with its assigned role

WCAG 2.0 (A) - WCAG 2.2 (A) 4.1.2: Name, Role, Value Blind Deafblind Mobility Legal Risk

What This Rule Checks

ARIA (Accessible Rich Internet Applications) attributes help make interactive elements accessible to users relying on screen readers and other assistive technologies. However, ARIA attributes must only be used where they are allowed. If an ARIA attribute is applied to an element that doesn’t support it, assistive technologies may misinterpret the element or fail to interact with it properly, leading to confusion or rendering the element inaccessible.

Who Is Affected

This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content; Mobility users, who navigate using keyboards, switches, voice control, or other assistive input devices.

Why This Matters

When ARIA attributes conflict with an element’s role, screen readers may announce nonsensical states (e.g., “heading, checked”) causing confusion. This violates WCAG 4.1.2 (Name, Role, Value) and is a Level A conformance failure.

How to Fix

To fix ARIA attribute issues, ensure the following best practices are followed:

Use ARIA Attributes Only Where Allowed: Always check whether an element supports the ARIA attribute before applying it. Refer to documentation like WAI-ARIA to confirm the valid attributes for different roles.

Check Role and Attribute Compatibility: Make sure that the role assigned to an element supports the ARIA attributes being used. For example, an aria-expanded attribute should only be applied to elements that can be expanded, such as buttons or dropdowns.

Code Examples

Incorrect Markup Solutions:
Code example
<!-- aria-checked on a non-toggle element --> <div role="heading" aria-level="2" aria-checked="true"> Section Title </div> Copy
Correct Markup Solutions:
Code example
<!-- Only appropriate ARIA attributes for the role --> <div role="heading" aria-level="2"> Section Title </div> Copy

Common Mistakes to Avoid

  • Adding aria-expanded to elements that cannot expand or collapse.
  • Using aria-checked on elements without a checkbox or switch role.
  • Applying aria-selected to elements outside a listbox or grid.
  • Not consulting the WAI-ARIA spec to verify which attributes are allowed per role.

Tip: Remember the first rule of ARIA: don’t use ARIA if a native HTML element can provide the same semantics. Native elements come with built-in keyboard handling and screen reader support that ARIA cannot replicate.

Related WCAG Criteria

  • 4.1.2: Name, Role, Value