Aria required attr
Moderate effortFound on 2% of audited stores.
Add the required `aria-level` attribute (and any other missing required ARIA attributes) to every element that uses an ARIA role which mandates them.
What it is
ARIA (Accessible Rich Internet Applications) roles tell screen readers and assistive technologies what a piece of content is — for example, a heading, a slider, or a tree item. Many ARIA roles come with required attributes that must be present for the role to make sense. For instance, any element with `role="heading"` must also have `aria-level` (a number from 1–6) so assistive technology knows whether it's a top-level heading or a sub-heading. When a required attribute is missing, the ARIA role is effectively broken — like labelling a shelf "Aisle 3" but leaving out the aisle number.
Why it matters
Screen reader users — who are often unable to use a mouse and rely entirely on assistive technology — receive garbled or meaningless announcements when required ARIA attributes are absent. This directly blocks those users from understanding your page structure, navigating your store, or completing a purchase. Under WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value), all user interface components must expose correct role information to assistive technology; failing this criterion creates legal accessibility risk in the US (ADA), UK (Equality Act), EU (EAA), and beyond. Search engines also parse page structure using semantic signals — broken heading hierarchies and malformed ARIA can weaken how Googlebot understands and ranks your content.
How to fix it
- Identify every flagged element: open your browser's DevTools (F12), go to the Elements panel, and search for elements with a `role` attribute (e.g., `role="heading"`, `role="slider"`, `role="listbox"`).
- Look up which attributes are required for that role. For `role="heading"`, the required attribute is `aria-level` (integer 1–6). For `role="slider"`, you need `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`. Consult the W3C ARIA spec or Deque's rule reference for a full list per role.
- Add the missing attribute directly to the HTML element — for example, change `<div role="heading">` to `<div role="heading" aria-level="2">`, choosing the level that reflects the element's position in the page's heading hierarchy.
- If the flagged element is a native HTML element (like `<h1>`–`<h6>`), consider removing the redundant `role="heading"` entirely and relying on the semantic HTML tag instead — native elements carry their semantics automatically and never trigger this error.
- Re-test with a free browser extension such as axe DevTools or WAVE to confirm the violation no longer appears.
- Audit the rest of your store's templates (product pages, category pages, cart, checkout) to catch the same pattern wherever it recurs — missing required ARIA attributes often appear across a whole theme component.
<div role="heading" aria-level="2">Featured Products</div>
<!-- Better: use native HTML which never needs aria-level -->
<h2>Featured Products</h2>
<!-- Slider example: all three value attributes required -->
<div role="slider"
aria-valuenow="50"
aria-valuemin="0"
aria-valuemax="100"
aria-label="Price range">
</div>Fix it on your platform
Pick your platform for the exact steps.
How to fix aria required attr on Shopify
- In your Shopify Admin, go to Online Store → Themes → click the three-dot menu next to your active theme → Edit code.
- Use the search box (top of the file list) to search for 'role=' across all Liquid template files (.liquid) to find every element using an ARIA role.
- For each `role="heading"` without `aria-level`, add the attribute: `aria-level="2"` (or the appropriate level). If the element is already an `<h1>`–`<h6>` tag, remove the redundant `role` attribute instead.
- For third-party app sections (e.g., review widgets, sliders), contact the app developer or override the rendered HTML in the section's Liquid file if accessible.
- Save each file and preview the storefront; re-run axe DevTools in the browser to confirm the violation is resolved.
How to fix aria required attr on WooCommerce
- In your WordPress Admin, go to Appearance → Theme File Editor (or use a child theme and edit files via FTP/SFTP to avoid overwriting on updates).
- Search your theme's PHP/HTML template files (e.g., `header.php`, `page.php`, `woocommerce/` override templates) for `role=` attributes.
- Add the missing required attribute directly in the template markup, e.g., `<div role="heading" aria-level="2">`.
- If the violation is inside a plugin's output (e.g., a slider or product filter), check that plugin's settings for accessibility options, or open a support ticket with the plugin author.
- Install the free 'axe Accessibility Linter' browser extension and re-check the page to verify the fix.
How to fix aria required attr on BigCommerce
- In your BigCommerce Admin, go to Storefront → My Themes → click Customize on the active theme, then select Edit Theme Files (requires Stencil CLI or the in-browser editor).
- Search Handlebars (.html) template files for `role=` — common locations are `templates/components/`, `templates/pages/`, and `templates/layout/`.
- Add the missing `aria-level` (or other required attribute) to the flagged element in the correct template file.
- If using Page Builder widgets that inject the markup, switch that widget to a custom HTML widget and add the correct attributes there.
- Push the updated theme and verify with axe DevTools in your browser.
How to fix aria required attr on Wix
- Open the Wix Editor for your site. Click the element flagged (e.g., a text box or custom widget) to select it.
- Open Wix's Accessibility Settings panel: click the element → Settings (gear icon) → Accessibility.
- For custom-coded sections (Wix Velo / Corvid), open the Developer Tools panel, navigate to the relevant page code or public file, and locate the HTML/JSX where the ARIA role is set — add the missing attribute there.
- If the element is a native Wix component (e.g., a text element used as a heading), use the Design/Text panel to set it as a proper heading tag (H1–H6) instead of relying on a custom `role="heading"` — this removes the need for `aria-level` entirely.
- Publish the site and re-test with the axe browser extension.
How to fix aria required attr on Squarespace
- In the Squarespace Editor, go to Pages → select the page with the issue → click Edit.
- For standard blocks (text, image, etc.), switch the block type to the correct semantic element: use a 'Heading' text block rather than a 'Body' block styled to look like a heading — Squarespace will output the correct `<h2>` tag natively.
- For Code Blocks or custom HTML injections (Settings → Advanced → Code Injection or a Code Block), locate the element with `role=` and add the missing required attribute directly in that HTML snippet.
- For theme-level changes, go to Design → Custom CSS — note this controls style only; for markup changes use Code Injection or a Code Block.
- Save and publish, then verify with axe DevTools.
How to fix aria required attr on Webflow
- Open the Webflow Designer. Select the element flagged (e.g., a Div Block acting as a heading).
- In the right-hand Settings panel (the gear icon), scroll to the Custom Attributes section.
- Add the missing attribute: set the Name field to `aria-level` and the Value field to the correct integer (e.g., `2`). Click the + button to save it.
- Consider switching the element's HTML tag to a native heading tag (H1–H6) via the Tag dropdown at the top of the Settings panel — this makes the `role` and `aria-level` attributes unnecessary.
- Publish the site and verify with the axe DevTools browser extension.
How to fix aria required attr on Adobe Commerce (Magento)
- Identify the template file responsible for the flagged element: use the browser's DevTools to find a unique class or string, then search your theme under `app/design/frontend/<Vendor>/<Theme>/` using `grep -r 'role=' .`
- Copy the core template into your custom theme following Magento's template override convention (mirror the module path under your theme directory) to avoid editing core files.
- In the overridden `.phtml` template, add the missing required attribute to the HTML element, e.g., `<div role="heading" aria-level="2">`.
- If the violation is in a UI Component (`.html` KnockoutJS template), locate it under `Magento_*/view/frontend/web/template/` and apply the same override pattern.
- Run `bin/magento cache:clean` and `bin/magento setup:static-content:deploy`, then verify with axe DevTools.
Does your site have this issue?
Run a free SEOLZ audit to find aria required attr — and every other issue — across your whole site in minutes.
Scan my site freeFrequently asked questions
What is Aria required attr?
ARIA (Accessible Rich Internet Applications) roles tell screen readers and assistive technologies what a piece of content is — for example, a heading, a slider, or a tree item. Many ARIA roles come with required attributes that must be present for the role to make sense. For instance, any element with `role="heading"` must also have `aria-level` (a number from 1–6) so assistive technology knows whether it's a top-level heading or a sub-heading. When a required attribute is missing, the ARIA role is effectively broken — like labelling a shelf "Aisle 3" but leaving out the aisle number.
Why does aria required attr matter?
Screen reader users — who are often unable to use a mouse and rely entirely on assistive technology — receive garbled or meaningless announcements when required ARIA attributes are absent. This directly blocks those users from understanding your page structure, navigating your store, or completing a purchase. Under WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value), all user interface components must expose correct role information to assistive technology; failing this criterion creates legal accessibility risk in the US (ADA), UK (Equality Act), EU (EAA), and beyond. Search engines also parse page structure using semantic signals — broken heading hierarchies and malformed ARIA can weaken how Googlebot understands and ranks your content.
How do I fix aria required attr?
Add the required `aria-level` attribute (and any other missing required ARIA attributes) to every element that uses an ARIA role which mandates them.
Authoritative references
- How to fix this specific rule — Deque/axe (rule reference)
- WCAG 2 overview — W3C WAI
- ARIA basics — MDN