HTML: aria-label

The aria-label attribute gives an element a name for assistive technology when a suitable visible name is not available.

What you will learn

aria-label and CSS: choose what you need

aria-label supplies a name for assistive technology, such as screen readers. It does not display that name on screen or change the element’s appearance.

Select an element that has aria-label

[aria-label] {
  border: 2px solid currentColor;
}

[aria-label="Close explanation"] {
  font-weight: bold;
}

The first selector matches elements with aria-label. The second matches one exact value. Renaming or translating that value breaks the exact match. A styling class keeps appearance independent of the accessible name.

<button class="icon-button" type="button"
        aria-label="Close explanation">
  <span aria-hidden="true">×</span>
</button>

<style>
.icon-button { font-weight: bold; }
</style>

If the name should be visible too

<button type="button">Close explanation</button>

If space allows, put the text inside the button. aria-label does not create a tooltip either. Do not put instructions that people need to see only in aria-label.

Try an icon-only button

You can close this explanation

The × is a visual symbol. The button is named “Close explanation”.

Press the button to close the explanation in this box.

Use the browser’s accessibility inspector to check the button’s name. Choose visible text, label, aria-labelledby, or aria-label to suit the element and the information already on screen.

Not every role allows an accessible name. Use aria-label on elements whose roles support naming, such as buttons. For an input, consider a visible label first.

Source: W3C guidance on aria-label.

Icon button example

<button type="button" aria-label="Close dialog">
  &times;
</button>

A screen reader can announce the button as “Close dialog” even though the visible control only contains an icon.

Prefer visible names when possible

<button type="button">Save changes</button>

Visible text helps everyone, including people who do not use assistive technology. For form inputs, use a visible label element when possible.

Common mistakes