Florian Schroiff has been building for the web for almost 20 years. He has worked on countless accessible websites as a freelancer and for various agencies. As a front-end expert he is always searching for ways to improve accessibility and user experience and to share them with his team — and now with you!
ARIA attributes, including aria-label and aria-labelledby, are designed to provide additional context to help users of assistive technologies understand your website content. These attributes are essential for enhancing web accessibility, ensuring all users can interact with web elements effectively.
Both aria-label and aria-labelledby provide an accessible name for an HTML element. This is particularly useful when the element’s default accessible name is missing or inaccurate. However, while these attributes serve a similar purpose, they achieve this in different ways and have different use cases.
In this article, we’ll explain the difference between the aria-label and aria-labelledby attributes, cover when each attribute should be used, and discuss best practices for implementation.
Key differences between aria-label and aria-labelledby
Before diving into the differences between aria-label and aria-labelledby, let’s go over the basics of each:
aria-label
This attribute defines a string that labels an interactive element, providing an accessible name when no visible text label is present, such as a button containing an SVG or an icon font without any text.
Tip: We generally don’t recommend using icon fonts, as they have many accessibility issues. One of them is that screen readers often can’t tell normal text from pictograms, and when they read the CSS text, they’ll either skip it or say “unpronounceable.”
Other possible cases are when the interactive element has no accessible name or an inaccurate accessible name and no content visible in the DOM exists that can be referenced by the aria-labelledby attribute.
Here’s an example of how the implementation would look:
<button aria-label="Search"><img src="search-icon.svg" alt=""></button>In this instance, when the button receives focus, the screen reader announces something like “Button: search,” telling the user what to expect when interacting with the button.
aria-labelledby
This attribute references another element on the page that contains the label text, associating it programmatically with the element for assistive technologies.
We recommend using this with an existing visible label that needs to be linked to the element for screen readers. This is common in modals where the label is visually present but needs to be programmatically associated.
Here’s an example of how this would look:
<div role="dialog" id="dialog1" aria-labelledby="dialog1_label" aria-modal="true">
<h2 id="dialog1_label">Add Delivery Address</h2>
</div>In this instance, when the first element within the modal receives focus, the screen reader announces the text referenced by the aria-labelledby attribute, in this case, “Dialog, Add Delivery Address”.
It’s important to note that aria-labelledby can reference multiple elements to provide an accessible name for the element it is applied to. In these instances, the order in which the elements are referenced is the order in which the labelling text will be read by the screen reader.
For example:
<span id="button-label1">Complete the</span>
<span id="button-label2">registration form</span><button aria-labelledby="button-label1 button-label2">Submit</button>When the button receives focus, the screen reader will announce “Complete the registration form” as the button’s accessible name.
Finally, remember that aria-labelledby has the highest precedence when browsers calculate accessible names. This means that the text referenced by the attribute will overwrite aria-label attributes, alt text, and the contents of the element to which it is applied. So, use aria-labelledby carefully and ensure that the referenced text accurately describes the purpose of the associated element.
When to use aria-label vs aria-labelledby
If you can, avoid using aria-label or aria-labelledby and instead use proper semantic HTML to provide an accessible name for your website elements.
Here are some examples:
- Include text inside your button elements instead of relying on SVG icons or icon fonts.
- Provide proper alt text for your images and other non-text content.
- Use
<label>elements to provide accessible names for your form inputs.
If you’re absolutely confident that you need to use ARIA to programmatically provide a label for an element, then check if visible text already exists on the webpage that can be used to label the element. If it does, use aria-labelledby to reference that text. If not, use aria-label.
⚠️Important: Because aria-labelledby attributes reference other elements to return an accessible name for their associated element, updating the referenced text will automatically change the accessible name. This is helpful for translation purposes or ensuring consistent updates across your site, but can be problematic if you update text without realising that another element references it.
When implementing aria-label and aria-labelledby, consider the following best practices to ensure effective use:
aria-labeltext doesn’t translate, so it’s not a great choice for multilingual websites. Instead, you should go with semantic HTML oraria-labelledby.- Avoid using
aria-labelto provide information that isn’t available to users who aren’t using assistive technology, such as additional instructions or clarifications not visible on the webpage. Instead, use visible text to provide this information and reference it witharia-labelledbyfor short labels oraria-describedbyfor longer descriptions. For more information onaria-describedby, refer to The A11y Collective’s guide on different types of ARIA labels. - Use aria-label and
aria-labelledbyfor interactive elements like links, buttons, videos, form controls, and elements with ARIA landmark roles or widget roles. - Always double-check that you are referencing valid and correct IDs with
aria-labelledbyto ensure that users of assistive technology receive the correct accessible name for webpage elements. - Any changes to page structure affecting the IDs of on-page elements will break the relationship between an
aria-labelledbyattribute and the element(s) it references. Always update youraria-labelledbyattributes whenever the IDs of referenced elements change.
It’s important to reiterate that using semantic HTML to provide accessible names for your webpage elements is always better than relying on ARIA attributes. It’s much more reliable and maintainable in the long run and should be your first choice for creating accessible web content.
Take your web accessibility to the next level
Understanding web accessibility can greatly improve user experience, especially for those using screen readers. The aria-label attribute provides names for elements without visible text, while aria-labelledby references visible text on another element. Proper use of these attributes is key for accessibility.
To make sure everything works correctly, combine accessibility testing tools and manual testing. This helps catch any issues that might be missed otherwise.
For a deeper dive into ARIA, enrol in The A11y Collective’s “ARIA explained” course. This course will enhance your skills and help you create websites that everyone can enjoy, regardless of their abilities.
Ready to get started?
Enhance your knowledge of ARIA roles and attributes with our comprehensive “ARIA explained” course.
