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
- How to label an icon-only control
- Why visible text or a label element should usually come first
- How to avoid hiding useful information from sighted users
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.
- Style an element with CSS
Select an element by its attribute - Show a text label
Put visible text in HTML - Name an icon button
Describe what the button does
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">
×
</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
- Do not use
aria-labelto hide a missing visible label when users need to see the instruction. - Keep the accessible name concise and describe the action, not only the icon shape.
- Do not add ARIA to an element when a native HTML element already provides the needed semantics.