Skip to content
Velloreth
Web Development 5 min read

ARIA Labels Explained: When and How to Use Them

ARIA can make a widget accessible or make it worse. Learn the labels, the roles, the live regions and the first rule of ARIA.

By

What ARIA is

ARIA is a set of attributes that add a role, a state or a property to an element. It changes the accessibility tree, which is what a screen reader reads.

<button aria-label="Close dialog">×</button>

The visual appearance does not change. A mistake is invisible in a browser and only appears in a screen reader, which is why ARIA is easy to get wrong.

The first rule

Do not use ARIA when a native element works.

<!-- Wrong: reimplements a button and misses the keyboard behaviour -->
<div role="button" tabindex="0" onclick="submit()">Submit</div>

<!-- Right: the element is a button -->
<button type="submit">Submit</button>

A native element comes with the semantics and the interaction. A button is focusable, it responds to Enter and Space, and it is announced as a button. A div with a role has the announcement and none of the behaviour.

The five rules of ARIA are worth knowing:

  1. Prefer a native element.
  2. Do not change native semantics unless you must.
  3. All interactive ARIA controls must be keyboard operable.
  4. Do not use role="presentation" on a focusable element.
  5. Every interactive element needs an accessible name.

The accessible name

aria-label takes a string.

<button aria-label="Search">
  <svg aria-hidden="true">...</svg>
</button>

aria-labelledby points at another element.

<h2 id="billing">Billing address</h2>
<form aria-labelledby="billing">
  ...
</form>

Use aria-labelledby when a visible label exists, so the name stays in sync with the visible text.

aria-describedby adds a description, which a screen reader reads after the name.

<input id="email" aria-describedby="email-hint">
<p id="email-hint">We will never share your address.</p>

The precedence is aria-labelledby, then aria-label, then the element’s own content.

Roles

A role changes how an element is announced.

<div role="alert">Your session has expired.</div>
<nav role="navigation">...</nav>
<ul role="list">...</ul>

A landmark role identifies a region, such as banner, main, navigation, complementary and contentinfo. A native element such as nav or main already has the role.

A widget role identifies a custom control, such as tab, tabpanel, dialog, menu and combobox. A widget role comes with a keyboard contract, and implementing the role without the contract is worse than no role.

role="presentation" removes the semantics, which is used for a layout table.

<table role="presentation">
  <tr><td>Left</td><td>Right</td></tr>
</table>

Do not use it on a focusable element. The element is still focusable and no longer announced.

States and properties

AttributeMeaning
aria-expandeda disclosure is open or closed
aria-selecteda tab or option is selected
aria-checkeda checkbox is checked
aria-disableda control is disabled
aria-currentthe current item in a set
aria-invalida field has an error
aria-requireda field is required
aria-busya region is loading
<button aria-expanded="false" aria-controls="menu">Menu</button>
<ul id="menu" hidden>...</ul>

aria-current="page" marks the current page in a navigation, which is more precise than a class.

<nav>
  <a href="/" aria-current="page">Home</a>
  <a href="/blog/">Blog</a>
</nav>

Live regions

A live region announces a change without moving focus.

<div aria-live="polite" id="status"></div>
document.getElementById('status').textContent = 'Saved';

polite waits for a pause. assertive interrupts, and it is reserved for an urgent message.

role="status" is an implicit polite region, and role="alert" is an implicit assertive one.

<p role="status">3 results found</p>
<p role="alert">Your card was declined</p>

The region must exist before the change. A region that is added with the content is often not announced, because the screen reader did not observe the insertion.

aria-atomic="true" announces the whole region rather than the changed part.

aria-hidden

aria-hidden="true" removes an element from the accessibility tree.

<button>
  <svg aria-hidden="true" focusable="false">...</svg>
  Save
</button>

Use it for a decorative icon that duplicates a text label.

Never put it on an element that contains focusable content. The element is removed from the tree while remaining focusable, which produces a focus on nothing.

inert is the modern alternative for a whole subtree, and it removes the content from the tree and from the tab order.

<div inert>...</div>

Testing

A screen reader is the real test. VoiceOver on macOS, NVDA on Windows, and Orca on Linux.

The accessibility tree in the browser devtools shows what a screen reader sees, which is faster than a screen reader for a first check.

An automated tool catches a subset. axe, Lighthouse and Pa11y find a missing label and a bad contrast, and they do not find a wrong role or a broken keyboard contract.

A keyboard-only pass is the fastest check for a widget. Tab through the page and confirm every control is reachable and operable.

Common mistakes

A role without the keyboard behaviour. A div with role="button" that does not respond to Enter and Space.

aria-label on a non-interactive element. A label on a div is ignored, because the element has no role that takes a name.

aria-hidden on a focusable element. A focus on nothing.

A live region that is added with the content. The change is not announced.

A redundant role. role="navigation" on a nav element adds nothing.

A label that duplicates the visible text. A screen reader reads both, which is confusing.

Testing only with an automated tool. It catches a subset and misses the interaction.

A quotable summary

ARIA adds a role, a state or a property to an element, and it changes the accessibility tree rather than the rendering. The first rule is not to use ARIA when a native element works, because a native element comes with the semantics and the interaction. Use aria-label for a string and aria-labelledby for a visible label, use a live region to announce a change without moving focus, and never put aria-hidden on an element that contains focusable content.

For the broader topic, see screen-reader-basics and keyboard-navigation-guide. For the forms, form-accessibility-guide and color-contrast-guide.

Frequently asked questions

What is ARIA?
ARIA is the Accessible Rich Internet Applications specification. It is a set of attributes that add a role, a state or a property to an element, so a screen reader can announce a custom widget correctly. It is used when a native HTML element cannot express the semantics.
What is the first rule of ARIA?
Do not use ARIA if a native HTML element or attribute already does the job. A button element is a button; adding role=button to a div reimplements it and usually misses the keyboard behaviour. Native elements come with the semantics and the interaction for free.
What is the difference between aria-label and aria-labelledby?
aria-label takes a string and uses it as the accessible name. aria-labelledby takes the id of another element and uses that element's text. Use aria-labelledby when a visible label already exists, so the name stays in sync with the visible text.
When should I use aria-hidden?
When an element is decorative or duplicated and should not be announced, such as an icon next to a text label. Never put aria-hidden on an element that contains focusable content, because the element is removed from the accessibility tree while remaining focusable, which produces a focus on nothing.
What is a live region?
It is a region whose changes are announced without moving focus. aria-live=polite waits for a pause, and aria-live=assertive interrupts. It is used for a status message, a validation error or a search result count.
Does ARIA affect the visual appearance?
No. ARIA attributes change the accessibility tree, not the rendering. A role or a label has no visual effect, which is why a mistake is invisible in a browser and only appears in a screen reader.