aria-label attribute defines a string value that labels an interactive element.
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.
<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>
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
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
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 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.
aria-label attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an ARIA
aria-label. For example, use visible text with
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-labelledby should be used with non-interactive elements or inline structural role such as with
emphasis nor roles whose semantics will not be mapped to the accessibility API, including
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
title, your images an
alt attributes, and your input's associated
aria-label is not necessary. But, if present, the
aria-label will take precedence over the
<label> as your
iframe, image, or input's accessible name, respectively.
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.
A string of text that will be the accessible name for the object.
ariaLabelproperty, part of the
Elementinterface, reflects the value of the
ariaLabelproperty, part of the
ElementInternalsinterface, reflects the value of the
Used in almost all roles except roles that can not be provided an accessible name by the author.
aria-label attribute is NOT supported in:
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.
|Accessible Rich Internet Applications (WAI-ARIA) |
- Using HTML landmark roles to improve accessibility on MDN blog (May 15, 2023)