Demystifying aria-labelledby: A Comprehensive Guide with Examples

Introduction to aria-labelledby

In the realm of web accessibility, ARIA (Accessible Rich Internet Applications) attributes play a crucial role in making web content usable for everyone, including people who use assistive technologies like screen readers. Among these attributes, aria-labelledby stands out as a powerful tool for linking an element to the visible text that names it. This guide covers what it does, how it differs from aria-label, how multiple IDs combine into one name, and the mistakes that break screen reader output.

What is aria-labelledby?

The aria-labelledby attribute gives an element its accessible name, the text a screen reader announces to identify it, by pointing to the ID of one or more other elements. The browser takes the text of those elements and uses it as the name. It is defined in the WAI-ARIA 1.2 specification, and MDN’s aria-labelledby reference lists the roles that support it.

Unlike aria-label, which holds a text string only assistive technology can see, aria-labelledby reuses content that is already on the page. That keeps what sighted users see and what screen reader users hear the same, and if the visible text is edited or translated, the name updates with it.

Why Use aria-labelledby?

• To name a dialog, region or tab panel after its visible heading.
• To name a custom widget (a div with a role such as radiogroup or listbox) that cannot use a <label> element.
• To build a name from several pieces of visible text, such as a “Read more” link plus the article title.
• To keep labels perceivable by all users, because the source text is on screen.

How to Use aria-labelledby: A Step-by-Step Guide

Using aria-labelledby effectively involves four steps:

1. Check for a native option first. The W3C’s first rule of ARIA is to use native HTML when it can do the job. A form field should get a <label for>; a button or link should get its name from its own text; a table should use <caption>. The APG’s Read Me First page explains why: no ARIA is better than bad ARIA.
2. Use aria-labelledby when the naming text is visible but not connected. Typical cases are a dialog title, a section heading, a group of radio buttons in a custom widget, or a name made from several parts.
3. Give each source element a unique ID and list them in reading order. Separate IDs with spaces. The browser joins the text in the order you list the IDs, not the order the elements appear on the page.
4. Check the computed name. Open your browser’s developer tools, select the element and read the computed name in the Accessibility panel, then confirm it with a screen reader.

Practical Examples of aria-labelledby

Example 1: Form Field: Native Label First, aria-labelledby as Fallback

For an ordinary text input, a <label> is the right answer. It names the field, and clicking the label moves focus into it, which helps people with motor impairments:

<label for="name">Enter your name</label>
<input id="name" type="text" autocomplete="name">

Reach for aria-labelledby only when the label text cannot be a <label> element, for example because the host is not a form control. A custom radio group is a common case:

<h3 id="ship-label">Shipping method</h3>
<div role="radiogroup" aria-labelledby="ship-label">
  <div role="radio" aria-checked="true" tabindex="0">Standard</div>
  <div role="radio" aria-checked="false" tabindex="-1">Express</div>
</div>

Screen readers announce “Shipping method, radio group” when focus enters the group. (A native <fieldset> with <legend> and real radio inputs would do the same with no ARIA at all, and is preferred where you can use it.)

Example 2: Naming a Table or Region

An earlier version of this guide put a heading and a full description sentence into one table name. That makes the name long and repetitive. The better pattern is a short name and a separate description:

<h2 id="table-heading">Monthly Sales Report</h2>
<p id="table-description">Sales data for October, by region.</p>
<table aria-labelledby="table-heading" aria-describedby="table-description">
  ...
</table>

The name is “Monthly Sales Report” and the description is read after it. If the heading can sit inside the table, a <caption> is simpler still.

Example 3: Composing a Name From Several IDs (“Read more” links)

Blog cards often have several “Read more” links. Out of context, a screen reader user browsing a links list hears “Read more” repeatedly. You can build a unique name from the link itself plus the card title:

<h3 id="post-12-title">Understanding WCAG 4.1.2</h3>
<a id="post-12-more" href="/wcag-4-1-2/" aria-labelledby="post-12-more post-12-title">Read more</a>

The link references its own ID first, so the name is “Read more Understanding WCAG 4.1.2”. Starting with the visible words matters for voice control users, as covered in the Label in Name section below. This self-plus-other technique is described in the W3C’s technique ARIA16: Using aria-labelledby to provide a name for user interface controls.

Example 4: Naming a Dialog After Its Title

<div role="dialog" aria-modal="true" aria-labelledby="dlg-title">
  <h2 id="dlg-title">Delete this file?</h2>
  ...
</div>

When focus moves into the dialog, screen readers announce “Delete this file?, dialog”, so the user knows where they are. The same pattern works for <section> and role="region" landmarks named after their headings, and for native <dialog> elements.

aria-labelledby vs aria-label: Which Should You Use?

1. Is there a native way to name it? Use <label>, element content, alt, <caption> or <legend>.
2. Is the naming text visible somewhere else on the page? Use aria-labelledby.
3. Is there no visible text at all? Use aria-label. Our aria-label guide covers that case.

The order matters because of how browsers calculate names. In the accessible name computation, aria-labelledby comes first, then aria-label, then native sources such as a <label>, element content or title. If an element has both ARIA attributes, aria-label is ignored. The APG’s guide to providing accessible names and descriptions explains the full order.

Name vs Description: aria-labelledby vs aria-describedby

A name says what something is; a description adds detail. “Password” is a name; “Must be at least 12 characters” is a description. Put the short identifying text in aria-labelledby and supporting help, hints or error messages in aria-describedby. Screen readers read the name first and the description after it, often after a pause, and users can skip the description once they know the control.

Common Mistakes That Break Screen Reader Output

• Pointing to an ID that does not exist. A typo or a renamed ID leaves the element with no name or a fallback name. Validators and automated checkers usually flag this.
• Duplicate IDs. If two elements share an ID, the browser uses the first one, which may be the wrong text. This is common with repeated components such as cards.
• Using it on elements that cannot be named. Generic div and span elements without a role, and roles such as paragraph or presentation, do not support naming, so screen readers may ignore it.
• Overriding visible text. Because aria-labelledby wins over the element’s own content, pointing a “Buy” button at a product heading replaces “Buy” entirely. Include the button’s own ID if you want both.
• Expecting chains to work. If element A is labelled by B, and B has its own aria-labelledby, the browser does not follow the second reference. It uses B’s text content.
• Labelling with whole paragraphs. Long names are tiring and slow to navigate. Keep the name short and move the rest to aria-describedby.

One useful behaviour: aria-labelledby can reference text that is hidden from view, including content with display: none or the hidden attribute. That lets you build names from text you do not want on screen, but use it sparingly, as visible labels help everyone.

aria-labelledby and WCAG

Two WCAG success criteria are directly involved. WCAG 4.1.2 Name, Role, Value requires every user interface component to expose a name to assistive technology (see W3C’s Understanding 4.1.2). WCAG 2.5.3 Label in Name requires that a control’s accessible name contain its visible label text. W3C’s Understanding 2.5.3 explains why: voice control users say what they see. Technique G208 recommends that the visible text appear at the start of the name, which is why Example 3 lists the link’s own ID first.

Testing aria-labelledby

Automated checkers can catch missing IDs, duplicate IDs and controls with no name. Our guide to automated accessibility testing covers the tools. They cannot tell whether the name makes sense, so listen to it. With NVDA, VoiceOver or JAWS, tab to the element and check that the announcement is short, accurate and starts with the visible text. Our screen reader testing guide walks through the process.

Best Practices and Considerations

• Use native HTML labelling first; use aria-labelledby for visible text that cannot be connected natively.
• Keep IDs unique, especially in repeated templates.
• List IDs in the order the name should be read, starting with any visible text on the control itself.
• Do not combine aria-label and aria-labelledby on the same element; the label will be ignored.
• Use aria-describedby for hints and errors, not the name.
• Test the computed name in developer tools and with a screen reader.

Conclusion

The aria-labelledby attribute is the right tool when an element should be named by visible text that HTML cannot connect on its own: dialog titles, region headings, custom widgets and composed link names. Use native labels first, keep names short, list IDs in reading order and test the result. Get those right and screen reader and voice control users will hear the same labels everyone else sees.

To keep learning, read our ARIA essentials quick-start guide, our overview of ARIA attributes, our guide to aria-expanded and our alt text guide.

Related Resources

• Accessibility remediation services
• aria-label guide
• ARIA attributes explained
• MDN: aria-labelledby

Work With Us

Relationships like this are exactly the kind of thing automated scanners miss. Our manual accessibility audit catches it — and our remediation service can fix it.

Get a free accessibility assessment — no commitment required.