aria-label
The aria-label
attribute defines a string value that labels an interactive element.
Description
Sometimes the default accessible name of an element is missing, or does not accurately describe its contents, and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example is a button containing an SVG or icon font (which you shouldn't be using) without any text.
In cases where an interactive element has no accessible name, or an accessible name that isn't accurate, and there is no content visible in the DOM that can be referenced via the aria-labelledby
attribute, the aria-label
attribute can be used to define a string that labels the interactive element on which it is set. This provides the element with its accessible name.
html
<button aria-label="Close" onclick="myDialog.close()">
<svg
aria-hidden="true"
focusable="false"
width="17"
height="17"
xmlns="http://www.w3.org/2000/svg">
<path
d="m.967 14.217 5.8-5.906-5.765-5.89L3.094.26l5.783 5.888L14.66.26l2.092 2.162-5.766 5.889 5.801 5.906-2.092 2.162-5.818-5.924-5.818 5.924-2.092-2.162Z"
fill="#000" />
</svg>
</button>
Note: aria-label
is intended for use on interactive elements, or elements made to be interactive via other ARIA declarations, when there is no appropriate text visible in the DOM that could be referenced as a label
Most content has an accessible name generated from its immediate wrapping element's text content. Accessible names can also be created by certain attributes or associated elements.
By default, a button's accessible name is the content between the opening and closing <button>
tags, an image's accessible name is the content of its alt
attribute, and a form input's accessible name is the content of the associated <label>
element.
If none of these options are available, or if the default accessible name is not appropriate, use the aria-label
attribute to define the accessible name of an element.
aria-label
can be used in cases where text that could label the element is not visible. If there is visible text that labels an element, use aria-labelledby
instead.
The purpose of aria-label
is the same as aria-labelledby
. Both provide an accessible name for an element. If there is no visible name for the element you can reference, use aria-label
to provide the user with a recognizable accessible name. If the label text is available in the DOM, and referencing the DOM content and acceptable user experience, prefer to use aria-labelledby
. Don't include both. If both are present on the same element, aria-labelledby
will take precedence over aria-label
.
Note: While aria-label
is allowed on any element that can have an accessible name, in practice, aria-label
is only supported on interactive elements, widgets, landmarks, images and iframes.
The aria-label
attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an ARIA role
assigned.
Don't "overuse" aria-label
. For example, use visible text with aria-describedby
or aria-description
, not aria-label
, to provide additional instructions or clarify the UI. Always remember, you don't need to target instructions to screen readers only; if instructions are needed, provide them to everyone (or, preferably, make your UI more intuitive).
Not all elements can be given an accessible name. Neither aria-label
nor aria-labelledby
should be used with non-interactive elements or inline structural role such as with code
, term
, or emphasis
nor roles whose semantics will not be mapped to the accessibility API, including presentation
, none
, and hidden
. The aria-label
attribute is intended for interactive elements only. Use aria-label
to ensure an accessible name is provided when none is visible in the DOM for all interactive elements, like links, videos, form controls, landmark roles, and widget roles.
If you give your <iframe>
s a title
, your images an alt
attributes, and your input's associated <label>
s, aria-label
is not necessary. But, if present, the aria-label
will take precedence over the title
, alt
and <label>
as your iframe
, image, or input's accessible name, respectively.
Note: The aria-label
is only "visible" to assistive technologies. If the information is important enough to add for AT users, consider making it visible for all users.
Values
<string>
-
A string of text that will be the accessible name for the object.
ARIAMixin API
Element.ariaLabel
-
The
ariaLabel
property, part of theElement
interface, reflects the value of thearia-label
attribute. ElementInternals.ariaLabel
-
The
ariaLabel
property, part of theElementInternals
interface, reflects the value of thearia-label
attribute.
Associated roles
Used in almost all roles except roles that can not be provided an accessible name by the author.
The aria-label
attribute is NOT supported in:
code
caption
deletion
emphasis
generic
insertion
mark
paragraph
presentation
/none
strong
subscript
superscript
suggestion
term
time
Note: The aria-label
attribute is intended for interactive elements only. When placed on non-interactive elements, such as those listed above, it may not be read or may confuse your users as a non-interactive element that acts like an interactive one.
Specifications
Specification |
---|
Accessible Rich Internet Applications (WAI-ARIA) # aria-label |
See Also
<label>
elementaria-labelledby
- Using HTML landmark roles to improve accessibility on MDN blog (2023)