DEV Community

Cover image for Using aria-labelledby for accessible names
Abdulqudus Abubakre
Abdulqudus Abubakre

Posted on

Using aria-labelledby for accessible names

#html #a11y #webdev

When building UI, we often rely on icons or visual cues that don’t include visible text. While that might look clean, it can leave screen reader users guessing.

aria-labelledby is one of the techniques we can use to give clear context to assistive technologies.

What is aria-labelledby?

aria-labelledby lets you reference visible text elsewhere in the DOM to create an accessible name for an element.

It basically tells assistive technology: “Use this other element’s text to label me.”

It’s commonly used when the text that explains an element is located outside the element itself.

<h2 id="dialog-title">Edit Profile</h2>

<button aria-labelledby="dialog-title">
  ✏️
</button>
Enter fullscreen mode Exit fullscreen mode

Here, the button doesn’t have its own text label, but because it references dialog-title, assistive tech will announce “Edit Profile.”

Why use it?

Sometimes we have elements, especially icon-only controls, that need textual context.

There are several techniques:

  • aria-label="Edit profile"
  • <button>Edit Profile</button> (preferred)
  • title="Edit profile"
  • aria-labelledby="id"

However, aria-labelledby has the highest priority, and if used, its referenced text will always take precedence over any other naming source.

How it works

1) Create an element with descriptive text:

<h2 id="dialog-title">Edit profile</h2>
Enter fullscreen mode Exit fullscreen mode

2) Reference its ID using aria-labelledby on the target element:

<button aria-labelledby="dialog-title">✏️</button>
Enter fullscreen mode Exit fullscreen mode

And that’s it.

⚠️ Important things to note

  • aria-labelledby has the highest priority among naming sources → It will override aria-label, title, and even visible text

the accessibility tree showing the available labels

  • It depends on other elements. If the referenced element is hidden or removed, the accessible name becomes invalid 
<button aria-labelledby="label"></button>
<span id="label" hidden>Example</span>
Enter fullscreen mode Exit fullscreen mode

In the example above, if the span is hidden, the accessible name of the button is lost❌.

✅ As a rule of thumb, use aria-labelledby when:

  1. A descriptive text already exists on the page
  2. The label needs to be more than just a plain string
  3. You want to use multiple elements as a label

✅ Learn more

✅ Final Thoughts

aria-labelledby is a powerful tool for providing context, especially when UI patterns scatter text visually.

Just remember:

  • It takes top priority
  • It relies on another element
  • If that reference breaks → the name breaks

When used well, it helps assistive tech users understand your UI as clearly as everyone else.

Top comments (0)