ARIA: aria-label attribute

Thearia-label attribute defines a string value that can be used to name an element, as long as the element's role does notprohibit naming.

Description

Sometimes, the defaultaccessible name of an element is missing or the accessible name does not accurately describe the contents of the element and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example of such an element is a button containing an SVG icon without any text.

In cases where an element that is not part of theprohibited list, has no accessible name or an accessible name is not accurate and there is no content visible in the DOM that can be referenced via thearia-labelledby attribute, thearia-label attribute can be used to define a string that labels the interactive element on which it is set. This provides the element an accessible name.

The code below shows an example of how to use thearia-label attribute to provide an accessible name for a<button> element. The button in this example contains an SVG graphic and lacks textual content, making thearia-label essential for screen reader users to understand its function, which in this case is "Close".

html

<button aria-label="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="black" />  </svg></button>

document.querySelector("button").addEventListener("click", () => {  myDialog.close();});

Note:aria-label is intended for naming elements where the implicit or explicit role does not prohibit naming. It is strongly recommended to prioritize the use ofaria-labelledby overaria-label if a visible label exists for the element to reference and receive its name from.

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 itsalt 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 thearia-label attribute to define the accessible name of an element.

Note:Whilearia-label can be used on any element that can have an accessible name, in practice however, it is supported only on interactive elements,widgets,landmarks, images, and iframes.

When usingaria-label, you also need to consideraria-labelledby:

aria-label can be used in cases where text that could label the element isnot visible. If there is visible text that labels an element, usearia-labelledby instead.
The purpose ofaria-label is the same asaria-labelledby. Both provide an accessible name for an element. If there is no visible name for the element you can reference, usearia-label to provide the user with a recognizable accessible name. If label text is available in the DOM and it's possible to reference it for an acceptable user experience, prefer to usearia-labelledby. Don't use both on the same element becausearia-labelledby will take precedence overaria-label if both are applied.

Keep the following additional guidelines in mind when usingaria-label:

Thearia-label attribute can be used with regular, semantic HTML elements; it is not limited to elements that have anARIArole assigned.
Don't "overuse"aria-label. Remember that it's primarily for assistive technologies. To provide additional instructions or to clarify the UI, use visible text witharia-describedby oraria-description, notaria-label. Instructions should be accessible to all users, not just to those with screen readers (or preferably, make your UI more intuitive).
Note:Sincearia-label content isn't displayed outside assistive technologies, consider making important information visible for all users.
Not all elements can be given an accessible name. Neitheraria-label noraria-labelledby should be used with inline structural roles such as withcode,term, andemphasis, and roles not mapped to the accessibility API, includingnone. Thearia-label attribute is intended for elements including links, videos, form controls, and those withlandmark roles orwidget roles;aria-label provides an accessible name when no visible label exists in the DOM.
If you assign atitle to an<iframe>, define analt attribute for an<img>, or add<label> for an<input>,aria-label is not necessary. However, if anaria-label attribute is present, it will take precedence over the iframe'stitle, the image'salt, or the input's<label> text as the accessible name for that element.

Values

<string>: A string of text that will be the accessible name for the object.

Associated interfaces

Element.ariaLabel: TheariaLabel property, part of theElement interface, reflects the value of thearia-label attribute.
ElementInternals.ariaLabel: TheariaLabel property, part of theElementInternals interface, reflects the value of thearia-label attribute.