Aria roles
Quick winFound on 4% of audited stores.
Audit every element that has a `role` attribute and replace any invalid or misspelled role value with a valid WAI-ARIA role from the official specification.
What it is
The `role` attribute tells assistive technologies (screen readers, braille displays, voice control software) what kind of interface element something is — for example, a button, a navigation landmark, a dialog, or a list. The WAI-ARIA specification defines an exact list of allowed role names. If any element on your store carries a role that isn't on that list — whether it's a typo like `role="buton"`, an invented name like `role="product-card"`, or an outdated value like `role="presentation"` used incorrectly — the browser and screen reader simply ignore it or misinterpret the element entirely. WCAG Success Criterion 4.1.2 (Name, Role, Value) requires that every user interface component exposes a valid, programmatically determinable role so all users can understand and operate it.
Why it matters
Screen reader users — who include people with visual impairments, motor disabilities, and cognitive disabilities — rely on role information to navigate and interact with your store. An invalid role means those customers hear confusing or missing announcements, cannot identify interactive controls, and may abandon your checkout or product pages. Beyond lost conversions, accessibility failures carry real legal risk: WCAG 2.1 AA compliance is referenced in ADA Title III lawsuits and, in many jurisdictions, is a statutory requirement for online businesses. Google also uses accessibility signals as a quality factor, so pages riddled with invalid ARIA can indirectly suppress organic rankings. Fixing invalid roles is typically a quick code change with outsized impact on both compliance and customer experience.
How to fix it
- Identify every element with a `role` attribute by running an automated accessibility audit (axe DevTools, WAVE, or Lighthouse) and reviewing the flagged elements in your browser's developer tools.
- Cross-reference each flagged role value against the official WAI-ARIA roles reference (https://www.w3.org/TR/wai-aria/#role_definitions) to confirm whether it is valid.
- Correct typos or misspellings — e.g. `role='buton'` → `role='button'`; `role='navigaton'` → `role='navigation'`.
- Remove invented or proprietary role names that have no equivalent in the WAI-ARIA spec. If the element's purpose is not expressible with an existing ARIA role, use a native HTML element instead (e.g. `<button>`, `<nav>`, `<dialog>`).
- Replace deprecated or abstract roles (such as `role='widget'` or `role='structure'`) with concrete, supported roles; if no valid role applies, remove the attribute entirely so the browser falls back to the element's native semantics.
- Re-run the automated audit to confirm zero remaining `aria-roles` violations, then do a quick manual screen-reader test (NVDA+Firefox or VoiceOver+Safari) on any affected interactive components.
Fix it on your platform
Pick your platform for the exact steps.
How to fix aria roles on Shopify
- In your Shopify Admin, go to Online Store → Themes → click Actions → Edit code on your active theme.
- Use the search box (top-left of the code editor) to search for `role=` across all theme files.
- Click each result — most will be in `.liquid` files under `sections/`, `snippets/`, or `layout/theme.liquid`.
- In the file editor, locate the invalid role attribute (the scanner will have identified the specific value), correct or remove it, and click Save.
- For roles added by third-party Shopify apps, check the app's settings or contact the app developer — you cannot edit app-injected code directly.
- Verify the fix with a browser-based axe DevTools scan on the live storefront.
How to fix aria roles on WooCommerce
- In WordPress Admin, go to Appearance → Theme File Editor (or use a child theme and edit via FTP/SFTP).
- Search your active theme's `.php` template files and `functions.php` for `role=` — common locations are `header.php`, `footer.php`, page templates, and WooCommerce template overrides in `woocommerce/` within your theme folder.
- Edit the file containing the invalid role, correct the value (or remove the attribute), and click Update File.
- If the role is injected by a plugin, search for the offending plugin in wp-content/plugins/ and either configure it, update it, or contact its developer.
- Clear any caching plugins (e.g. WP Rocket, W3 Total Cache) after saving.
- Re-run axe or WAVE on the affected page to confirm the fix.
How to fix aria roles on BigCommerce
- In BigCommerce Admin, go to Storefront → Themes → click Customize on your active theme, then Advanced → Edit Theme Files.
- Use the file browser to search template files (`.html` Handlebars templates) for `role=` — check `templates/layout/base.html`, `templates/components/`, and `templates/pages/`.
- Correct the invalid role value in the appropriate file and save.
- For Stencil CLI users: edit the same files locally in your theme directory, then run `stencil push` to deploy.
- If the issue is in a BigCommerce widget or app, update the widget HTML in Page Builder (Content → Page Builder) or contact the app vendor.
- Preview and re-run axe to confirm the fix.
How to fix aria roles on Wix
- Wix does not expose raw HTML editing for most site elements; however, custom HTML can be injected via the HTML iframe widget (Add → Embed → Custom Code or HTML iFrame).
- If the invalid role is inside a custom HTML/embed block: open the HTML iFrame in the Wix Editor, click Enter Code, and correct or remove the `role` attribute.
- For roles added by Wix's own components, report the issue to Wix Support — you cannot directly edit core component markup.
- If you are using Wix Studio (Velo / Wix Studio advanced mode), open the relevant page, switch to Developer Mode, and edit the component properties in the Properties & Events panel or in Page Code to remove/correct the role.
- After updating, republish the site and recheck with axe DevTools.
How to fix aria roles on Squarespace
- Squarespace does not allow direct HTML editing of structural templates; invalid roles in core blocks must be reported to Squarespace Support.
- For roles inside Code Blocks or custom HTML you added yourself: in the Page Editor, click the Code Block, select Edit, find the `role=` attribute in your markup, correct it, and save.
- For site-wide custom code (e.g. injected via Settings → Advanced → Code Injection): go to Settings → Advanced → Code Injection, locate the snippet containing the invalid role, correct it, and save.
- Republish and verify with an axe browser extension on the live page.
How to fix aria roles on Webflow
- Open your project in the Webflow Designer.
- Select the element with the invalid role in the Navigator or on the canvas.
- In the right-hand Settings panel (gear icon), scroll to the Custom Attributes section.
- Find the `role` attribute entry, click it, and type the correct valid ARIA role value — or click the × to delete it if no valid role applies.
- Publish the site and re-run axe DevTools or WAVE to confirm the fix.
- For roles added inside Embed components (HTML Embed): click the Embed element on the canvas, open the embed editor, and correct the `role` attribute in the raw HTML.
How to fix aria roles on Adobe Commerce (Magento)
- Identify the template file responsible for the element by inspecting it in the browser (right-click → Inspect) and noting the block/template hint (enable template hints in Stores → Configuration → Advanced → Developer → Debug → Template Path Hints).
- Locate the `.phtml` template file in your custom theme directory under `app/design/frontend/<Vendor>/<Theme>/`, or find the core template at `vendor/magento/` and copy it to your theme to override it.
- In the template file, find the invalid `role=` attribute and correct or remove it.
- Run `bin/magento cache:clean` and `bin/magento cache:flush` to clear caches.
- If using Page Builder content, edit the block/row in Admin → Content → Pages or Blocks, switch to the HTML editor view, correct the role attribute, and save.
- Re-run axe or WAVE on the storefront page to verify the fix.
Does your site have this issue?
Run a free SEOLZ scan to find aria roles — and every other issue — across your whole site in minutes.
Scan my site freeFrequently asked questions
What is Aria roles?
The `role` attribute tells assistive technologies (screen readers, braille displays, voice control software) what kind of interface element something is — for example, a button, a navigation landmark, a dialog, or a list. The WAI-ARIA specification defines an exact list of allowed role names. If any element on your store carries a role that isn't on that list — whether it's a typo like `role="buton"`, an invented name like `role="product-card"`, or an outdated value like `role="presentation"` used incorrectly — the browser and screen reader simply ignore it or misinterpret the element entirely. WCAG Success Criterion 4.1.2 (Name, Role, Value) requires that every user interface component exposes a valid, programmatically determinable role so all users can understand and operate it.
Why does aria roles matter?
Screen reader users — who include people with visual impairments, motor disabilities, and cognitive disabilities — rely on role information to navigate and interact with your store. An invalid role means those customers hear confusing or missing announcements, cannot identify interactive controls, and may abandon your checkout or product pages. Beyond lost conversions, accessibility failures carry real legal risk: WCAG 2.1 AA compliance is referenced in ADA Title III lawsuits and, in many jurisdictions, is a statutory requirement for online businesses. Google also uses accessibility signals as a quality factor, so pages riddled with invalid ARIA can indirectly suppress organic rankings. Fixing invalid roles is typically a quick code change with outsized impact on both compliance and customer experience.
How do I fix aria roles?
Audit every element that has a `role` attribute and replace any invalid or misspelled role value with a valid WAI-ARIA role from the official specification.
Authoritative references
- How to fix this specific rule — Deque/axe (rule reference)
- WCAG 2 overview — W3C WAI
- ARIA basics — MDN