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
Example
#<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>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
#<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 overaria-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.politewaits until the reader finishes speaking, andassertiveinterrupts right away. The region must exist on the page before you change its content.
More examples
#<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>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-labelto 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 thehiddenattribute orinert.- 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
#- roleAn ARIA role tells screen readers what an element is: a button, a tab, a message, navigation.
- hiddenHides an element: the browser neither displays nor exposes it.
- <label>A form field’s label. Clicking the label moves the cursor to the field.
- <button>A clickable button: submits a form, clears it, or runs an action on the page.
- inertDisables interaction with an element and its descendants: clicking, focus and screen readers.
Practise it in lessons
#Spotted a mistake or missing an example? Write to us.