Aria dialog name
Moderate effortFound on 4% of audited stores.
Add a visible or programmatic accessible name to every dialog element so screen readers can announce what the dialog is about when it opens.
What it is
Any popup, modal, or overlay that uses `role="dialog"` or `role="alertdialog"` must have an accessible name — a short label that tells users what the dialog is for. This name is provided either by pointing to the dialog's own heading with `aria-labelledby`, or by writing the label directly into an `aria-label` attribute on the dialog element itself. Without it, a screen reader user hears something like "dialog" with no context when the popup opens, giving them no idea whether it's a cart, a cookie notice, a sign-in prompt, or anything else.
Why it matters
Screen reader users — including many people with visual impairments — rely entirely on the announced name of a dialog to orient themselves when it opens. A nameless dialog is effectively invisible to them: they may not know a popup has appeared, what it contains, or how to close it, which can block them from completing a purchase or any other task. This violates WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value) at Level A — the most basic level of conformance — creating real legal exposure under the ADA (US), EN 301 549 (EU), and equivalent laws in many other countries. Fixing it also signals to Google that your site is well-structured, and it prevents cart-abandonment from users who cannot interact with a broken modal (e.g., a checkout popup or cookie consent dialog).
How to fix it
- Locate every element in your site's HTML or theme templates that has role="dialog" or role="alertdialog" (also check <dialog> HTML elements).
- Check whether the dialog has a visible heading (e.g., an <h2> inside it). If yes, give that heading a unique id (e.g., id="cart-dialog-title") and add aria-labelledby="cart-dialog-title" to the dialog element — this is the preferred method because it uses text already on screen.
- If there is no visible heading, add an aria-label attribute directly to the dialog element with a concise, descriptive name (e.g., aria-label="Shopping cart").
- Never leave aria-label empty (aria-label="") — that is treated the same as having no label at all.
- Test with a screen reader (NVDA + Firefox on Windows, VoiceOver on macOS/iOS, TalkBack on Android): open the dialog and confirm the name is announced immediately when focus moves into it.
- Re-run your accessibility scanner to confirm the aria-dialog-name violation is resolved.
Fix it on your platform
Pick your platform for the exact steps.
How to fix aria dialog name on Shopify
- In your Shopify admin, go to Online Store → Themes → click the (…) menu next to your active theme → Edit code.
- Search across all .liquid files for 'role="dialog"' or 'role="alertdialog"' using the search box in the code editor (or look in sections/cart-drawer.liquid, sections/header.liquid, assets/theme.js for modal templates).
- For each match, find the visible heading inside the modal (e.g., <h2>Shopping cart</h2>), add a unique id to it (e.g., id="cart-dialog-title"), then add aria-labelledby="cart-dialog-title" to the element with role="dialog".
- If there is no heading, add aria-label="Cart" (or an appropriate name) directly to the role="dialog" element.
- Save the file and preview the theme. Use a screen reader or the axe DevTools browser extension to verify the dialog announces its name correctly.
How to fix aria dialog name on WooCommerce
- Identify which plugin or theme generates the dialog: common sources are WooCommerce core (mini-cart drawer), popup plugins (e.g., Elementor Popup, Ninja Popups), or your theme (e.g., Storefront, Flatsome).
- For theme-generated modals, go to Appearance → Theme File Editor (or use a child theme) and locate the template file rendering the dialog (e.g., header.php, woocommerce/cart/mini-cart.php).
- Add a unique id to the dialog's heading and add aria-labelledby="that-id" to the element with role="dialog"; or add aria-label="Mini cart" if no heading exists.
- For plugin-generated popups, check the plugin's settings for an 'Accessibility' or 'ARIA label' field; if none exists, add the attribute via a small JavaScript snippet in Appearance → Customize → Additional CSS/JS or in your child theme's functions.php using wp_add_inline_script.
- Clear any caching plugins (e.g., WP Rocket, W3 Total Cache) and verify with a screen reader or axe browser extension.
How to fix aria dialog name on BigCommerce
- Go to Storefront → Themes → click Customize on your active theme, then switch to the Edit Theme Files tab (available in Stencil themes via the Theme Editor or locally via Stencil CLI).
- Search template files (templates/components/ and templates/pages/) for role="dialog" — common locations are the cart preview modal, search overlay, and age-gate popups.
- Add a unique id to the heading inside each dialog and add aria-labelledby="that-id" to the role="dialog" element, or add aria-label="[Dialog purpose]" if there is no heading.
- Commit and push changes if using Stencil CLI (stencil push), or save directly in the Theme Editor.
- Preview changes and test with the axe DevTools browser extension.
How to fix aria dialog name on Wix
- Open the Wix Editor for your site.
- Wix generates dialogs (lightboxes) via Add → Lightbox. Click on the lightbox component to select it.
- Open the lightbox settings panel. In the Accessibility section (if available in your plan), enter a descriptive name in the 'ARIA label' field.
- If no ARIA label field is available, add a prominent text element at the top of the lightbox that serves as a heading — Wix's accessibility engine will use it as the accessible name in many cases.
- For custom coded dialogs in Velo (Wix's dev platform), open the page code, locate the dialog element, and set element.accessibility.ariaLabel = 'Your dialog name'; or element.accessibility.ariaLabelledBy = headingElement.
- Publish the site and verify with the axe DevTools browser extension.
How to fix aria dialog name on Squarespace
- Squarespace popups (Promotional Pop-Ups and Quick View panels) are generated by the platform. Go to Pages → Not Linked → Promotional Pop-Up (or Marketing → Promotional Pop-Up) to configure your popup content.
- Add a descriptive heading block as the first element inside the popup so it serves as a visible title.
- To inject the ARIA attribute, go to Settings → Advanced → Code Injection and add a small JavaScript snippet that runs after page load to set aria-labelledby or aria-label on the dialog element (see code snippet below).
- For Quick View dialogs on product pages, use the same Code Injection approach targeting the Quick View modal's role="dialog" element.
- After publishing, verify with the axe DevTools browser extension in a real browser.
How to fix aria dialog name on Webflow
- In the Webflow Designer, click on the modal/dialog element in the Navigator panel to select it.
- Open the Element Settings panel (the gear icon on the right) and scroll to the Custom Attributes section.
- If the dialog has a visible heading inside it: give the heading element an HTML id (e.g., modal-title) via its own Custom Attributes, then add the attribute aria-labelledby with value modal-title to the dialog wrapper element.
- If there is no visible heading, add the attribute aria-label with a descriptive value (e.g., 'Newsletter signup') directly to the dialog wrapper element.
- Publish the site and confirm the fix using the axe DevTools browser extension.
How to fix aria dialog name on Adobe Commerce (Magento)
- Locate the modal template in your theme: app/design/frontend/<Vendor>/<theme>/Magento_Ui/templates/modal/modal-popup.html (or modal-slide.html).
- Find the root element that has role="dialog" (or data-role="modal") and add aria-labelledby="{{ data.modalTitleId }}" if a title element already exists in the template with a matching id, which is the Magento modal component's built-in support.
- If the title element exists but lacks an id, add id="{{ data.modalTitleId }}" to the heading element inside the template.
- If no title is present, add aria-label="{{ data.title }}" to the root dialog element so the component's configured title string is used.
- Run bin/magento cache:flush and bin/magento setup:static-content:deploy, then verify with the axe DevTools browser extension.
How to fix aria dialog name on Shopify Plus
- Shopify Plus uses the same theme-editing flow as standard Shopify.
- Go to Online Store → Themes → Edit code, then locate your dialog/modal/cart-drawer Liquid snippets (e.g. snippets/cart-drawer.liquid, snippets/modal.liquid).
- If you use a custom storefront or headless build via Shopify Storefront API, edit the React/Vue/Svelte component that renders the modal and add aria-labelledby or aria-label to the outermost dialog element.
- For third-party apps that inject dialogs (e.g. upsell popups), contact the app developer or use a custom Script Tag / Theme App Extension to patch the ARIA attributes after the element is inserted into the DOM.
- Verify with axe DevTools or a screen reader after each change.
How to fix aria dialog name on Wix Studio
- In Wix Studio, enable Dev Mode from the top toolbar.
- Select the panel, popup, or lightbox component that acts as a dialog.
- In the Properties & Events panel, check whether an aria-label field is available directly on the component (Wix Studio is expanding native ARIA support — check the latest release notes).
- If no native field exists, use the page's JavaScript code panel to target the rendered dialog element after it opens and set aria-label or aria-labelledby programmatically, similar to the Velo approach for standard Wix.
- Test using axe DevTools in your browser while previewing the published or staged site.
Does your site have this issue?
Run a free SEOLZ scan to find aria dialog name — and every other issue — across your whole site in minutes.
Scan my site freeFrequently asked questions
What is Aria dialog name?
Any popup, modal, or overlay that uses `role="dialog"` or `role="alertdialog"` must have an accessible name — a short label that tells users what the dialog is for. This name is provided either by pointing to the dialog's own heading with `aria-labelledby`, or by writing the label directly into an `aria-label` attribute on the dialog element itself. Without it, a screen reader user hears something like "dialog" with no context when the popup opens, giving them no idea whether it's a cart, a cookie notice, a sign-in prompt, or anything else.
Why does aria dialog name matter?
Screen reader users — including many people with visual impairments — rely entirely on the announced name of a dialog to orient themselves when it opens. A nameless dialog is effectively invisible to them: they may not know a popup has appeared, what it contains, or how to close it, which can block them from completing a purchase or any other task. This violates WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value) at Level A — the most basic level of conformance — creating real legal exposure under the ADA (US), EN 301 549 (EU), and equivalent laws in many other countries. Fixing it also signals to Google that your site is well-structured, and it prevents cart-abandonment from users who cannot interact with a broken modal (e.g., a checkout popup or cookie consent dialog).
How do I fix aria dialog name?
Add a visible or programmatic accessible name to every dialog element so screen readers can announce what the dialog is about when it opens.
Authoritative references
- How to fix this specific rule — Deque/axe (rule reference)
- WCAG 2 overview — W3C WAI
- ARIA basics — MDN