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

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:

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