Roles

A role identifies an element’s type or function to assistive technologies and their users.

Meeting the Web Accessibility Standard

When an element’s role can be programmatically determined and reflects the element's visually presented function in the page, this meets WCAG 2 Success Criterion 1.3.1 Info and Relationships (Level A).

When an element’s role can be programmatically determined and reflects the element's actual function in the page, this meets WCAG 2 Success Criterion 4.1.2 Name, Role, Value (Level A).

On this page

What’s a role?

A role is a user interface (UI) element’s type or function, what it means or does in the web page. This semantic information about an element is expressed in the HTML markup, making it programmatically determinable — it can be read by a machine.

The role is a principal characteristic of accessible objects in the accessibility tree, the model of the page that’s communicated to assistive technologies (AT) through the operating system’s accessibility API. The role tells AT users what an element is and how to interact with it. While not every element has or needs a role, every interactive UI component needs one.

For more on semantics and how web pages are made accessible to AT users, see the following Knowledge Areas:

How roles are defined

There is a predefined set of roles that HTML elements can have. They are defined in the Web Accessibility Initiative’s Accessible Rich Internet Applications (WAI-ARIA) specification from the W3C.

Note: Accessible Rich Internet Applications (WAI-ARIA), or just ARIA, is a W3C technology for programmatically adding semantic information about content — such as its name, role, state or other properties. ARIA is intended to be used when the host markup language — for example, HTML — does not include elements or attributes with the semantics needed to represent the content.

When ARIA is used correctly, it enables assistive technologies (AT), especially screen readers, to relay the necessary semantic information about the content to the user.

As a rule, do not use ARIA if a native HTML element or attribute with the needed semantics or features already exists.

For more information, see:

ARIA defines several different categories of roles:

For a list of all the ARIA roles, see:

How roles are assigned

Implicit ARIA semantics

Note: Most HTML elements have default semantics that map to the semantics defined in the ARIA specification. These are an element’s “implicit WAI-ARIA semantics”.

For instance, when a browser comes across an <h1>, it exposes the element in the accessibility tree with a role of heading, as that’s the default ARIA role for each of the <h1>–<h6> elements. And as the heading role requires an aria-level property for the heading element’s level in the heading hierarchy, browsers use the number in the heading element's tag name to set the aria-level property which also gets exposed in the accessibility tree.

Some HTML attributes map directly to ARIA states or properties. For example, when it comes across the placeholder attribute on a <textarea>, a browser will expose that attribute in the accessibility tree as if it were the aria-placeholder property.

For more information, see Implicit WAI-ARIA Semantics — Accessible Rich Internet Applications (WAI-ARIA) — W3C.

Not all HTML elements map to an ARIA role, but they are still exposed in the accessibility tree in some way. Some elements are not exposed through the accessibility API at all because they provide no meaningful information to the user.

For a list of HTML elements showing how they map to accessibility APIs and any default ARIA role semantics they have, see HTML Element Role Mappings — HTML Accessibility API Mappings (HTML-AAM) —W3C.

Explicitly declared ARIA roles

Authors can use the role attribute to assign many HTML elements a role that’s different from their default role, including roles that do not have an equivalent in HTML.

Example of assigning an element a different role

Here, the role attribute is used to assign a role of button to a normal <div>:

<div role="button">Submit application</div>

This markup causes the browser to expose the <div> in the accessibility tree as having a button role, which is how AT will present the element to users.

Note: Changing an element’s role only changes how the element is exposed in the accessibility tree for AT users. It does not change the element’s functionality or how it is visually displayed.

If an element’s role is associated with specific functionality or keyboard interaction, these need to be added, typically using JavaScript. For example, a <div> with role="button" will need event handlers scripted to make the button actionable by pointer and keyboard input.

For a list of HTML elements and the roles that can be explicitly assigned to them, see Document conformance requirements for use of ARIA attributes in HTML — ARIA in HTML — W3C.

Conflicts between implicit and explicit role semantics

If a page author assigns an HTML element a valid ARIA role that has a corresponding role in the accessibility API, browsers are expected to use that explicitly declared role’s semantics when exposing the element in the accessibility tree.

Browsers will not expose the HTML element’s native or implicit semantics unless the explicit declared ARIA role requires additional ARIA states or properties that are not permitted on that HTML element.

For more information, see:

When to assign a role

ARIA was created to support the development of accessible custom web applications and content. ARIA includes roles for many UI components that authors want to build, but that do not exist in HTML, such as web-based spreadsheets or simple tabbed interfaces.

