Updated: 22 May 2024
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 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. |
search |
yes | Does not mask content: accessible name provided via aria-label will generally be announced when the search element 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.
13 replies on “Not so short note on aria-label usage – Big Table Edition”
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.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. […]
[…] Use ARIA correctly […]
Re: “The math element is not currently supported in modern browsers.”
It has been supported in ALL modern browsers since January 2023 and everyone should feel encouraged to rely on tags nowadays.
But there is still no need for aria-label on elements. MathML 3 supports an “alttext” attribute, while MathML 4 is introducing a new “intent” attribute aimed at accessible readouts.
[…] Not so short note on aria-label usage – Big Table Edition by Steve Faulkner […]