Aria required attr
Moderate effortFound on 4% of audited stores.
Add all required ARIA attributes (such as aria-expanded and aria-controls) to every interactive element that uses an ARIA role, so assistive technologies can communicate widget state to users.
What it is
ARIA (Accessible Rich Internet Applications) roles tell screen readers and other assistive technologies what kind of widget an element is — for example, a button that opens a dropdown, a tab panel, or an accordion. Each ARIA role has a defined set of required attributes that must also be present for the widget to make sense. For instance, a button that expands a menu must include `aria-expanded` (so the screen reader can announce "expanded" or "collapsed") and typically `aria-controls` (so it points to the element it controls). When those required attributes are missing, the role declaration is incomplete and the assistive technology cannot convey the correct state or relationship to the user.
Why it matters
Screen reader users — who often navigate by keyboard only — rely entirely on ARIA state attributes to know whether a menu is open, a tab is selected, or an accordion panel is visible. Without `aria-expanded`, a screen reader user has no way to know whether a dropdown they just activated is open or closed. Without `aria-controls`, they may not find the content that just appeared. This directly breaks the shopping experience for blind and low-vision customers. WCAG 2.x Success Criterion 4.1.2 (Name, Role, Value) is a Level AA requirement, meaning it is referenced in most accessibility laws worldwide (ADA, Section 508, EN 301 549, AODA). Failing it exposes your store to legal complaints and demand letters. It also signals to Google's quality systems that the site has usability issues, which can indirectly affect organic rankings.
How to fix it
- Identify every element flagged with a missing required ARIA attribute — note its role (e.g. button, combobox, tab, listbox) and which attributes are missing (e.g. aria-expanded, aria-controls, aria-selected).
- Look up the required attributes for that role in the ARIA specification: for example, a role='button' that toggles content requires aria-expanded; a role='combobox' requires aria-expanded and aria-controls; a role='tab' requires aria-selected.
- Add the missing attribute(s) directly to the HTML element, setting the correct initial value — e.g. aria-expanded='false' when the controlled panel starts closed, and the id of the target element in aria-controls.
- Wire up any interactive JavaScript so the attribute value updates dynamically when the widget state changes — e.g. toggle aria-expanded between 'true' and 'false' each time the user opens or closes the element.
- Verify the fix: open the page with a screen reader (NVDA+Firefox on Windows, VoiceOver+Safari on Mac/iOS) and confirm the state is announced correctly when the widget is activated.
- Re-run your automated accessibility scanner (axe, WAVE, or Lighthouse) to confirm the aria-required-attr violation is resolved.
Fix it on your platform
Pick your platform for the exact steps.
How to fix aria required attr on Shopify
- From your Shopify admin, go to Online Store → Themes → (your active theme) → Actions → Edit code.
- In the 'Sections' or 'Snippets' folder, open the file that renders the component with the missing attribute — common culprits are header.liquid (navigation dropdowns), predictive-search.liquid (search combobox), or any accordion/FAQ section.
- Find the HTML element with the ARIA role (e.g. <button role='button'> or <div role='combobox'>) and add the missing attributes: aria-expanded='false' and/or aria-controls='target-element-id'.
- Open the corresponding JavaScript file (usually assets/theme.js or assets/[component-name].js) and find the toggle function. Add a line that updates the attribute on state change: element.setAttribute('aria-expanded', isOpen ? 'true' : 'false').
- Save both files, then preview the theme and test with a screen reader or the axe browser extension.
How to fix aria required attr on Shopify Plus
- Same as Shopify above; Shopify Plus also allows customisation via the Checkout editor — for checkout-page widgets, go to Settings → Checkout → Customize and inspect the checkout liquid files in your theme code editor.
- For headless Shopify Plus storefronts (Hydrogen/custom), locate the React/Vue component responsible for the interactive widget and add the ARIA attributes as props, then wire the state variable to aria-expanded.
How to fix aria required attr on WooCommerce
- In your WordPress admin, go to Appearance → Theme File Editor (or use a child theme via FTP/SFTP).
- Locate the template file for the affected component — e.g. header.php, functions.php-registered navigation menus, or a block template in /templates/.
- Add aria-expanded='false' and aria-controls='[target-id]' to the relevant HTML element in the template.
- If the toggle behaviour comes from a plugin (e.g. a mega-menu or accordion plugin), check the plugin's settings panel for built-in ARIA options first; if none exist, enqueue a small custom JS file via functions.php that patches the attribute on page load and toggle.
- Alternatively, install the 'WP Accessibility' plugin (by Joe Dolson), which patches common ARIA issues in nav menus automatically.
- Test with the axe DevTools browser extension.
How to fix aria required attr on BigCommerce
- In your BigCommerce admin, go to Storefront → My Themes → (active theme) → Advanced → Edit Theme Files.
- Locate the Handlebars template responsible for the widget — typically templates/components/header/navigation.html for nav dropdowns or templates/components/search/quick-search.html for the search combobox.
- Add aria-expanded='false' and aria-controls='target-id' to the trigger element in the template markup.
- Open assets/js/theme/ and find the matching JavaScript module (e.g. header.js or search.js). In the toggle handler, add: this.$trigger.attr('aria-expanded', isOpen ? 'true' : 'false');
- Bundle and preview the theme changes, then verify with the axe browser extension.
How to fix aria required attr on Wix
- Wix's standard drag-and-drop editor has limited direct HTML access. First check if the affected widget (e.g. a menu or accordion) is a native Wix component — if so, check Wix's support pages for any built-in accessibility settings or contact Wix support, as they occasionally push fixes via platform updates.
- If using Wix Editor X / Wix Studio, open the page, select the element, go to the Settings or Accessibility panel in the right sidebar to see if aria properties can be set there.
- For custom-coded elements, use Wix Velo (Dev Mode): enable Dev Mode from the top bar, select the element, and in the Properties & Events panel set the aria attributes via code: $w('#myButton').setAttribute('aria-expanded', 'false'); and update on click.
- To dynamically toggle: in Wix Velo, write an onClick handler that reads the current value and toggles it: $w('#myButton').setAttribute('aria-expanded', currentState ? 'true' : 'false');
- Preview and test with a browser-based accessibility checker such as the axe extension.
How to fix aria required attr on Squarespace
- Squarespace does not allow direct editing of most core HTML. Go to Website → Pages → (your page) → Edit, and check if the component has any built-in accessibility options in its block settings.
- For nav dropdowns, go to Design → Navigation and confirm you are using Squarespace's native navigation, which should include ARIA attributes — if it does not, your template version may be outdated; check for template updates under Design → Template.
- For custom-coded blocks (Code Blocks or Custom HTML injection): go to Settings → Advanced → Code Injection, or open the Code Block directly, and manually add aria-expanded and aria-controls to your markup, plus a small <script> tag to toggle the value.
- If you use a third-party Squarespace plugin for accordions or menus, check that plugin's documentation for ARIA support or contact the plugin vendor.
- Test the result with the WAVE browser extension.
How to fix aria required attr on Webflow
- Open your project in the Webflow Designer and select the element that triggers the widget (e.g. the button or link that opens a dropdown or accordion panel).
- In the right-hand Element Settings panel (the gear icon), scroll to the Custom Attributes section and click the '+' button.
- Add the attribute name aria-expanded and set its value to false (or true if the widget starts open).
- Add a second custom attribute: aria-controls with the value set to the HTML ID of the panel it controls (set that ID on the target element via its Element Settings as well).
- Open the Interactions panel and, within your existing open/close interaction, add a 'Set Attribute' action that changes aria-expanded to 'true' on open and 'false' on close.
- Publish the site and verify with the axe DevTools browser extension.
How to fix aria required attr on Adobe Commerce (Magento)
- Identify the PHTML template or UI Component responsible for the flagged element — common locations are Magento_Theme/templates/html/header.phtml, Magento_Catalog/templates/navigation/top.phtml, or a third-party module's template.
- Open the file via app/design/frontend/[Vendor]/[theme]/[Module_Name]/templates/ (always work in a custom theme, never core files).
- Add aria-expanded='false' and aria-controls='target-element-id' to the trigger element in the template.
- Locate the corresponding requireJS module (usually lib/web/mage/menu.js or a custom module's JS) and in the toggle/activate method add: $(trigger).attr('aria-expanded', isOpen ? 'true' : 'false');
- Run bin/magento setup:static-content:deploy and flush the cache (bin/magento cache:flush), then test with the axe extension.
How to fix aria required attr on Magento Open Source
- Follow the same steps as Adobe Commerce above — template overrides in app/design/frontend/[Vendor]/[theme]/, JS customisation via requireJS mixins, and static content deployment after changes.
How to fix aria required attr on Headless / Custom (I build in code)
- Find the component that renders the interactive widget (e.g. a Dropdown, Accordion, Combobox, or Tab component).
- Add aria-expanded={isOpen} (boolean → React converts to 'true'/'false') and aria-controls='target-element-id' to the trigger element's JSX/HTML.
- Ensure the controlled element has the matching id attribute.
- Wire the isOpen state variable (or equivalent) so it updates correctly on user interaction.
- Test with axe-core (npm package) in your CI pipeline or use the axe DevTools browser extension manually.
Does your site have this issue?
Run a free SEOLZ scan 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 other assistive technologies what kind of widget an element is — for example, a button that opens a dropdown, a tab panel, or an accordion. Each ARIA role has a defined set of required attributes that must also be present for the widget to make sense. For instance, a button that expands a menu must include `aria-expanded` (so the screen reader can announce "expanded" or "collapsed") and typically `aria-controls` (so it points to the element it controls). When those required attributes are missing, the role declaration is incomplete and the assistive technology cannot convey the correct state or relationship to the user.
Why does aria required attr matter?
Screen reader users — who often navigate by keyboard only — rely entirely on ARIA state attributes to know whether a menu is open, a tab is selected, or an accordion panel is visible. Without `aria-expanded`, a screen reader user has no way to know whether a dropdown they just activated is open or closed. Without `aria-controls`, they may not find the content that just appeared. This directly breaks the shopping experience for blind and low-vision customers. WCAG 2.x Success Criterion 4.1.2 (Name, Role, Value) is a Level AA requirement, meaning it is referenced in most accessibility laws worldwide (ADA, Section 508, EN 301 549, AODA). Failing it exposes your store to legal complaints and demand letters. It also signals to Google's quality systems that the site has usability issues, which can indirectly affect organic rankings.
How do I fix aria required attr?
Add all required ARIA attributes (such as aria-expanded and aria-controls) to every interactive element that uses an ARIA role, so assistive technologies can communicate widget state to users.