ARIA roles need to be assigned only when the element’s implicit ARIA role needs to be changed. Authors can, by judiciously applying the correct ARIA roles to the appropriate HTML elements, programmatically express the intended semantics of their custom widget to AT. These semantics get conveyed to the users so that they know what the custom widget represents and how to interact with it.

Depending on the role that’s assigned to an element, it can require child elements with specific roles. For example, an element with a role of list is required to contain or own elements with a role of listitem. For more, see the ARIA specification’s section on Required Owned Elements.

For each ARIA role’s required owned elements, see the role’s entry in the WAI-ARIA specification.

Note: ARIA can be a dangerous technology if not applied correctly, since it changes how content is represented to AT users. This is especially the case for screen reader users who cannot see the screen and rely on what their screen reader tells them about the content.

Developers are strongly urged to fully understand how the ARIA that they use in their HTML will impact people who use AT.

Rules for using ARIA roles

When using ARIA, there are a number of important rules and best practices that all developers should be familiar with. These are documented in the W3C’s guide for developers, Using ARIA.

The Using ARIA guide lists 5 rules of ARIA. The first 4 rules relate to the use of ARIA roles, and are summarised below. For more detail on these rules and other best practices for using ARIA, see also When to use ARIA — ARIA and HTML — Learn Accessibility — web.dev.

Rule #1: Do not use ARIA

If there are native HTML elements that can represent the role semantics of the content being developed, use those native HTML elements instead of ARIA.

For more, see the First Rule of ARIA Use — Using ARIA — W3C.

Rule #2: Do not override default roles

Changing an element’s role only changes its representation in the accessibility tree, and not its appearance or functionality. As such, users could easily be confused when a specific bit of content identified one way by their AT comes with unexpected semantics or functionality of the repurposed HTML element.

For more, see the Second Rule of ARIA Use — Using ARIA — W3C.

Rule #3: Make interactive ARIA keyboard accessible

If an ARIA role is assigned to an interactive control, make sure that the control responds to keyboard input as well as pointer or touch input.

For more, see:

Rule #4: Do not hide or remove semantics from focusable elements

The presentation and none roles do the same thing: they remove an element’s default semantics and it is not exposed in the accessibility tree. The element’s content is still exposed in the accessibility tree, but the element itself becomes no more meaningful than a <div> or <span>.

Focusable elements are expected to be interactive. If, for example, a screen reader user sets focus to an element that has a role of none, the user will not be provided any role information that might indicate to them what the element is and how to interact with it.

For more, see:

Role parity with HTML

The ARIA specification continues to evolve toward parity with HTML — that is, a state where every HTML element that gets exposed in the accessibility tree has a corresponding role defined in ARIA. As ARIA develops, new roles are added, some of which will become the default role for HTML elements that currently do not have a corresponding role.

No corresponding role

Some clearly meaningful HTML elements, such as <input type="color">, currently have no default ARIA role — they have no implicit WAI-ARIA semantics. However, such elements are nonetheless exposed in the accessibility tree in other non-ARIA ways that help AT users know what the element is and how to interact with it. Exactly how the element is exposed in the accessibility tree depends on which browser and accessibility API are being used.

As work on ARIA continues, elements that have no corresponding ARIA role today may get one in the next version of the specification.

Because these elements without a corresponding ARIA role still have meaningful semantics, avoid using them when repurposing HTML elements for use with ARIA. For more, refer to the second rule of ARIA use.

The generic role

Some elements, such as <div> and <span>, are exposed in the accessibility tree, but are otherwise meaningless containers with no specific role of their own.

To enable role parity with HTML, the generic role was introduced so that browsers and other user agents had an ARIA role to assign to these semantically meaningless elements.

Note: The generic role is not for authors to assign to an element. Instead, to make a semantic element into a meaningless container, that is, to remove its role from being represented in the accessibility tree, explicitly declare role="none" or role="presentation".

While <div> and <span> have no meaningful semantics, some elements with a generic role do get presented to users in ways that say something about the element. For example, <b> elements are exposed visually with bold font styles, and this style information is available to screen reader users, even if screen readers do not announce it by default.

As <div> and <span> have no default role semantics, they are usually the 2 best HTML elements to reuse when creating custom content or interaction with ARIA. For more, refer to the second rule of ARIA use.

Not mapped

Some HTML elements, such as <meta> and <style> are not exposed to users at all and so have no role, and cannot be assigned any role by the author.

Testing for roles

Use your web browser’s developer tools to inspect the accessibility information for the page you are viewing. For instructions, see Inspecting the accessibility tree — Knowledge Area: Browsers, code and assistive technologies.

For any element in question, check that: