Accessible Name Debugger Guide: Fix the Names Screen Readers Announce

Sighted users read a button's label at a glance. Screen reader users hear its accessible name, and if that name is missing, duplicated or misleading, the control becomes confusing or invisible. The Accessible Name Debugger inspects elements and shows the accessible name a browser computes for each one, so you can find and fix naming problems before your users meet them.

The accessible name is a short text string that assistive technology uses to identify a control. It is not the same as the visible text, though visible text often supplies it. Browsers compute it through a defined order of sources, roughly: aria-labelledby first, then aria-label, then the element's own content or associated label, then title and placeholder as fallbacks in some cases. That order matters, because a well-meaning aria-label can override visible text, creating a mismatch that confuses voice control users, who speak the visible label, and screen reader users, who hear the aria-label. When the two differ, both groups lose.

Different controls get their names differently. A button's name usually comes from its text content. A link's name comes from its text, or from the alt text of an image inside it. A form input's name comes from its associated label element, or from aria-label or aria-labelledby. An image that acts as a button needs alt text that names the action, not the picture. Icon-only buttons, a search magnifier or a hamburger menu with no text, have no content to draw on, so they need an explicit aria-label. Placeholder text is not a reliable name: it disappears when the user types, and some assistive technologies do not treat it as a name at all.

To debug with the tool, enter or point it at the markup or page you want to check, then read the computed name for each interactive element. Work through a checklist for each control: does it have a name at all, does the name describe the action, is the name unique where several similar controls exist, and does it match the visible label where there is one? A page with three buttons all named Read more fails the uniqueness test even though each has a name; a screen reader user tabbing through them cannot tell which article each opens. Rename them with context, such as Read more about patio lighting, or use aria-labelledby to include the heading.

A worked example you can follow

Consider a sample search button that contains only a magnifier icon and no text. Without any label, its computed accessible name is empty, so a screen reader announces it as an unnamed button, and the user has no idea what it does. Add aria-label with the value Search, and the debugger now reports the accessible name as Search, which is a clear, single-word action. Now consider a second sample: a visible button labelled Subscribe, but with an aria-label of Sign up now. The debugger reports Sign up now, because aria-label outranks content, and the visible and announced labels now disagree. A voice control user saying click Subscribe will fail, because the control's usable name is the aria-label. The fix is to remove the aria-label or change it to Subscribe, so visible and announced names match. In both samples, the debugger makes the invisible computation visible, and the fix is a one-line change once you see it.

Test the fix the way a user would. Tab through the page with a keyboard and confirm every interactive element announces a sensible name. Check repeated controls: pagination links, product cards and table actions are the usual sources of duplicated names. Check dynamic content too: a button whose label changes from Play to Pause should announce the new state, and a control added by JavaScript after page load still needs a name at the moment it appears. Automated checks catch the empty names; manual keyboard and screen reader passes catch the misleading ones.

Common mistakes to avoid

The most common mistake is leaving icon-only controls unnamed, especially close buttons, menu toggles and social share icons. A second mistake is writing aria-labels that duplicate the visible text with extra marketing words, creating the mismatch described above. A third mistake is using title attributes as the only name, since title tooltips are inconsistently exposed and often invisible to keyboard users. A fourth mistake is giving decorative images meaningful alt text, which clutters the screen reader experience, or giving meaningful images empty alt text, which hides information. A fifth mistake is assuming a passing automated scan means the names are good: a name can exist yet be useless, such as button, link or click here repeated twenty times.

Good names are short, action-oriented and specific. Prefer Search over Search the site for something, and Read more about winter patios over Read more where the context is missing. Keep the visible label inside the accessible name when both exist: if the visible text is Add to basket, the accessible name should start with or contain Add to basket. Pair naming checks with the Accessibility Contrast Matrix for legibility and the Colour Converter for colour value handling. Accessibility tools help check common issues but do not guarantee compliance; a pass from a debugger is a step, not a certificate.

Frequently asked questions

What is the difference between accessible name and accessible description? The name identifies the control, such as Search. The description adds extra detail, such as Password must be at least 8 characters. Both help, but the name is the essential one, and a control without a name is broken even if it has a description.

Should every element have an accessible name? No. Only interactive elements and meaningful images need names. Decorative elements should be hidden from assistive technology, not given empty or redundant names.

Is aria-label always the right fix? No. A visible label element is usually better for form inputs, and text content is usually better for buttons. Use aria-label when there is no visible text to use, such as an icon-only control, and keep it consistent with any visible hint.

For a related accessibility topic, see PDF Accessibility Checker Guide. Names are small strings with large consequences: get them right, and every control on the page becomes usable to everyone who meets it.