How to Fix Invalid ARIA Attributes and Roles on Your Site
ARIA roles and attributes tell assistive technology what a custom element is and what state it is in. When a role is misspelled, an attribute is not allowed on that element, a value is invalid, or a required state is missing, screen readers announce the wrong thing or nothing at all. By the end of this guide you will have found every ARIA error on your key templates, corrected it, and confirmed the fix with an automated scan and a quick screen reader check.

Why it matters
Broken ARIA is often worse than no ARIA: a div with role="checkbox" but no aria-checked is announced as a checkbox with no state, and a menu wrapped in aria-hidden="true" that still receives focus traps keyboard users in invisible content. These failures block real customers from navigation, filters and checkout, they are counted against you under WCAG 2.2 success criterion 4.1.2 (Name, Role, Value) in accessibility complaints and procurement reviews, and they lower Lighthouse accessibility scores. Assistive technologies and AI agents that read the accessibility tree also rely on correct roles to understand what your controls do.
What you need
Step-by-step fix
Scan your key templates for ARIA errors
Open each key page in Chrome, open DevTools (F12), go to the axe DevTools tab and click Scan ALL of my page. Filter results to issues whose rule ID starts with aria-. Note the rule, the element selector and the page, because the same component (header, mega menu, slider, cookie banner) usually repeats across the whole site.
To scan many URLs at once, use the CLI command below.
npx @axe-core/cli https://example.com https://example.com/shop https://example.com/cart --tags wcag2a,wcag2aa,best-practice
Correct invalid, misspelled and deprecated names
Rules aria-roles, aria-valid-attr and aria-deprecated-role flag roles and attributes that do not exist in the ARIA spec. Common offenders:
- Made-up roles:
role="dropdown",role="nav",role="input" - Misspelled attributes:
aria-labeledby(correct:aria-labelledby),aria-role,aria-lable - Deprecated roles:
role="directory"(uselist)
Better still, replace the div with the native element (<button>, <nav>, <input>) and drop the role entirely.
<!-- Before --> <div role="nav" aria-labeledby="nav-title">...</div> <!-- After --> <nav aria-labelledby="nav-title">...</nav>
Fix invalid attribute values and broken ID references
Rule aria-valid-attr-value fails when a value is not allowed for that attribute or an ID reference points to nothing. Booleans must be true or false (not yes, 1 or empty); aria-current accepts page, step, location, date, time, true or false; aria-controls, aria-labelledby and aria-describedby must reference an id that exists on the same page. Check duplicated components, where copied IDs often go missing or collide.
<!-- Before --> <button aria-expanded="yes" aria-controls="faq-1">Shipping</button> <a href="/shop" aria-current="active">Shop</a> <!-- After --> <button aria-expanded="false" aria-controls="faq-shipping">Shipping</button> <div id="faq-shipping" hidden>...</div> <a href="/shop" aria-current="page">Shop</a>
Add the attributes each role requires
Rule aria-required-attr fails when a role is missing a mandatory state. The ones that trip sites up most:
checkbox,switch,menuitemcheckbox,menuitemradio,radioneedaria-checkedcomboboxneedsaria-expandedsliderand focusablescrollbarneedaria-valuenow(scrollbar alsoaria-controls)headingneedsaria-level
Update the state in JavaScript whenever the user interacts.
<div role="switch" tabindex="0" aria-checked="false" aria-labelledby="nl-label"></div> <span id="nl-label">Email me deals from Example Co</span> <div role="slider" tabindex="0" aria-valuemin="0" aria-valuemax="500" aria-valuenow="120" aria-label="Maximum price"></div>
Fix parent and child role structure
Rules aria-required-children and aria-required-parent check that composite widgets are nested correctly: listitem inside list, tab inside tablist, option inside listbox, menuitem inside menu or menubar, row inside table, grid or rowgroup. A frequent failure is putting role="menu" on a site navigation <ul> while the links have no menuitem role. For ordinary site navigation, remove menu/menubar roles completely and use a plain <nav> with a list of links.
<!-- Before -->
<ul role="menu">
<li><a href="/shop">Shop</a></li>
</ul>
<!-- After -->
<nav aria-label="Main">
<ul>
<li><a href="/shop">Shop</a></li>
</ul>
</nav>Remove disallowed and prohibited attributes
Rules aria-allowed-attr, aria-prohibited-attr, aria-conditional-attr and aria-allowed-role catch ARIA used on the wrong element:
aria-labelon a plain<div>or<span>with no role is prohibited and ignored; add a suitable role or use visible textaria-checkedon a native checkbox conflicts with the realcheckedstate; remove itaria-expandedon a role that does not support it (e.g.img)- Roles that contradict the element, such as
<button role="heading">or<ul role="button">
<!-- Before --> <span aria-label="4.5 out of 5 stars">★★★★☆</span> <input type="checkbox" aria-checked="true" checked> <!-- After --> <span role="img" aria-label="4.5 out of 5 stars">★★★★☆</span> <input type="checkbox" checked>
Name widgets and clean up aria-hidden
Give every ARIA widget an accessible name: buttons, links and menu items (aria-command-name), text fields, comboboxes, listboxes and sliders (aria-input-field-name), checkboxes and switches (aria-toggle-field-name), dialogs (aria-dialog-name), plus tooltips, progress bars, meters and tree items. Then fix hidden content: aria-hidden="true" must never be on <body> (aria-hidden-body), and anything inside an aria-hidden region must not be focusable (aria-hidden-focus). Use the inert attribute for closed off-canvas menus and the page behind an open modal.
<div role="dialog" aria-modal="true" aria-labelledby="cart-title"> <h2 id="cart-title">Your cart</h2> </div> <!-- Closed mobile menu: hidden from everyone, not focusable --> <div id="mobile-menu" inert aria-hidden="true">...</div>
Re-scan and test with a screen reader
Clear any page cache or CDN cache, then re-run axe DevTools (or the CLI command from step 1) on every template you edited, with menus and modals open. All aria- rules should pass. Finally, tab through the header, filters and checkout with NVDA (Insert+Space toggles modes) or VoiceOver (Cmd+F5) and confirm each control announces a name, role and current state.
npx @axe-core/cli https://example.com https://example.com/shop https://example.com/cart --tags wcag2a,wcag2aa,best-practice --exit
Platform-specific notes
WordPress
Most ARIA errors come from the theme's header/menu or from slider, mega menu and cookie plugins. Update them first (Dashboard > Updates), then edit block markup via the block's three-dot menu > Edit as HTML. For theme templates, use a child theme or Appearance > Editor > Patterns/Template Parts in block themes; for plugin output, report the bug to the vendor or swap to an accessible alternative.
Shopify
Go to Online Store > Themes > ... > Edit code. ARIA errors usually live in sections/header.liquid, snippets/header-drawer.liquid, product variant pickers and app embeds. Duplicate the theme before editing, and check app blocks (reviews, upsells) separately since their markup is injected by the app.
Wix / Wix Studio
You cannot edit raw HTML of built-in elements. Select the element, open the Inspector panel > Accessibility (or Settings > Accessibility > ARIA attributes in Wix Studio) to set labels and supported ARIA attributes, and run Settings > Accessibility Wizard. Custom code embeds must be fixed in their own HTML.
Webflow
Select the element and open Element Settings (D) > Custom Attributes to add, rename or delete aria-* attributes and role. Webflow's built-in Dropdown, Tabs and Navbar components output their own ARIA; avoid adding conflicting roles on top of them, and use the Audit panel to spot issues.
React / Next.js
Install eslint-plugin-jsx-a11y and enable aria-props, aria-proptypes, aria-role, role-has-required-aria-props and role-supports-aria-props to catch these errors at build time. Pass boolean ARIA states as strings or booleans (aria-expanded={isOpen}), and prefer accessible component libraries such as Radix UI or React Aria over hand-built widgets.
Check that it worked
✅ How to verify
- axe DevTools scan shows zero violations for rules starting with aria- on every key template, with menus and dialogs opened
- Chrome DevTools > Lighthouse > Accessibility report no longer lists ARIA audits such as "[aria-*] attributes are not valid" or "[role]s do not have all required [aria-*] attributes"
- In Chrome DevTools > Elements > Accessibility pane, each fixed widget shows the correct Role, Name and states (e.g. checked, expanded)
- A screen reader announces each control as name + role + state, e.g. "Email me deals, switch, off"
⚠️ Common mistakes
- Adding ARIA to fix a div-based control instead of replacing it with a native <button>, <a>, <input> or <select>, which already have correct roles and states
- Setting the initial state (aria-expanded="false") but never updating it in JavaScript, so the announced state is wrong after interaction
- Using role="menu" and role="menubar" for normal website navigation, which forces strict child roles and keyboard behavior most sites do not implement
- Hiding off-canvas menus or modal backgrounds with aria-hidden="true" while links inside remain focusable, instead of using inert or display:none
Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.
Check my site freeFAQ
What does "ARIA attribute is not allowed" mean?
The attribute is real, but the element's role does not support it. For example, aria-label on a generic <div> or <span> is prohibited, and aria-checked is not supported on role="button". Either give the element an appropriate role, move the attribute to the right element, or remove it.
Which ARIA attributes are required for each role?
The WAI-ARIA 1.2 spec lists required states per role. The most common: checkbox, radio, switch and menuitemcheckbox need aria-checked; combobox needs aria-expanded; slider needs aria-valuenow; heading needs aria-level; focusable scrollbar needs aria-controls and aria-valuenow.
Is it better to remove ARIA than to fix it?
Often yes. The first rule of ARIA is to use a native HTML element when one exists. Removing a wrong role from a native element, or replacing a div with a <button>, fixes the error and reduces JavaScript you must maintain. Only keep ARIA where no native element fits, such as tabs or comboboxes.
Do ARIA errors affect SEO?
Not as a direct ranking factor, but they lower Lighthouse accessibility scores, make controls unusable for screen reader users, and confuse tools and AI agents that read the accessibility tree to understand and interact with your page. They also count as WCAG 4.1.2 failures in legal and procurement accessibility reviews.
How to Fix Duplicate Element IDs for Accessibility
How to Add a Skip to Content Link for Keyboard Users
How to Fix List Structure Errors in HTML (ul, ol, dl)
How to Fix a Missing Main Landmark and Unwrapped Content
How to Fix "Frames Have Titles": Add Iframe Title Attributes
How to Fix Heading Order: One H1 and No Skipped Levels