aria-label

The 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>

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.

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.

<string>

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

Element.ariaLabel

The ariaLabel property, part of the Element interface, reflects the value of the aria-label attribute.

ElementInternals.ariaLabel

The ariaLabel property, part of the ElementInternals interface, reflects the value of the aria-label attribute.

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, and time

• <label> element
• aria-labelledby