aria-labelledby — Referencing Visible Labels for Accessible Names

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-labelledby references one or more element IDs to compose an accessible name from existing visible text, enabling dynamic labeling without duplicating content.

In this tutorial, you'll learn how to use aria-labelledby to connect elements to their visible labels in ARIA.

What You'll Learn

By the end of this lesson, you'll understand when to use aria-labelledby, how it differs from aria-label and the HTML label element, how to reference multiple elements, and how to test the results.

Why It Matters

aria-labelledby keeps labels in sync with visible content. When the visible label changes, the accessible name automatically updates without modifying the ARIA attribute.

Real-World Use

Doda Browser's tab panels use aria-labelledby to link each tabpanel to its tab, so screen reader users hear the tab label when entering a panel.

Labeling Strategy

flowchart TD
  A[Element needs name] --> B{Visible text exists?}
  B -->|Yes| C[Use aria-labelledby]
  B -->|No| D{Can add visible text?}
  D -->|Yes| E[Add visible label]
  D -->|No| F[Use aria-label]
  C --> G[Reference element IDs]
  G --> H[Test announcement]

How aria-labelledby Works

aria-labelledby takes a space-separated list of element IDs. The accessible text is the concatenation of the referenced elements' text content:

<h2 id="section-title">Scan Results</h2>
<div role="region" aria-labelledby="section-title">
  <!-- content -->
</div>

The screen reader announces "Scan Results region" when entering the div.

Referencing Multiple Elements

You can reference multiple elements to compose a label:

<p id="price">$49.99</p>
<p id="description">Annual subscription</p>
<button aria-labelledby="price description">Add to Cart</button>

The button is announced as "$49.99 Annual subscription Add to Cart button". The text from referenced elements is concatenated in ID order.

aria-labelledby vs aria-label

aria-labelledby takes priority over aria-label. If both are present, aria-labelledby is used:

<button aria-label="Buy now" aria-labelledby="custom-label">Purchase</button>

The screen reader uses the value referenced by aria-labelledby, not "Buy now".

Common Mistakes

• Referencing IDs that do not exist: The attribute silently fails if IDs are missing.
• Creating circular references: Element A references B, and B references A, causing infinite loops.
• Using aria-labelledby on elements that already have an HTML label: The HTML label already provides the name.
• Forgetting that aria-labelledby overrides visible text: The accessible name comes entirely from referenced elements.
• Using the same ID on multiple elements: IDs must be unique on the page.

Practice and Challenge

1. What does aria-labelledby do? References one or more element IDs to compose an accessible name.

2. What happens if you use both aria-label and aria-labelledby? aria-labelledby takes precedence.

3. How do you reference two elements with aria-labelledby? Use a space-separated list of IDs.

4. What happens if a referenced ID does not exist? The ID is ignored. The remaining IDs are still used.

5. Challenge: Create a dialog where the heading is the dialog's accessible name using aria-labelledby.

FAQ

Mini Project

Create a page where each section uses aria-labelledby to link to its heading. Add a screen reader test script that verifies the region announcements.

What's Next

Continue to aria-describedby to learn how to add descriptions to elements.