
aria-label
is one of a number of secondary methods to label native HTML UI elements. It works particularly well on interactive elements, it also works well on most block level elements old skool term that have explicitly or implicitly defined structural roles. It works less well or not at all on text level semantics. It is prohibited as are any form of accessible name on a whole slew of roles.
Implicit roles are those applied automatically by browsers to native HTML elements.
Explicit roles are those applied by developers using the role
attribute. When applied they override the implicit role of an element.
(Somewhat out of place here) general rules for labeling
- Prefer visible over hidden labels
- Prefer text labels over icons
- If icons are used provide a supplementary text label ( may be displayed on focus/hover)
- Place visible labels as expected:
- For a checkbox or radio button, place the label immediately after the field.
- If not a checkbox or radio button, place the label immediately before the field.
- Prefer native HTML labeling mechanisms, for Native HTML controls, over ARIA labeling mechanisms.
Never be tempted to use placeholder text as a label. It SUX.
Questions on aria-label usage
I find myself regularly asking the these questions in regards to aria-label
:
- Is it a good idea to use
aria-label
on element X? - Does
aria-label
work as expected i.e is announced by screen readers on element Z? - Is
aria-label
allowed on element Y?
FYI empty aria-label=""
does not equal empty alt=""
, the latter signals that an img
element has no useful information, the former does nothing.
aria-label
masks any other accessible name source except aria-labelledby
, which masks all others including aria-label
.
For HTML elements I have provided some guidance on aria-label
usage (which by all means you may disagree with):
HTML element | aria-label | notes |
---|---|---|
a with href |
yes | Masks text content, so only aria-label is announced:
Be wary of label in name issues |
a without href |
no | a without href is not a link and not exposed as a link . Maps to role=generic naming not allowed |
abbr |
no | title attribute works but announcement is a user preference in some screen readers (off by default). Refer to Short note: The abbreviation appreciation society |
address |
no | aria-label use not well supported |
area with href |
no | use alt |
area without href |
no | a without href is not a link and not exposed as a link . Maps to role=generic naming not allowed |
article |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the article is navigated to. |
aside |
yes | Does not mask content. Accessible name provided via aria-label will generally be announced when the aside is navigated to. |
audio |
yes | Prefer visible, a heading perhaps (via aria-labelledby if you like) |
b |
no | Maps to role=generic naming not allowed |
base |
no | not UI |
bdi |
no | Maps to role=generic naming not allowed |
bdo |
no | Maps to role=generic naming not allowed |
blockquote |
no | aria-label use not well supported |
body |
no | aria-label use not supported |
br |
no | Maps to role=generic naming not allowed |
button |
yes | masks text content, so only aria-label is announced:
Be wary of label in name issues |
canvas |
no | Use child content
|
caption |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
cite |
no | Maps to role=generic naming not allowed |
code |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
col |
no | not UI |
colgroup |
no | not UI |
data |
no | Maps to role=generic naming not allowed |
datalist |
no | For aria-label on <datalist> element itself. |
dd |
no | aria-label use not well supported |
del |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
dfn |
no | aria-label use not well supported |
details |
yes | Does not mask content: When details has an accessible name it is announced as a group along with its accessible name (test case). |
dialog |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the dialog is navigated to. |
div |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
dl |
yes | Fairly good support across browsers/screenreaders. |
dt |
no | aria-label use not well supported |
em |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
embed |
no | aria-label use not well supported |
fieldset |
yes | aria-label overrides accessible name from legend content (if present). Otherwise, does not mask content: accessible name provided via aria-label will generally be announced when the fieldset is navigated to. |
figcaption |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
figure |
yes | aria-label overrides accessible name from figcaption content (if present). Otherwise, does not mask content: accessible name provided via aria-label will generally be announced when the figure is navigated to. |
footer |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the footer is navigated to. |
form |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the form is navigated to. |
form-associated custom element | yes | Unless the custom element is an extension of a native HTML interactive element, ARIA labeling (aria-label , aria-labelledby ) is the primary method of labeling. |
h1 to h6 |
no | aria-label use not well supported, works with NVDA/VoiceOver not with JAWS
Masks text content, so only
|
head |
no | not UI |
header |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the header is navigated to. |
hgroup |
no | Maps to role=generic naming not allowed |
hr |
yes | Will generally be announced when the hr is navigated to. |
html |
no | not UI |
i |
no | Maps to role=generic naming not allowed |
iframe |
yes | Use title attribute for accessible name |
img with alt ="some text" |
no | Use alt attribute for accessible name |
img with alt ="" |
no | use alt |
img without alt attribute |
no | if you want to add an accessible name to an <img> use alt attribute for accessible name |
input type=button |
yes | accessible name from value preferred |
input type=checkbox |
yes | accessible name from label preferred |
input type=color |
yes | accessible name from label preferred |
input type=date |
yes | accessible name from label preferred |
input type=datetime-local |
yes | accessible name from label preferred |
input type=email |
yes | accessible name from label preferred |
input type=file |
yes | accessible name from label preferred |
input type=image |
no | if you want to add an accessible name to an <input type=image> use alt |
input type=month |
yes | accessible name from label preferred |
input type=number |
yes | accessible name from label preferred |
input type=password |
yes | accessible name from label preferred |
input type=radio |
yes | accessible name from label preferred |
input type=range |
yes | accessible name from value preferred |
input type=reset |
yes | accessible name from value preferred |
input type=search |
yes | accessible name from label preferred |
input type=submit |
yes | accessible name from value preferred |
input type=tel |
yes | accessible name from label preferred |
input type=text |
yes | accessible name from label preferred |
input type=time |
yes | accessible name from label preferred |
input type=url |
yes | accessible name from label preferred |
input type=week |
yes | accessible name from label preferred |
ins |
no | Maps to role=generic naming not allowed |
kbd |
no | Maps to role=generic naming not allowed |
label |
no | Maps to role=generic naming not allowed (until ARIA 1.3) |
legend |
no | aria-label use not well supported |
li |
no | aria-label use not well supported |
link element with ahref |
no | Don’t use link in body |
main |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the main is navigated to. |
map |
no | not UI |
math |
no | The math element is not currently supported in modern browsers. |
mark |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
menu |
no | This element sucks in general, suggest not using. |
meta |
no | not UI |
meter |
yes | accessible name from label preferred |
nav |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the nav is navigated to. |
noscript |
no | not UI |
object |
no | aria-label use not well supported |
ol |
yes | Fairly good support across browsers/screenreaders. |
optgroup |
no | Use label attribute |
option |
no | Use text content of option or use a label attribute. |
output |
no | aria-label use not supported |
p |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
param |
no | not UI |
picture |
no | not UI |
pre |
no | Maps to role=generic naming not allowed |
progress |
yes | accessible name from label preferred or a heading perhaps (via aria-labelledby if you like). |
q |
no | Maps to role=generic naming not allowed |
rp |
no | Maps to role=generic naming not allowed |
rt |
no | Maps to role=generic naming not allowed |
ruby |
no | Maps to role=generic naming not allowed |
s |
no | Maps to role=generic naming not allowed |
samp |
no | Maps to role=generic naming not allowed |
script |
no | not UI |
section |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the section is navigated to. |
select |
yes | accessible name from label preferred |
slot |
no | not UI |
small |
no | Maps to role=generic naming not allowed |
source |
no | not UI |
span |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
strong |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
style |
no | not UI |
SVG |
yes | alt="some text" DOES NOT WORK even if the SVG (or any other element) has a role="img" |
sub |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
summary |
no | aria-label use not well supported |
sup |
no | refer to Roles which cannot be named (Name prohibited) ARIA 1.2 |
table |
yes | Prefer visible caption element text |
tbody |
no | aria-label use not well supported |
template |
no | not UI |
textarea |
yes | accessible name from label preferred |
tfoot |
no | aria-label use not well supported |
thead |
no | aria-label use not well supported |
time |
no | Maps to role=generic naming not allowed |
title |
no | aria-label use not supported |
td |
no | aria-label use not well supported |
th |
no | aria-label use not well supported |
tr |
no | aria-label use not well supported |
track |
no | not UI |
u |
no | Maps to role=generic naming not allowed |
ul |
yes | Fairly good support across browsers/screenreaders. |
var |
no | Maps to role=generic naming not allowed |
video |
yes | Prefer visible, a heading perhaps (via aria-labelledby if you like) |
wbr |
no | Maps to role=generic naming not allowed |
Thanks to @carmacleod for feedback.
19 replies on “Not so short note on aria-label usage – Big Table Edition”
Hi Steve,
Many Thanks for this great article. I’m french, and I have a question for you. Is it relevant to use aria-label to fix a perticular bad pronounciation of an element?
Here is a use case:
in french let’s take this example: a link with Apereo as label
<a href="url" rel="nofollow"> Apereo</a>
. VoiceOver, Talback (on desktop and mobile) will announce “Apeuro”, which is awful in french, believe me.What I’m doing is :
<a href="url" rel="nofollow" aria-label=”apéréo”>Apereo</a>
and then assistive technologies announce “Apéréo” in the perfect french way to announce the Apereo fundation…Does this use of aria-label could be correct ? Have you insights on this use?
How does it sound if you use `Apereo`?
Maybe the
<ruby>
element is what you’re looking for?https://www.w3.org/TR/WCAG20-TECHS/H62.html
Never played with it, intended for Asian languages but might be the right tool for your situation?
Also, why can’t you just use `Apéréo` if that’s the correct pronunciation? Your main issue is that you’re trying to write 2 different things based on the user agent :/
.
Hi Christian, in general trying to fix screen reader mispronunciation is not advised. In this particular case am wondering why you don’t do?
<a href="url" lang="fr">apéréo</a>
note, assuming it is French? After googling I am guessing that you may be linking to https://www.apereo.org/projects/cas ?
@Bobu, the use of
<ruby>
here is not appropriate and will not do anything.Thank you for the article! I struggle with how to handle UI elements that use or include an abbreviation/acronym in the visible text. In such cases (e.g. UW–Madison instead of University of Wisconsin-Madison) I sometimes use aria-label to spell out the abbreviation or acronym but this results in a mismatch between the visible text and coded name. I generally stopped using or several years ago under the impression they were largely not implemented and/or used by users.
Do you have any advice for how to work with abbreviations or acronymns within UI text/labels? (For instances where they are unavoidable.)
@Nick did you take a look at the The abbreviation appreciation society article?
Is an aria-label or a title attribute preferred for iframe? It currently says “yes” for aria-label, yet also “Use title attribute for accessible name”.
@Mitchell, It says use “Use title attribute for accessible name” While
aria-label
generally works and is allowed on<iframe>
better to usetitle
as it is the native and robustly supported method.Hi Steve, this is really useful—thank you!
Just to clarify, when you say:
>`aria-label` masks any other accessible name source except `aria-labelledby`
…does that mean that `aria-labelledby` might work in situations where `aria-label` wouldn’t?
So let’s say I’ve got:
`div aria-label=”some text”`
… that’s not going to work becuase `aria-label` doesn’t work with the `div` element,
But if I’ve got:
`div aria-labelledby=”someID”`
…would that work?
Or do the same rules apply for `aria-labelledby` as `aria-label`? i.e. the list of go/no-go elements in your list also applies to `aria-labelledby`?
@Jeremy
For example, in the following code example the acc name for the
button
is “poot” as it overrides thearia-label
“pong”, which overrides the child text content “ping” of thebutton
as acc name source.I was referring to accessible name calculation order of precedence for sources of accessible name. take a look at Accessible Name and Description Computation for HTML elements for details.
In general yes.
Thanks so much, Steve—this is really good to know!
Typically brilliant article, copied straight into my developer resources. I’m a bit curious why you “forbid” use of aria-label on img elements. As a source of accessible name, they work as well as alt attributes (at least for a wide variety of screen reader/user agents) in my testing. native is always better, but the same applies to any HTML element with native labeling semantics. So I am curious why you feel so strongly about the img element in particular. I would have copied your note on, e.g. radiobuttons over stating directly that aria-label cannot be used on img elements. Of course there’s always plenty of room for personal opinions and the ensuing lively discussions, and I can’t say I am fanatical about my interpretation. *grin*
@Birkir
The reason i said use
alt
is there is no reason whyaria-label
would need to be used instead ofalt
(am happy to be disabused). Besidesalt
is displayed in place of broken images in graphical browsers, it’s used by search engines, when an image is copied in most modern browsers and pasted into a HTML document itsalt
text goes with it.Thank you. I article is very useful
For further reading, I also recommend Jamie Teh’s still very relevant article on problems aria-label causes for screen reader implementors, especially those who still have to rely on virtual buffers. And despite some attempts to get rid of them, these virtual buffers are going to stay around for at least some years to come I think.
[…] Not so short note on aria-label usage […]
[…] Not so short note on aria-label usage – Big Table Edition html5accessibility.comAccessibility, ever an important subject, can have nuances that are hard to understand. In this piece, Steve Faulkner provides a useful guide on aria-label usage. […]
Please include graphics-aria roles in your big table. These roles are so poorly documented, that there is no clear consensus whether data points should be included in the tab sequence or not, and I believe this has an impact on the behavior of aria-label.
Where should the AT vendors look for accessible names in graphics aria?
Please also add some comment about use of aria naming attributes with custom components. I understand that these have the same rules as div. This means that if you extend from a HTMLImageElement, aria-label will be invalid, then? What if you add role=”img”? I am struggling to find information about this topic.