How to Give ARIA Widgets Accessible Names? Complete Guide (2026)

Why Accessible Names on Widgets Matter

ARIA widgets are usually the most interactive parts of a page — they are dialogs that interrupt the flow, tooltips that add context, progress indicators that report long-running work. When they have no name, screen-reader users hit a wall the moment focus enters the widget.

• Dialogs become "dialog":A modal that opens with no name is announced as "dialog" with no further information. The user has no idea whether it is a confirmation, a sign-up form, or an error.
• Progress bars stop reporting purpose: A bar at 65% is meaningless without context. Is it a file upload? A multi-step form? A video buffer? The accessible name carries that meaning.
• Trees become unnavigable: Tree widgets (file explorers, nested category pickers) rely on each treeitem being announced by name. Unnamed items collapse the entire structure into a featureless list.
• Menu items become silent: A menuitem with no text content and no aria-labelis announced as just "menu item," making keyboard navigation through a menu impossible.
• WCAG 4.1.2 violations: Name, Role, Value is Level A — the most basic conformance bar. Missing names are also frequently cited in US ADA and EU European Accessibility Act (in force June 2025) lawsuits.
• AI search visibility: AI answer engines parse the accessibility tree to understand interactive structure on a page. Widgets without names degrade the structured signals that platforms like Google AI Overviews and Perplexity use when picking citations.

The Three Ways to Name a Widget

The W3C's Accessible Name and Description Computation algorithm walks through several sources of a name in order. For ARIA widgets, three sources matter in practice:

The First Rule of ARIA still applies: if a native HTML element exists (<dialog>, <progress>, <meter>), prefer it. The naming rules below apply equally — native elements with no accessible name fail the same audits.

How to Fix Each of the Six Audits

<!-- BAD: opens as just "dialog" -->
<div role="dialog" aria-modal="true">
  <h2>Delete account</h2>
  <p>This action cannot be undone.</p>
</div>

<!-- GOOD: heading provides the name -->
<div role="dialog" aria-modal="true" aria-labelledby="del-title">
  <h2 id="del-title">Delete account</h2>
  <p>This action cannot be undone.</p>
</div>

<!-- GOOD: native <dialog> with the same association -->
<dialog aria-labelledby="del-title">
  <h2 id="del-title">Delete account</h2>
</dialog>

<!-- BAD: empty tooltip element -->
<button aria-describedby="tip-1">Save</button>
<div id="tip-1" role="tooltip"></div>

<!-- GOOD: tooltip has visible text content -->
<button aria-describedby="tip-1">Save</button>
<div id="tip-1" role="tooltip">Saves and continues to step 2</div>

<!-- BAD: announced as "65%, progress bar" — but progress on what? -->
<div role="progressbar" aria-valuenow="65" aria-valuemin="0" aria-valuemax="100"></div>

<!-- GOOD: visible label with aria-labelledby -->
<span id="upload-label">Uploading attachment</span>
<div role="progressbar"
     aria-labelledby="upload-label"
     aria-valuenow="65" aria-valuemin="0" aria-valuemax="100"></div>

<!-- GOOD: native <progress> with <label> -->
<label for="up">Uploading attachment</label>
<progress id="up" value="65" max="100"></progress>

<!-- BAD: just "0.6, meter" -->
<div role="meter" aria-valuenow="0.6" aria-valuemin="0" aria-valuemax="1"></div>

<!-- GOOD: aria-label on the role -->
<div role="meter"
     aria-label="Disk usage"
     aria-valuenow="0.6" aria-valuemin="0" aria-valuemax="1"
     aria-valuetext="60%"></div>

<!-- GOOD: native <meter> with <label> -->
<label for="disk">Disk usage</label>
<meter id="disk" value="0.6" min="0" max="1">60%</meter>

<!-- BAD: icon-only treeitem with no name -->
<li role="treeitem">
  <svg aria-hidden="true">...</svg>
</li>

<!-- GOOD: visible text inside the treeitem -->
<li role="treeitem">Q4 reports</li>

<!-- GOOD: aria-labelledby when the row has more than one piece of text -->
<li role="treeitem" aria-labelledby="row-12-name">
  <svg aria-hidden="true">...</svg>
  <span id="row-12-name">Q4 reports</span>
  <button>Rename</button>
</li>

<!-- BAD: icon-only menuitem -->
<li role="menuitem">
  <svg aria-hidden="true">...</svg>
</li>

<!-- GOOD: visible text -->
<li role="menuitem">Duplicate</li>

<!-- GOOD: icon-only with aria-label -->
<li role="menuitem" aria-label="Duplicate">
  <svg aria-hidden="true">...</svg>
</li>

<!-- GOOD: menuitemcheckbox with state and name -->
<li role="menuitemcheckbox" aria-checked="true">Show ruler</li>

How to Check Your Pages

• Greadme deep scan — runs all six naming audits, lists each unnamed widget with the role it is using, and offers a one-click GitHub PR fix where applicable.
• Greadme crawler scan — finds repeated naming bugs across templates (a single broken modal component will fail on every page that mounts it).
• Greadme AI visibility analyzer — surfaces how clean accessible names affect how AI answer engines interpret interactive structure on your pages.
• Chrome DevTools → Accessibility tab — select any element and look at the "Name" field. If it is empty for a widget that needs one, the audit will fail.
• axe-core (the open-source rules engine) — integrates into Jest, Playwright, and Cypress so CI fails on any unnamed widget before merge.
• Manual screen-reader test — open the page in NVDA (Windows), VoiceOver (macOS/iOS), or TalkBack (Android). If a widget is announced by role only, it has no accessible name.

Bad vs Good: Side-by-Side Examples

All six naming audits, with the most common bad version and the simplest good version:

10 Rules for Reliable Accessible Names

Common Mistakes and How to Avoid Them

FAQ

What does the aria-dialog-name audit check?

It verifies that every element with role="dialog" or role="alertdialog" (and the native <dialog> element) has an accessible name. The most common pass is aria-labelledbypointing at the dialog's heading.

Can I use aria-label and aria-labelledby together?

You can, but aria-labelledby wins. The Accessible Name and Description Computation algorithm treats aria-labelledby as a higher-priority source than aria-label. To avoid confusion, choose one.

Does a native <dialog> or <progress> element still need an explicit name?

Yes. The role is implicit, but the name still has to come from somewhere — visible heading, <label> association, aria-labelledby, or aria-label. Native semantics do not invent a name for you.

Is a missing accessible name a WCAG failure?

Yes — Success Criterion 4.1.2 Name, Role, Value (Level A). It is also one of the most-cited failures in WebAIM's annual home-page audits and in US ADA / EU European Accessibility Act litigation.

Why does my icon-only menuitem fail aria-command-name even with a title?

The HTML title attribute is unreliable as an accessible name source — many mobile screen readers do not surface it, and accessibility checkers do not count it as a guaranteed name. Use aria-label instead, or include visible text.

What is the difference between progressbar and meter?

A progressbar represents a process moving toward completion (file upload, multi-step form). A meter represents a static measurement at a point in time (disk usage, password strength). They have separate audits — aria-progressbar-name and aria-meter-name — but the naming rules are identical.

Do unnamed widgets affect AI search engines like Perplexity and ChatGPT?

Indirectly. AI answer engines parse the accessibility tree and semantic HTML to understand the structure of your pages. Widgets with no accessible name produce a noisier tree, weaker structured signals, and worse rankings in traditional Google search — and AI answer engines preferentially cite pages that already rank well.