This article explains aria-roledescription in plain language, starting with how native and ARIA roles work, then showing how it can override how a role is announced, without creating a new role.
What are roles?
When you use a website, many HTML elements on the page have specific roles.
For example, an element might be a button, a link, a heading, or a region containing a particular part of the page.
Screen readers use these roles to help people understand the purpose of different elements. For example, a screen reader might announce:
“Submit, button”
The word “Submit” is the element’s name, while “button” identifies the element’s role.
Native HTML roles
Sometimes the role is provided automatically by the HTML element. This is known as a native role.
For example:
<button>Submit</button>A screen reader already knows this element is a button, so the developer does not need to add role="button".
ARIA roles
Sometimes HTML does not provide enough information about what an element is being used for, so developers can add a role using ARIA.
This commonly happens in two situations.
First, developers may use a generic HTML element such as a <div> or <span> to build a custom widget. These elements do not provide a useful role on their own, so an ARIA role may be needed to explain what the element represents.
In the following example, role="region" tells assistive technologies that this otherwise generic element should be treated as a region. The aria-label gives the region a name.
<div
role="region"
aria-label="Featured products"
>
</div>Second, an HTML element may already have a native role, but developers can sometimes replace that role with a permitted ARIA role when they are building a different type of control.
In the following example, the <input> would normally have the role of textbox. Adding role="combobox" changes the role exposed to assistive technologies to combobox.
<input
type="text"
role="combobox"
>This new role provides more specific information about the control. Instead of understanding it as a simple text field, a screen reader user can understand that it is a combobox, which may provide additional options or suggestions as they type.
Note that a working combobox needs more than the role attribute alone – attributes such as aria-expanded, and usually aria-controls or aria-haspopup, are also required. The example above is simplified to show the role change only.
So what does aria-roledescription do?
aria-roledescription can give an existing role a more specific or useful description.
Imagine a web-based presentation containing a series of slides. Each slide might have the ARIA role of region and an accessible name:
<div
role="region"
aria-labelledby="slide-heading"
>
<h2 id="slide-heading">Quarterly results</h2>
</div>A screen reader might therefore announce:
“Quarterly results, region”
But “region” does not make it clear that this part of the page is a slide in a presentation. The developer could add aria-roledescription="slide":
<div
role="region"
aria-labelledby="slide-heading"
aria-roledescription="slide"
>
<h2 id="slide-heading">Quarterly results</h2>
</div>Now the screen reader may announce:
“Quarterly results, slide”
The underlying role is still region, but the screen reader may present its role description as “slide” instead of “region”.
This gives the screen reader user more useful context.
It does not create a new role
aria-roledescription doesn’t let developers invent new roles.
In the example above, slide has not become a new ARIA role. The element’s actual role is still region.
aria-roledescription changes how that existing role may be described to the screen reader user. It does not change the underlying role or its meaning.
That existing role could be:
- a native role, such as the
buttonrole automatically provided by a<button> - an ARIA role, such as
role="region"
So the simplest way to remember it is:
aria-roledescriptiongives a more specific way of describing a role that already exists. It does not create a new role or change what the element actually is.
When should I use aria-roledescription?
Use aria-roledescription when the existing role is correct, but a more specific description would help a screen reader user understand what the element represents.
The ARIA specification recommends limiting its use to situations where:
- a general container role, such as
regionorgroup, could be described more clearly in a particular context - an existing widget role is correct, but a more specific description would make its purpose easier to understand
aria-roledescription should be used carefully because it can replace a familiar role description with different wording. If that wording is unclear or unfamiliar, it could make the element harder to understand or use.
The existing native or ARIA role should still accurately describe the element. aria-roledescription should only provide a more specific way of describing that role, not change what the role means.