· Development

aria-label or aria-labelledby: which accessible name wins?

Browsers compute an accessible name in a defined order. See how aria-labelledby, aria-label, label, and placeholder rank, with common mistakes checked against W3C documents.

DevelopmentAccessibility

A button says “Search” on screen, but a screen reader announces “Find on this site, button.” The markup contains aria-label="Find on this site". This is not a browser error. It is the result of the accessible-name calculation.

The name follows a defined order

W3C’s Accessible Name and Description Computation (AccName) 1.2 defines the algorithm in section 4.3.2. Its branches vary by element and role, but this is the common order developers encounter:

  1. Text from elements referenced by aria-labelledby
  2. A non-empty aria-label
  3. Native HTML naming such as <label> or alt
  4. Descendant text for roles that take their name from content, such as buttons and links
  5. A tooltip attribute such as title

Once an earlier step supplies a name, later candidates are not automatically appended. Add aria-label to an input that already has a <label for>, and the visible label can disappear from the accessible name. HTML-AAM’s rule for text inputs puts placeholder after title. That is one reason a placeholder is not a substitute for a label.

aria-labelledby joins references in order

aria-labelledby can contain several space-separated IDs. Text calculated from those references is joined in the listed order. Here is a shortened AccName example:

<a id="file1" href="/files/a.pdf">a.pdf</a>
<span role="button" tabindex="0" id="del1"
      aria-label="Delete" aria-labelledby="del1 file1"></span>

The button references itself first. During that traversal, the algorithm does not follow the same aria-labelledby again, so aria-label supplies “Delete.” The file name follows, producing “Delete a.pdf.”

Two related rules are easy to miss. An element hidden with hidden or display: none can still supply name text when aria-labelledby references it directly. References also do not recurse without limit. If A points to B and B points to C, B’s aria-labelledby is not followed while the algorithm computes A’s name.

Which attribute should you use?

WAI-ARIA 1.2 says authors SHOULD use aria-labelledby, and SHOULD NOT use aria-label, when the label text exists in the DOM. For form controls, consider native HTML such as <label for> before ARIA. The ARIA Authoring Practices Guide (APG) likewise recommends visible text and native HTML first. A native <label> also activates its control when clicked; an ordinary element referenced by aria-labelledby does not gain that behavior.

aria-label fits an icon-only button when a visible label is not practical:

<button type="button" aria-label="Close">
  <svg aria-hidden="true">…</svg>
</button>

When the visible text and name disagree

WCAG 2.2 Success Criterion 2.5.3, Label in Name (Level A), requires the accessible name of a user-interface component with a text label to contain the visible text. Speech-input users say the words they can see. If the “Search” button above is named only “Find on this site,” it fails this criterion. Removing the unnecessary aria-label so the visible text supplies the name is the simplest repair. The Understanding document calls placing the visible label at the start of the name a best practice.

Nor can aria-label name every element. HTML-AAM maps a <div> or <span> without another role to generic; WAI-ARIA 1.2 lists generic among roles that cannot be named. An aria-label on such an element is not allowed by the specification.

Translation needs deliberate handling too. WAI-ARIA 1.2 classifies aria-label as translatable, and the HTML Standard recognizes attributes that other specifications define as translatable, using aria-label as an example. Extraction tools still vary, so verify that your localization pipeline collects ARIA attribute values or place those strings in explicit translation resources.

Chrome DevTools shows the computed name under Computed Properties in the Accessibility pane. That is useful for inspection, but APG warns that prohibited or unspecified patterns may appear to work in some browsers without being consistent. Test with assistive technology as well.

This article reflects documents checked on October 7, 2026. AccName 1.2 and HTML-AAM are Working Drafts, so step names and details may change. The precedence of aria-labelledby over aria-label also appears in WAI-ARIA 1.2, which is a W3C Recommendation.

Sources: AccName 1.2, WAI-ARIA 1.2, HTML-AAM, Understanding SC 2.5.3, APG: Providing Accessible Names, HTML Standard: translate, Chrome DevTools accessibility reference

Back to the blog