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.

Associated interfaces
---------------------

`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:

* `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>` element
* `aria-labelledby`
* Using HTML landmark roles to improve accessibility on MDN blog (2023)