Skip to main content Accessibility Feedback

aria-label requires a valid role

The [aria-label] attribute is used to provide an accessible name to an element that might not otherwise have one.

For example, let’s say you have a <button> that’s used to download a file. Instead of text, it includes a download icon as an inline SVG, like this…

<button>
	<svg xmlns="http://www.w3.org/2000/svg" height="1em" width="1em" viewBox="0 0 16 16"><path fill="currentColor" d="M13.922 5.626A3.72 3.72 0 0010.205 2a3.712 3.712 0 00-2.92 1.418 2.09 2.09 0 00-3.719 1.573 3.028 3.028 0 00-3.567 2.98A3.028 3.028 0 003.026 11H4.46l3.539 3.664L11.538 11h1.742a2.725 2.725 0 00.641-5.374zM8 13l-3-3h2V7h2v3h2l-3 3z"/></svg>
</button>

A screen reader would simply announce that as “button,” which doesn’t tell a visually impaired user anything about what it does.

One common mistake with [aria-label] (that I have absolutely done myself) is to add the attribute directly to the SVG instead of the <button> or <a> or other element.

For example, the contact links on my about page looked like this for a while (and by “for a while” I mean until yesterday)…

<a href="https://bsky.app...">
	<svg xmlns="http://www.w3.org/2000/svg" class="margin-right" style="margin-bottom:-0.1875em;" width="1em" height=".9em" fill="none" viewBox="0 0 64 57" aria-label="BlueSky: "><path fill="currentColor" d="M13.873 3.805C21.21 9.332 29.103 20.537 32 26.55v15.882c0-.338-.13.044-.41.867-1.512 4.456-7.418 21.847-20.923 7.944-7.111-7.32-3.819-14.64 9.125-16.85-7.405 1.264-15.73-.825-18.014-9.015C1.12 23.022 0 8.51 0 6.55 0-3.268 8.579-.182 13.873 3.805Zm36.254 0C42.79 9.332 34.897 20.537 32 26.55v15.882c0-.338.13.044.41.867 1.512 4.456 7.418 21.847 20.923 7.944 7.111-7.32 3.819-14.64-9.125-16.85 7.405 1.264 15.73-.825 18.014-9.015C62.88 23.022 64 8.51 64 6.55c0-9.818-8.578-6.732-13.873-2.745Z"></path></svg>
	@cferdinandi
</a>

But that SVG element doesn’t have a valid role. By default, it’s role is none.

I have two options. I can explicitly give it a role, or I can apply the [aria-label] to an element that already implicitly has a valid role, like a link or button.

Here, the easiest thing to do is to move the label to the link element, like this…

<a href="https://bsky.app..." aria-label="BlueSky: @cferdinandi@bsky.social">
	<svg xmlns="http://www.w3.org/2000/svg" class="margin-right" style="margin-bottom:-0.1875em;" width="1em" height=".9em" fill="none" viewBox="0 0 64 57" aria-hidden="true"><path fill="currentColor" d="M13.873 3.805C21.21 9.332 29.103 20.537 32 26.55v15.882c0-.338-.13.044-.41.867-1.512 4.456-7.418 21.847-20.923 7.944-7.111-7.32-3.819-14.64 9.125-16.85-7.405 1.264-15.73-.825-18.014-9.015C1.12 23.022 0 8.51 0 6.55 0-3.268 8.579-.182 13.873 3.805Zm36.254 0C42.79 9.332 34.897 20.537 32 26.55v15.882c0-.338.13.044.41.867 1.512 4.456 7.418 21.847 20.923 7.944 7.111-7.32 3.819-14.64-9.125-16.85 7.405 1.264 15.73-.825 18.014-9.015C62.88 23.022 64 8.51 64 6.55c0-9.818-8.578-6.732-13.873-2.745Z"></path></svg>
	@cferdinandi
</a>

Some screen readers (notably VoiceOver on macOS) are extremely forgiving of invalid markup.

My computer read the original version aloud the way I expected it would work. But other screen reader and browser combinations are a lot more strict.

If you test with VoiceOver, it’s worth being aware that what you experience might not be the same as what people on other devices experience.