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.

By Updated ⏱ 1-3 hours, depending on the number of custom widgets🎯 Intermediate● High impactAccessibility
Illustration: Valid ARIA attributes and roles fix guide
ACCESSIBILITY · FIX GUIDE Valid ARIA attributes and roles IMPACTEFFORT TIME1-3 hours, depending on the number of custom widgets LEVELIntermediate

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.

✕Before<div role="dropdown"aria-expanded="yes"aria-labeledby="menu-title">Products</div>✓After<button type="button"aria-expanded="false"aria-controls="products-menu">Products</button>

What you need

Access to edit your theme templates, components or page HTML
Google Chrome with the free axe DevTools extension (or Node.js to run @axe-core/cli)
A list of your key templates: home, category/listing, product or article, cart/checkout, contact form
Optional: a screen reader (NVDA on Windows, VoiceOver on macOS/iOS)

Step-by-step fix

1

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.

text
npx @axe-core/cli https://example.com https://example.com/shop https://example.com/cart --tags wcag2a,wcag2aa,best-practice
Pro tip: Open menus, modals and accordions before scanning. Hidden widgets are often skipped, and their ARIA errors only appear once they are expanded.
2

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" (use list)

Better still, replace the div with the native element (<button>, <nav>, <input>) and drop the role entirely.

html
<!-- Before -->
<div role="nav" aria-labeledby="nav-title">...</div>

<!-- After -->
<nav aria-labelledby="nav-title">...</nav>
Pro tip: Search your codebase for the bad token (e.g. grep -rn "aria-labeledby" ./theme) to fix every instance at once instead of page by page.
3

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.

html
<!-- 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>
Pro tip: If JavaScript toggles the state, make sure it writes the string "true"/"false" with setAttribute, not undefined or null.
4

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, radio need aria-checked
  • combobox needs aria-expanded
  • slider and focusable scrollbar need aria-valuenow (scrollbar also aria-controls)
  • heading needs aria-level

Update the state in JavaScript whenever the user interacts.

html
<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>
Pro tip: A native <input type="checkbox"> or <input type="range"> exposes all of these states automatically and is easier to maintain.
5

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.

html
<!-- 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>
Pro tip: Wrapper divs between parent and child break the relationship. Give them role="none" or remove them.
6

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-label on a plain <div> or <span> with no role is prohibited and ignored; add a suitable role or use visible text
  • aria-checked on a native checkbox conflicts with the real checked state; remove it
  • aria-expanded on a role that does not support it (e.g. img)
  • Roles that contradict the element, such as <button role="heading"> or <ul role="button">
html
<!-- 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>
7

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.

html
<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>
Pro tip: Modal scripts that set aria-hidden on <body> are a common cause of aria-hidden-body. Apply it (or inert) to a sibling wrapper of the dialog instead.
8

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.

text
npx @axe-core/cli https://example.com https://example.com/shop https://example.com/cart --tags wcag2a,wcag2aa,best-practice --exit
Pro tip: Add the --exit command to your CI pipeline so a build fails if new ARIA errors are introduced.

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 free

FAQ

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.