Fix guides · Accessibility
How to fix ARIA dialogs, fields and toggles without an accessible name
Custom pop-ups, dropdowns, switches and progress bars built with ARIA roles that screen readers can't name. How to label them.
- Time to fix
- 15–45 minutes
- Skill needed
- Developer
- Who notices
- Screen reader and voice-control users
Why it matters
Custom widgets use ARIA roles (dialog, combobox, switch, checkbox, progressbar, tooltip…) to tell assistive technology what they are. They also need a name that says what they're for.
Without one, a visitor hears "dialog" or "switch, off" with no idea which setting it is, or which pop-up just opened.
“Home pages with ARIA present had significantly more errors (59.1 on average) than pages without ARIA (42 on average).”
Before you start
- Your report shows each element and its role. Name it with aria-labelledby pointing at its visible heading or label, or with aria-label if there's no visible text.
- Dialogs: point aria-labelledby at the dialog's heading. Fields and toggles: use a real <label> where possible.
- Better still, use native HTML (<dialog>, <select>, <input type="checkbox">, <progress>), which is easier to label and works with the keyboard.
Fix it on your platform
Shopify
- Shopify's theme accessibility guidance asks drawers and modals to use role="dialog" and move focus to the element that labels them. If your theme's are unnamed, add aria-labelledby in its code or ask the theme developer.
- Pop-ups, quantity pickers and filters added by apps are fixed by the app's developer.
WordPress
- Check which plugin or theme part outputs the element (pop-up, cookie banner, slider, filter). Update it, or ask its developer to add a label.
Webflow
- For custom components, add aria-label or aria-labelledby in Element settings → Custom attributes. Webflow's built-in components are managed by Webflow.
Wix Managed by the platform
- Wix defines ARIA attributes for the elements it provides. If an app or your custom code is listed, add labels in that code, or remove it.
Squarespace Managed by the platform
- Squarespace generates the code for its own elements. If code injection or an extension is listed, add labels in that code; otherwise contact Squarespace support.
Next.js
- Label dialogs with their heading, and custom controls with their visible label.
<div role="dialog" aria-modal="true" aria-labelledby="newsletter-title">
<h2 id="newsletter-title">Get 10% off</h2>
</div>
<button role="switch" aria-checked={on} aria-label="Dark mode" onClick={toggle} />Any other site
- Give every element with a widget role a name with aria-labelledby or aria-label.
<div role="progressbar" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100" aria-label="Upload progress"></div>Check that it's fixed
- With a screen reader, open each widget: it should announce its name as well as its role.
- Re-run your StudioLNC audit: the elements should no longer be listed.
Find every issue like this on your site
Free audit of performance, accessibility, SEO and security, with fixes for your platform.