role
An ARIA role tells screen readers what an element is: a button, a tab, a message, navigation.
- Applies to
- All HTML elements, although not every role may be given to every element
Example
#<style>
.fake-button {
display: inline-block;
margin-top: 10px;
padding: 6px 12px;
border-radius: 6px;
background: #3f3f46;
cursor: pointer;
}
</style>
<button type="button" onclick="this.textContent = 'Progress saved'">Save progress (button)</button>
<br>
<div class="fake-button" role="button" tabindex="0" onclick="this.textContent = 'Progress saved'">
Save progress (div with a role)
</div>Both elements react to a mouse click. Now move to them with the Tab key and press Enter or Space: the <button> works and the <div role="button"> does not, because a role does not add keyboard handling.
Definition and usage
#The role attribute gives an element a role from the WAI-ARIA specification. It is information for assistive technologies such as screen readers: it says what the element is and what to expect from it. With role="button" the reader will say “button”, and the content of an element with role="alert" will be read as soon as it appears, even if the user is in a different part of the page.
Most HTML elements have a built-in role: <button> is a button, <nav> is navigation, <a href> is a link, and <ul> is a list. That is why the first rule of ARIA applies: if an HTML element with the meaning and behavior you need exists, use it instead of adding a role to a <div> or <span>. The role attribute is for situations where HTML has no ready-made element, such as tabs or messages announced live.
A role only changes how assistive technologies see the element. It changes neither the look nor the behavior: a <div role="button"> still does not get focus with the Tab key and does not react to Enter or Space, so you have to add all of that yourself. Do not override roles without need, either. A heading with role="button" stops being a heading, so if a heading is supposed to expand something, put a button inside it.
Syntax
#<element role="role-name">…</element>The most common roles
#button
<button>
An element that performs an action. Apart from a<button>element, it also needstabindex="0"and handling of the Enter and Space keys.link
<a href>
A link to another page or a place on the page. Apart from an<a>element, it needs focus and handling of the Enter key.navigation
<nav>
A landmark with the main links. Screen readers let you jump to it quickly.main
<main>
The main content of the page. There should be one such area on a page.banner
<header>
The header of the whole page. A<header>has this role only when it is not inside an<article>,<section>,<main>or a similar element.contentinfo
<footer>
The footer of the whole page with information about the site. The same rule applies as forbanner.complementary
<aside>
Supplementary content, for example a side panel with recommended lessons.search
<search>
A search area. It used to be added to a form; today the<search>element has it.img
<img>
Several elements that together form one image, for example a group of icons or emoji. It needs a name, for example inaria-label.list, listitem
<ul>, <ol>, <li>
A list and its items. They restore the list meaning when Safari stops announcing lists after bullets are removed withlist-style: none.alert
none
An urgent message, for example a form error. The reader usually interrupts what it is saying and reads it right away. Use sparingly.status
<output>
A status message, for example “Saved”. The reader reads it when it finishes its current utterance.tablist, tab, tabpanel
none
Tabs. They require arrow key handling and thearia-selectedandaria-controlsattributes.presentation, none
none
Removes the element’s meaning, for example a table used only for layout. It does not work on elements that can receive focus.
More examples
#<button type="button"
onclick="document.getElementById('cart-status').textContent = 'Course added to cart'">
Add to cart
</button>
<p id="cart-status" role="status"></p>The empty element with role="status" is on the page from the start. When a script writes text into it, the screen reader reads the message once it finishes its current utterance. For urgent errors, use role="alert".
Browser support
#Widely available
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Before you add a
role, check whether the right HTML element is enough. It is better not to use ARIA at all than to use it wrong. - A role is a promise. If you give an element
role="tab"orrole="menu", you must provide the keyboard handling a screen reader user expects from tabs or a menu. - You can check the effect in developer tools. In Chrome, the Elements panel has an Accessibility tab that shows the role and name of the selected element.
Related entries
#- aria-*ARIA attributes describe elements for screen readers: they give them names, link them to descriptions and report their state.
- <button>A clickable button: submits a form, clears it, or runs an action on the page.
- <nav>A block of primary navigation links: a menu, a table of contents, breadcrumbs.
- <main>The page’s main, unique content. Only one should be visible per page.
- tabindexDecides whether an element can be focused with the Tab key and in what order.
Practise it in lessons
#Spotted a mistake or missing an example? Write to us.