ARIA roles

What are ARIA roles?

ARIA roles are attributes from the Web Accessibility Initiative's Accessible Rich Internet Applications (WAI-ARIA) specification. Each ARIA role attribute tells assistive technologies what an element is and how it behaves, filling in the semantic meaning that native HTML elements don't provide on their own. Screen readers and other assistive technologies use ARIA roles to build an accurate accessibility tree of a web page.

At a glance

Why are ARIA roles important when it comes to accessibility?

Modern websites aren't built from plain HTML alone. A lot of web application interfaces are made of generic, non-semantic elements – divs and spans styled and scripted to look and act like tabs, menus, dialogs, or switches.

Visually, these components work fine. Programmatically, a div is just a div. Without extra information, assistive technologies have no way of knowing it's meant to behave like a checkbox or a dialog.

Accurate ARIA roles are just as important on sites built mostly from semantic HTML elements. Even a well-marked-up page usually has a handful of dynamic or custom pieces – a comment thread, a dismissible banner, or an in-page search, for example – that native HTML can't fully describe on its own.

ARIA roles carry that meaning across the gap. By adding a role attribute, you give the element a semantic meaning that screen readers, braille displays, and other assistive technologies can pick up through the accessibility APIs built into the browser and operating system.

WCAG's Name, Role, Value criterion helps ensure that every interactive element communicates an accessible name, its role, and its current state to assistive technologies.

Get this wrong, and screen reader users can't tell what an element is or how to interact with it. Get it right, and a custom widget becomes just as usable with a screen reader as a native HTML equivalent, and you improve accessibility for the whole page rather than one component.

Keyboard-only users benefit just as much as screen reader users, since a correctly implemented role usually comes paired with the keyboard focus and keyboard interaction a component needs.

Voice control software and switch devices depend on that same structure, reading the accessibility tree to figure out which elements exist and what commands apply to them. Get the roles right, and each one of these assistive technologies benefits from the same fix.

How do ARIA roles work?

You add a role to an element with the role attribute, for example role="dialog". The browser exposes that role to its accessibility APIs, enabling screen readers, switch devices, and other assistive technologies to learn what the element is.

A role attribute only changes what's reported to assistive technologies. It doesn't change how the element looks, and – this is the part people miss – it doesn't add any keyboard interaction on its own.

If you give a div role="button", you still need to add keyboard focus and a keyboard event handler yourself, or screen reader users and keyboard-only users won't be able to activate it the same way they could with a native <button>.

The WAI-ARIA specification groups every role into six main categories:

1. Widget roles – Interactive UI components that usually need JavaScript for their behavior, such as the checkbox role, switch role, textbox role for free-form text, and grid role. A grid, for example, is a widget that contains one or more rows of cells, and each gridcell role mimics a native table cell.
2. Document structure roles – Roles that describe the structure of content on the page rather than something interactive, such as the article role, document role, heading role, mark role, comment role, and listitem role. This category also covers the application role, which tells assistive technologies to treat an entire section like a desktop-style application rather than a standard web page. The feed role is a good example of a useful role in this category: a feed enables screen readers to use the browse mode reading cursor to read and scroll through a stream of rich content that may continue scrolling infinitely as more items load.

• Landmark roles – Regions that help screen reader users jump straight to key navigation regions and other sections of a page, such as the banner role, contentinfo role, the main role for a page's primary content, search role, and region role.
• Live region roles – Roles for content that updates dynamically, such as the alert role, the log role, the status role, and the timer role. A timer, for instance, works like a numerical counter that tracks elapsed or remaining time.
• Window roles – Roles for sub-windows layered on top of the main page, primarily the dialog role and the alertdialog role.
• Abstract roles – Base roles that the specification uses to organize the ontology of every other role. They're not meant for developers to use directly in HTML. Adding one to a page, such as role="widget" or role="structure", produces invalid role attribute values with no real meaning for assistive technologies.

A couple of document structure roles are worth a closer look because they don't map to an obvious HTML element. The ARIA img role and figure role identify a figure inside page content made of multiple elements – one or more images bundled with code snippets or other content that doesn't fit a regular flow of text – and present that group to assistive technologies as a single image.

Used consistently, elements presenting equivalent content expose the same role, so assistive technologies treat them the same way every time.

Most modern browsers and screen readers support this full set of roles, but several document structure roles – article, list, heading, and table among them – now have native HTML equivalents that do the same job without an extra attribute: <article>, <ul>, <h1>–<h6>, and <table>.

Here's a short ARIA roles list showing common roles from each category, and the native HTML element that already covers the same semantics where one exists:

An ARIA roles example

A live region role is one of the more common places developers reach for ARIA. Say a form shows a confirmation message after a user input is submitted:

<div role="alert">
  Your changes have been saved.
</div>

‍The alert role tells assistive technologies to announce the message right away, without the user needing to move their keyboard focus to find it. It's useful for time-sensitive information, like form errors or save confirmations, where waiting for the user to notice a visual change isn't reliable.

A landmark role works differently. It doesn't announce anything on its own, it just labels a region so screen reader users can jump to it directly:‍‍

<form role="search">
  <input type="text" aria-label="Search the site">
  <button type="submit">Search</button>
</form>

With role="search", a screen reader user browsing by region can navigate straight to the search functionality instead of tabbing through the entire page to find it.

ARIA roles vs. native HTML elements

ARIA roles and native HTML elements often describe the same semantics, but they aren't interchangeable in practice.

One of the first rules of ARIA use is to prefer a native HTML element or attribute over a role attribute whenever one with the same semantics and behavior already exists. ARIA roles earn their place when you're building a genuinely custom widget, like a combobox or a tree view, that HTML has no native equivalent for.

That doesn't mean roles are a lesser option. They're the right tool when the interface genuinely goes beyond what HTML alone can describe, like a live region that needs to announce updates, or a composite widget with several moving parts.

The rule is really about avoiding unnecessary work: reinventing a native HTML element's behavior with a role and a pile of JavaScript, when the browser would have given you that behavior for free.

Common mistakes or misconceptions

• Reaching for a role instead of native HTML. Adding role="button" to a div is only half the job. Without matching keyboard focus and keyboard interaction, the element looks right but doesn't behave right for keyboard and screen reader users.
• Using abstract roles directly. Roles like role="widget" or role="structure" exist for the specification itself, not for markup. Using one produces an invalid role attribute value.
• Adding a role without its required ARIA states or ARIA attributes. A checkbox role without aria-checked, for example, leaves the checkbox's state invisible to screen reader users – the role alone doesn't communicate whether it's on or off.
• Overusing landmark or region roles. A page with a dozen landmark roles creates noise for screen reader users trying to build a mental map of the layout. Use them for genuinely significant sections, not every div on the page.
• Assuming a role overrides visual styling. A role attribute changes what's reported to the accessibility tree, not what's rendered on the page. Changing an element's role never changes its appearance, so visual design and semantic meaning need to be handled as two separate jobs.