Back to Info and Examples for Accessibility Insights for Web
aria-allowed-attr
Elements must use only ARIA attributes allowed for their implicit or explicit ARIA role.
Why it matters
An ARIA role attribute can be added to various HTML elements to instruct assistive technologies to expose the element as something other than its native HTML element type. For example, an <a> element with role="button" is to be exposed as a button, not a link. Note: modifying an element's role will only change how it is exposed to assistive technology. Any additional functional changes to an element (to either add expected behaviors, or supress native ones), must be separately made by web developers, typically via scripting.
Some ARIA property and state attributes are allowed only for certain ARIA roles. When an assistive technology encounters a mismatch between an element's role and its state or property attributes, it might ignore attributes or respond in an unexpected way. As a result, people who use assistive technologies might find the element difficult or impossible to use.
How to fix
- Identify the ARIA role that best identifies the element’s purpose, function, or both.
- Examine the element in the Chrome or Edge accessibility pane to verify that it has the correct role attribute.
- Use only ARIA state and property attributes that are allowed for the given role.
- Make sure the value of each ARIA property attribute is an accurate and valid value.
- Make sure the value of each ARIA state attribute updates as needed to reflect the element’s current state.
Example
Fail
<button> element has an ARIA role attribute (role="option"). This role overrides the implicit button role, and instead communicates to assistive technologies to expose the <button> as a selectable item in a listing of options (i.e., role="listbox").
However, the element also has an ARIA state attribute (aria-pressed="true"). This attribute is allowed for buttons, but is not a valid attribute for options. Because browsers may not expose incorrect attributes for roles, and some assistive technologies ignore mismatched ARIA attributes, users likely won't know whether this custom option is selected.Pass
aria-selected) for the option role. Set to true in the selected state, and false when not selected.
The attribute's value is updated through scripting (not shown) to ensure it correctly communicates the current state to assistive technologies.About this rule
This rule passes if ALL of the following are true:
- ARIA attribute is used correctly for the implicit or explicit role of the element
- ARIA attribute is widely supported by browsers and assistive technologies