Aria allowed attr

What it is

ARIA (Accessible Rich Internet Applications) attributes are special HTML properties — like `aria-checked`, `aria-expanded`, or `aria-haspopup` — that tell screen readers and other assistive technologies what a page element is and how it behaves. Every ARIA role (e.g. `button`, `listbox`, `img`) has a defined set of attributes it is allowed to carry. When an element has an ARIA attribute that its role does not support — for example, placing `aria-checked` on a plain `<div role="heading">` — the browser and screen reader can't make sense of the conflicting signals. The `aria-allowed-attr` rule flags exactly these mismatches.

Why it matters

Screen reader users — who rely entirely on ARIA signals to understand and navigate your store — receive garbled or misleading information when roles and attributes conflict, making buttons, menus, forms, and product options unusable for them. In many countries (the US ADA, EU EAA, UK PSBAR, and others) online stores must meet WCAG 2.1 AA, and ARIA mismatches are a clear, documentable failure of Success Criterion 4.1.2 (Name, Role, Value) — creating real legal exposure. Beyond legal risk, inaccessible checkout flows and product pages directly reduce conversions from the roughly 15–20 % of shoppers who use assistive technology. Fixing these mismatches is also a trust signal: accessibility audits and Core Web Vitals tooling surface these errors, and a clean bill of health supports your brand reputation.

How to fix it

1. Open browser DevTools (F12) on the page with the flagged element, find the element in the Elements panel, and note its `role` attribute (explicit or implicit) and every `aria-*` attribute present.
2. Cross-reference the element's role against the WAI-ARIA specification's list of allowed attributes for that role (e.g. `role="heading"` does not support `aria-checked`); identify which `aria-*` attributes are invalid for that role.
3. If the attribute is simply wrong for the role, remove it. If the behaviour the attribute was meant to convey is genuinely needed, either change the element's role to one that supports the attribute, or restructure the markup using a semantically correct HTML element (e.g. a native `<button>` instead of a `<div role='button'>`).
4. Prefer native HTML semantics over ARIA wherever possible — a real `<button>`, `<input type='checkbox'>`, or `<select>` carries the correct implicit role and allowed attributes automatically, with no risk of mismatch.
5. After making the change, re-run an automated accessibility checker (e.g. axe DevTools browser extension, WAVE, or Lighthouse) to confirm the `aria-allowed-attr` violation no longer appears on that element.
6. Test the corrected element with an actual screen reader (NVDA + Firefox on Windows, VoiceOver + Safari on macOS/iOS, or TalkBack on Android) to verify the announced role, name, and state are accurate and meaningful.

<!-- WRONG: aria-checked is not allowed on role="heading" -->
<div role="heading" aria-level="2" aria-checked="true">Sale Items</div>

<!-- CORRECT: remove the disallowed attribute -->
<div role="heading" aria-level="2">Sale Items</div>

<!-- BETTER: use a native HTML element (implicit correct role + no mismatch risk) -->
<h2>Sale Items</h2>

<!-- WRONG: aria-expanded is not allowed on role="img" -->
<div role="img" aria-label="Product photo" aria-expanded="false"></div>

<!-- CORRECT: aria-expanded belongs on interactive roles like button/combobox -->
<button type="button" aria-expanded="false" aria-controls="filter-panel">
  Filter products
</button>

Fix it on your platform

Pick your platform for the exact steps.

Frequently asked questions

Authoritative references

• How to fix this specific rule — Deque/axe (rule reference)
• WCAG 2 overview — W3C WAI
• ARIA basics — MDN