HTML global attributeGlobal attributes

aria-*

ARIA attributes describe elements for screen readers: they give them names, link them to descriptions and report their state.

Applies to
All HTML elements, but each ARIA attribute has its own usage rules
On this page

Example

#
HTML
<style>
  .menu-button { padding: 6px 10px; font-size: 18px; line-height: 1; }
  .menu { list-style: none; margin: 10px 0 0; padding: 0; }
  .menu li { margin-bottom: 6px; }
  .menu a { color: #d4d4d4; }
  .menu a[aria-current="page"] { color: #c4b5fd; font-weight: 600; }
</style>

<button type="button" class="menu-button"
  aria-label="Menu" aria-expanded="false" aria-controls="main-menu"
  onclick="
    const open = this.getAttribute('aria-expanded') === 'true';
    this.setAttribute('aria-expanded', String(!open));
    document.getElementById('main-menu').hidden = open;
  ">
  <span aria-hidden="true">☰</span>
</button>

<ul class="menu" id="main-menu" hidden>
  <li><a href="#">Courses</a></li>
  <li><a href="#" aria-current="page">Documentation</a></li>
  <li><a href="#">Pricing</a></li>
</ul>
Preview

The button has only an icon, so it gets the name “Menu” from aria-label, and the icon itself is hidden from readers by aria-hidden. A click toggles aria-expanded, and aria-current="page" marks the current page. CSS also uses that last attribute here to highlight the active link.

Definition and usage

#

Attributes starting with aria- come from the WAI-ARIA specification. They supplement the information that assistive technologies, such as screen readers, read from the page: what an element is called, what describes it, whether it is expanded, whether it points to the current page. They change nothing on screen, and the browser adds no behavior through them.

Before you reach for them, remember the first rule of ARIA: if a native HTML element provides the name and state you need, use it. A <label> names a field better than aria-label, because everyone sees its text, and <details> expands and reports its state without aria-expanded. ARIA is for situations HTML cannot handle on its own: an icon-only button, a custom dropdown menu, messages that appear without a page reload.

In practice, three groups of attributes are used most. Names and descriptions (aria-label, aria-labelledby, aria-describedby) say what an element is called and what is worth knowing about it. States (aria-expanded, aria-current, aria-hidden) you change with a script along with the interface. Live regions (aria-live) make the reader announce new content even though the user is in a different part of the page.

ARIA does not update itself. If a button has aria-expanded="false" and a menu expands on click, a script must change the value to true. A stale state misleads more than no state at all.

Syntax

#
Syntax
<element aria-name="value">…</element>

The most important aria-* attributes

#
  • aria-label

    text

    The element’s name for screen readers when there is no visible text, for example an icon-only button. It replaces the element’s content. On a plain <div> and <span> without a role, readers usually ignore it.
  • aria-labelledby

    list of ids

    A name taken from another element, for example a section heading. You can give several identifiers separated by spaces. It takes precedence over aria-label.
  • aria-describedby

    list of ids

    Points to an additional description, for example a field hint or an error message. The reader reads it after the element’s name.
  • aria-hidden

    true | false

    Hides the element and all its content from screen readers, but not on screen. For icons and decorations. Never hide elements that can receive focus this way.
  • aria-expanded

    true | false

    The state of a button that shows and hides another part of the page, for example a menu or an answer in an FAQ. Update it with a script on every click.
  • aria-current

    page | step | location | date | time | true

    Marks the current item in a set: the active link in a menu (page), the current form step (step), or today’s date in a calendar (date).
  • aria-live

    off | polite | assertive

    Turns an element into a live region: the reader announces changes to its content. polite waits until the reader finishes speaking, and assertive interrupts right away. The region must exist on the page before you change its content.

More examples

#
A field hint and a live message
HTML
<style>
  .hint { margin: 4px 0 8px; color: #a3a3a3; font-size: 14px; }
</style>

<form onsubmit="
  event.preventDefault();
  const nick = this.elements.nick.value.trim();
  const valid = nick.length >= 3 && nick.length <= 16 && !nick.includes(' ');
  document.getElementById('nick-status').textContent = valid
    ? 'Nickname ' + nick + ' saved.'
    : 'A nickname must be 3 to 16 characters long and cannot contain spaces.';
">
  <label for="nick">Leaderboard nickname</label>
  <input id="nick" name="nick" type="text" aria-describedby="nick-hint">
  <p id="nick-hint" class="hint">3 to 16 characters, no spaces.</p>
  <button>Save nickname</button>
  <p id="nick-status" aria-live="polite"></p>
</form>
Preview

A screen reader will read the field name from the label, and after it the hint pointed to by aria-describedby. The result of saving goes into a paragraph with aria-live="polite" that is on the page from the start, so the reader announces the message even though focus stays on the button.

Browser support

#

Widely available

Works in all modern browsers, phones included. You can use it without worry.

  • Chrome
  • Edge
  • Firefox
  • Safari

Good practices

#
  • Do not give aria-label to elements with visible text that says something different. People who control their computer by voice say what they see on screen, and the program knows only the name from ARIA.
  • aria-hidden="true" on an element that can receive focus creates a “ghost”: the keyboard lands on it, but the screen reader stays silent. Hide such elements with the hidden attribute or inert.
  • Check the effect in a real screen reader. On a Mac you have the built-in VoiceOver (Cmd + F5), and on Windows you can download the free NVDA.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.