Skip to content

WPShout Newsletter

Sign up for news, tips, and insights to help you build better websites.

Newsletter - Top banner

Complete List of WAI ARIA Roles and Their Uses

WAI ARIA Roles and Their Uses

Why understanding WAI ARIA roles and attributes is key to today’s landscape of the web? Let’s start at the core of the issue:

Web accessibility is the process of making your website equally usable to people of all abilities and disabilities. It’s about understanding that users with disabilities may use assistive technologies to access the web. As a website owner, it is your duty to ensure that you make your website adequately compatible with such assistive technologies.

WAI ARIA (Web Accessibility Initiative – Accessible Rich Internet Applications) is a W3C specification that defines roles, states, and properties for making web content and applications more accessible. WAI-ARIA 1.2 is the current W3C Recommendation, while WAI-ARIA 1.3 is still a draft. The roles and attributes in the specification help improve accessibility and make your DOM structure more readable by assistive technologies.

In this post, we look at every non-abstract WAI ARIA role set by W3C, grouped by category.

But before we do that, let’s go through some of the basics of working with WAI ARIA.

The four rules of ARIA use

There are many types of assistive technologies. A common one is a screen reader, which is used by partially or completely blind people. A screen reader parses the HTML DOM of a webpage and reads it out to the user. WAI ARIA roles and attributes help screen readers read out the relevant details. To get an understanding of how it works in practice, here is an older (2011) collection of videos of screen readers using ARIA. Some common tasks that you can accomplish using ARIA are:

  • Set checkpoints within a webpage
  • Announce dynamic parts of a webpage to assistive technologies
  • Improve keyboard navigation of a webpage

Before you set out to incorporate ARIA into your website, take a step back and review W3C’s rules for ARIA use. The Using ARIA note is now a Discontinued Draft, but W3C keeps its four rules there for reference:

  • Use native HTML elements and attributes over ARIA whenever possible.
  • Do not change native semantics, unless you really have to. In case there is a clash, create a div wrapper over the element and define a role.
  • All interactive ARIA controls must be usable with the keyboard.
  • Do not use role as presentation, or aria-hidden to true on a focusable element. This results in the user focusing on an empty element.

Beyond these four rules, give every interactive element an accessible name, usually its visible text or an aria-label or aria-labelledby value, so assistive technologies can announce what it does.

With these rules in mind, let us explore how you can use WAI ARIA roles in your website.

Types of WAI ARIA roles

Before we describe each role, let us look at the six categories of WAI ARIA roles:

  • Landmark roles typically denote large areas of a document. Some examples are banner, search, and region.
  • Widget roles help in making interactive elements accessible. button, checkbox, and radio are common examples of widget roles.
  • Window roles help in creating a sub-window within your webpage. The two roles that comprise window roles are alertdialog and dialog.
  • Document structure roles give information about a non-interactive, static section of the page. Common document structure roles are article, table, and heading.
  • Live region roles help you inform assistive technologies about dynamic content of a webpage. They work together with the aria-live attribute. alert, log, and timer are commonly used live region roles.
  • Abstract roles are the foundation on which other WAI ARIA roles are based on. Abstract roles are used by browsers and not developers.

You may also be interested in:

Comprehensive list of WAI ARIA roles

In this section, we look at every non-abstract WAI ARIA role, grouped by its category. For most document structure roles, browsers support a native HTML element with the same meaning, so use that element instead of the role.

Landmark roles

The banner ARIA role

As the name suggests, the banner role describes elements that contain informative content at the top of a page. These elements may include the title of a website, its logo, or the search bar. Here is the how you can use it in your code:

<div role="banner">
  <img src="logo.png" alt="Website Name" />
  <h1>Title of the Website</h1>
  <h2>Tagline</h2>
</div>

The complementary ARIA role

This landmark role marks a supporting section that relates to the main content but still makes sense on its own. These elements are generally sidebars or boxes with more information. The HTML tag <aside> provides native functionality, and you should use it whenever possible.

<div class="about-us" role="complementary">
  Some information
</div>

The contentinfo ARIA role

The contentinfo role is another landmark ARIA role. It contains information repeated at the end of every page. This generally includes copyright information, contact information, or privacy statements. When this information sits in a footer that covers the whole page, the native <footer> element already carries the contentinfo semantics.

<div role="contentinfo">
  &copy; All rights reserved.
</div>

The form ARIA role

The form role identifies a group of elements that together work like an HTML form, and it is exposed as a landmark only when it has an accessible name. Give it an aria-label or aria-labelledby value, and prefer the native <form> element whenever you can. If the form submits search criteria, use the search role instead.

The main ARIA role

The main role is a landmark ARIA role that is associated with the primary content of the document. The main content can then be further subdivided into other categories.

The navigation ARIA role

The navigation role is a landmark role that encompasses a group of links that you can use to navigate through a website.

The region ARIA role

The region role identifies a section the author deems significant, and every region must carry a label set with aria-labelledby or aria-label. Use it only for a section important enough that users will want to navigate to it, when no more specific landmark fits. The native <section> element becomes a region landmark once it has an accessible name.

The search ARIA role

The search role is a landmark role that contains the search section of a page, though the native <search> element, available across browsers since October 2023, now provides it without ARIA. It may contain the search bar, the search button and errors in the search form, if any. Adding role="search" to an existing search <form> is also acceptable.

Widget roles

The button ARIA role

The rules of WAI ARIA suggest that you use the HTML native functionality for clickable objects on a webpage. Occasionally, you may use a non-native element to function as a button. In such a situation, you should set the ARIA role of the element to button. When encountering this role, assistive technologies will treat the element as a button.

Give it tabindex="0" so it is focusable, add click and keydown handlers that respond to Enter and Space, and use the aria-pressed attribute only when the button acts as a toggle. A native <button> element gives you focusability and Enter and Space activation for free, though a toggle still needs aria-pressed and code that updates it.

<div id="form-submit" tabindex="0" role="button">Submit</div>

The checkbox ARIA role

The first rule of ARIA use explains the use of native HTML features. The native <input type="checkbox"> element already provides checkbox functionality, so prefer it whenever you can.

However, any other interactive control that the user can check should have the checkbox role. Elements with the checkbox role must also include the aria-checked attribute, which exposes the checkbox’s state to assistive technologies. Make it focusable with tabindex="0", let the Space key toggle it, and update aria-checked every time the state changes.

The combobox ARIA role

The combobox role marks an input that controls a popup, such as a listbox, tree, grid, or dialog, that helps the user set the input’s value. You must set aria-expanded on it to match the popup’s state, and the role carries an implicit aria-haspopup="listbox", so specify aria-haspopup yourself when the popup is something else.

The grid ARIA role

A widget can use the grid role when it contains one or more rows of cells that the user can navigate in two dimensions. The role itself adds no keyboard behavior: you must script focus management and arrow-key navigation between the cells.

The gridcell ARIA role

The gridcell role is complementary to the grid role, as it denotes cells within a grid. You should use the gridcell in absence of the <td> HTML tag. Each gridcell must sit inside an element with the row role. The following code snippet demonstrates the use of grid and gridcell together:

<div role="grid">
  <div role="row">
    <div role="gridcell">Data Point 1</div>
    <div role="gridcell">Data Point 2</div>
  </div>
</div>

The link role marks an interactive reference that navigates to another resource when activated, and the native <a> element with an href already provides it. If activating the element performs an action without navigating anywhere, use the button role instead.

The listbox ARIA role

The listbox role is a widget that lets the user select one or more items from a list of choices, where each item carries the option role. You must manage keyboard focus for its options, and the role has an implicit vertical orientation.

The menu ARIA role

The menu role is a widget that offers a list of choices to the user, usually rendered as a popup or overlay whose actions relate to the element that opened it. Activating an item performs its action and dismisses the menu, and you must manage keyboard focus for the items inside.

The menubar ARIA role

The menubar role is a menu that usually stays visible and is presented horizontally, like the menu bar of a desktop application. It has an implicit horizontal orientation.

The menuitem ARIA role

The menuitem role marks one option in a menu or menubar. Setting aria-haspopup="true" on it indicates that the item opens a sub-level menu.

The menuitemcheckbox ARIA role

The menuitemcheckbox role is a menu item with a checkable state, and it must expose that state with a required aria-checked value of true, false, or mixed.

The menuitemradio ARIA role

The menuitemradio role is a checkable menu item in a set where only one item can be checked at a time. It requires aria-checked, and checking one item should clear the previously checked item in its group.

The option ARIA role

The option role marks one selectable item inside a listbox. Show the selection with aria-selected="true" on the chosen option in a single-select listbox; in a multi-select one, put either aria-selected or aria-checked on every option, true on the selected options and false on the rest.

The progressbar ARIA role

The progressbar role displays the progress status of a task that takes a long time. When the progress is determinate, set aria-valuenow to the current value and update it as the task advances, but leave it unset for an indeterminate progressbar; the default range is 0 to 100 unless you set aria-valuemin and aria-valuemax.

The radio ARIA role

The radio role is a checkable input in a group of elements where only one can be checked at a time, and it requires aria-checked. Enclose the radios in an element with the radiogroup role, and prefer the native <input type="radio"> whenever you can.

The radiogroup ARIA role

The radiogroup role groups a set of radio buttons that affect the same value. Give it an accessible name with aria-label or aria-labelledby, ideally referencing a visible label.

The scrollbar ARIA role

The scrollbar role is a graphical object that controls the scrolling of content within a viewing area. You must set aria-valuenow to indicate the current thumb position, and the role has an implicit vertical orientation.

The searchbox ARIA role

The searchbox role is a type of textbox intended for specifying search criteria. The native <input type="search"> element already provides it.

The separator ARIA role

The separator role is a divider that separates sections of content or groups of menu items, and the native <hr> covers the static case. If the separator is focusable, for example a draggable splitter between two panels, it becomes a widget that requires aria-valuenow.

The slider ARIA role

The slider role is an input where the user selects a value from within a given range. You must set aria-valuenow, and the role has an implicit horizontal orientation.

The spinbutton ARIA role

The spinbutton role is a range control that expects the user to pick from discrete choices, usually through increment and decrement buttons, as in a quantity field. Set aria-valuenow when it has a value, plus aria-valuemin and aria-valuemax when there are bounds, and make the up and down arrow keys step the value.

The switch ARIA role

The switch role is a more specific form of the checkbox role. It represents the states on and off instead of checked and unchecked, through a required aria-checked value of true or false, and the mixed value is not supported.

The tab ARIA role

The tab role is the grouping label of a tab set, sitting inside a tablist and selecting which tabpanel gets rendered. Associate it with its panel through aria-controls, and set aria-selected="true" on the active tab.

The tablist ARIA role

The tablist role is the container for a set of tab elements, usually placed just before their panels. You must manage keyboard focus for its tabs, and it has an implicit horizontal orientation.

The tabpanel ARIA role

The tabpanel role is the container for the content associated with a tab. When a tab is active, its corresponding tabpanel must be rendered, and you can tie the two together with aria-labelledby on the panel pointing at the tab.

The textbox ARIA role

The textbox role contains an element that allows the user to enter free-form text. It is used in place of the <input type = "text" > element for single line text inputs, or the <textarea> tag for multi-line text input.

The tree ARIA role

The tree role is a widget that lets the user select one or more items from a hierarchically organized collection, such as a file browser, with treeitem children. You must manage keyboard focus for its items, and it has an implicit vertical orientation.

The treegrid ARIA role

The treegrid role is a grid whose rows can be expanded and collapsed in the same manner as a tree. As with grid, you must manage focus for its descendants.

The treeitem ARIA role

The treeitem role marks one item in a tree, and it can contain an expandable group of child items. If you do not nest groups to convey the hierarchy, set aria-level, aria-posinset, and aria-setsize explicitly on every treeitem.

Window roles

The alertdialog ARIA role

The alertdialog role is a type of dialog that contains an alert message, with initial focus going to an element inside it, such as a confirmation button. Unlike the plain alert role, it can receive a response from the user, so keep keyboard and mouse interaction inside the dialog while it is open, and give it an accessible name with aria-label or aria-labelledby.

The dialog ARIA role

The dialog role is a window ARIA role that signifies a sub-window separated from the rest of the webpage. Give the dialog an accessible name with aria-labelledby or aria-label, move keyboard focus into it when it opens, and keep focus inside a modal dialog until it closes; the dialog container itself does not need tabindex. An example of the dialog role is shown below:

<div role="dialog" aria-labelledby="dialog-title" aria-describedby="dialog-desc">
  <h2 id="dialog-title">Dialog Title</h2>
  <p id="dialog-desc">Dialog Content</p>
  <button>Close Dialog</button>
</div>

Document structure roles

The application ARIA role

The application role tells assistive technologies to treat an element and all its children like a desktop application, suspending the usual reading-mode interpretation of the content inside. Reserve it for very dynamic, desktop-like web applications whose interaction model no standard WAI ARIA widget role covers; most web apps and widgets do not qualify. When you use it, you take over all keyboard handling and focus management yourself, so give the region an accessible name and test it with a screen reader. Google Docs, Sheets and Slides are prominent web applications that have used this role.

<div role="application" aria-label="Document editor">...</div>

The article ARIA role

You should assign the article role to an element that contains an article or similar textual content within itself. Other use cases of the article role are comments and forum posts. Bear in mind that this role does not support any keyboard interaction, as assistive technologies usually read out the contents.

<div role="article">
  <h2>Article Title</h2>
  ...
</div>

The cell ARIA role

The cell role identifies an element as a cell in a tabular container that carries no column or row header information. An element with the cell role must be nested in an element with the row role, such as a <tr>; HTML has no <row> element. If a cell contains column or row header information, use the columnheader or rowheader role instead. Here’s an example use of the cell role:

<table>
  ...
  <tr role="row">
    <td role="cell">Data Point 1</td>
    <td role="cell">Data Point 2</td>
  </tr>
  ...
</table>

The columnheader ARIA role

The columnheader role marks a cell as the header for a column, and it is the structural equivalent of <th scope="col">. Like any cell, it must sit inside an element with the row role, and the native <th> element is the better choice whenever you can use it.

The comment ARIA role

The comment role denotes a comment or reaction to content on the page, or a reply to another comment, and it is proposed in the WAI-ARIA 1.3 draft rather than the published 1.2 Recommendation. Link the comment to the text it annotates by putting aria-details="thread-1" on the element that holds the commented text.

<div role="comment" id="thread-1">
  <h3>John Doe</h3>
  <p>Happy New Year.</p>
  <p><time datetime="2021-01-01T00:00">January 1 2021, 00:00</time></p>
</div>

The definition ARIA role

The definition role marks the definition of a term or concept, and it pairs with an element given the term role. The native <dfn> element already covers the term side of the pair.

The directory ARIA role

The directory role was meant for a static table of contents, but it has been deprecated since ARIA 1.2. Use a list, or the native list elements, instead.

The document ARIA role

The document role marks content that assistive technology users may want to browse in a reading mode. When focus moves to an element with this role, assistive technologies that have a reading mode may switch to it, so the role only changes anything when it sits on a focusable element, for example one with tabindex="0", holding static content inside a widget or an application region.

The feed ARIA role

The feed role marks a scrollable list of articles, where articles may be added to or removed from either end as the user scrolls. A feed may load more content infinitely when a user reaches its end.

This role lets screen readers use their browse-mode reading cursor to read through the stream and trigger the loading of more content. The children of a feed element should be <article> HTML tags.

<div role="feed" aria-busy="false">
  ...
  <article>...</article>
  <article>...</article>
  ...   
</div>

The figure ARIA role

The figure role is assigned to elements that contain a figure inside a page, in absence of an HTML element. A figure may consist of one or more images, or other content that puts a break to the regular flow of text. Images, code snippets, media players and example text are typical examples.

<div role="figure">
  ...
  <img src="fig.png" alt="image description" />
  ...
</div>

The generic ARIA role

The generic role is the nameless container role that div and span elements carry by default, with no semantic meaning of its own. It exists mainly so browsers can build the accessibility tree, so do not set it in your own markup.

The graphics roles

The WAI-ARIA Graphics Module defines graphics-document, graphics-object, and graphics-symbol for describing the structure and meaning of graphical content, for example inside SVG charts. They are subclasses of the document, group, and img roles.

The group ARIA role

The group role collects a set of related interface objects that assistive technologies should not include in a page summary or table of contents, which is what sets it apart from region. Typical uses are fieldset-like groupings and collections of siblings inside a widget.

The heading ARIA role

The heading role signifies an element that acts as a heading when the native h1 to h6 elements cannot be used. You must also set aria-level to give the heading its level. An example of the heading role is:

<div role="heading" aria-level="2">This is the second level heading of a page</div>

The img ARIA role

The ARIA img role helps you encompass multiple elements in a page that should be considered as a single image, and you must give it an accessible name with aria-label or aria-labelledby. These elements can be images, code snippets, text, emojis or other content that combine into one image. The WAI-ARIA 1.3 draft adds image as a synonym of this role.

The list ARIA role

The list ARIA role encompasses a list of items. It is normally used in conjunction with the listitem role. You should use it only if the semantic HTML lists are not used for the purpose.

The listitem ARIA role

The listitem role identifies an item within a list of items. Here is a code snippet that demonstrates the use of list and listitem together:

<div role="list">
  <div role="listitem">Item 1</div>
  <div role="listitem">Item 2</div>
  ...
</div>

The mark ARIA role

The mark role is a document structure role, not a landmark, added in the WAI-ARIA 1.3 draft, and it identifies content highlighted for reference or notation, such as search result matches. The HTML <mark> element provides this functionality natively, so prefer it.

The math ARIA role

The math role marks content as a mathematical expression. Mark the expression up in MathML where possible, and if you fall back to an image of a formula, give it a text alternative that describes the expression as it would be spoken.

The meter ARIA role

The meter role is a document structure role that shows a scalar measurement within a known range, such as disk usage, and it requires aria-valuenow. Do not use it to indicate progress, because that is what progressbar is for, and prefer the native <meter> element where it fits.

The none and presentation ARIA roles

The none and presentation roles are synonyms that strip an element’s implicit semantics from the accessibility tree while leaving its content in place, for example on a layout table. They are not a substitute for aria-hidden="true", and the fourth rule of ARIA use bans them on focusable elements.

The note ARIA role

The note role marks content that is parenthetic or ancillary to the main content it supplements. If it needs a programmatic association with that content, use aria-details when the note holds structured or interactive content, and aria-describedby for a brief static note.

The row ARIA role

The row role identifies a row in a table. Use it only when you cannot use the native <tr> element. An element with the row role may contain a cell, gridcell, or a column header. Usually, a row role is placed in a table or a grid.

The rowgroup ARIA role

The rowgroup ARIA role is a combination of rows within a table. It contains one or more elements with the row role, which in turn hold the cells. Here is a code snippet that demonstrates its use:

<div role="table" ...>
   <div id="desc">Table Description</div>
   <div role="rowgroup"> <!-- contains table header -->
      <div role="row">
         <span role="columnheader">Table Header</span>
      </div>
   </div>
   <div role="rowgroup"> <!-- contains table data -->
     <div role="row">
        <span role="cell">Table Row 1</span>
     </div>
     <div role="row">
        <span role="cell">Table Row 2</span>
     </div>
     ...
   </div>
</div>

The rowheader ARIA role

The rowheader role marks a cell as the header for its row, the structural equivalent of <th scope="row">. It must sit inside an element with the row role.

The suggestion ARIA role

The suggestion role, proposed in the WAI-ARIA 1.3 draft, marks a single proposed change to content, as in a collaborative editor. It is built from exactly one insertion child, one deletion child, or one of each.

The table ARIA role

The table role identifies the HTML element that contains a table structure. Within this structure, you may have headers, descriptions, rows, and columns. You should use the table role instead of the native <table> HTML element if it’s not available.

<div role="table" ...>
   <div role="rowgroup"> <!-- contains table header -->
      ...
   </div>
   <div role="rowgroup"> <!-- contains table data -->
     ...
   </div>
</div>

The term ARIA role

The term role marks a word or phrase that has, or expects, a definition, and you can point it at the definition with aria-details. The native <dfn> element covers this, and you should not put the role on interactive elements such as links.

The toolbar ARIA role

The toolbar role is a compact collection of commonly used function buttons or controls, like an editor’s formatting bar. When a page contains more than one toolbar, you must label each one, and the role has an implicit horizontal orientation.

The tooltip ARIA role

The tooltip role is a contextual popup that displays a description for an element, usually on hover or keyboard focus. Reference it from the element it describes with aria-describedby.

MDN lists roles such as associationlist and its associationlistitemkey and associationlistitemvalue items, blockquote, caption, code, deletion, emphasis, insertion, paragraph, strong, subscript, superscript, and time for completeness, but notes that in most cases they are rarely, if ever, useful.

Live region roles

The alert ARIA role

the list

The alert role announces to a user the content of an element, when it is updated dynamically. Assistive technologies will detect change in the contents of elements with this role and read out new content. Ensure that you do not use this role on static elements.

You can associate the alert role as shown below. A simple use case could be a div that displays errors in a form before submission.

<div class="form-errors" role="alert">
    The alert will trigger when the content of this element changes.
</div>

The log ARIA role

The log role is a live region where new information is added in a meaningful order and old information may disappear, such as a chat history or an error log. It has an implicit aria-live value of polite, so updates are announced without interrupting the user.

The marquee ARIA role

The marquee role is a live region for non-essential information that changes frequently, such as a stock ticker or an ad banner.

The status ARIA role

The status role is a live region for advisory information that is not important enough to justify an alert, such as a save confirmation. It has implicit aria-live="polite" and aria-atomic="true" values, and it should not receive focus when its content changes.

The timer ARIA role

The timer role may be used to tell assistive technologies that it contains a numerical counter, which changes with the passage of time. You can use JavaScript to manipulate the data within the timer role.

Abstract roles

Abstract roles such as command, composite, input, landmark, range, roletype, section, sectionhead, select, structure, widget, and window exist for the ontology that structures the specification. Browsers use them to organize and streamline the document, but authors must not use them in content, because doing so conveys no meaningful information to assistive technologies or users.

Final thoughts on WAI ARIA roles in 2026

Accessibility ensures that you treat users of all abilities and disabilities equally. However, you may ask what is the correct time to ensure that your website is accessible? The ideal time to make a website accessible is from the very beginning. Enhancing digital accessibility on an existing project can be cumbersome and end up being a redundant task. Therefore, it makes sense for you to incorporate WAI ARIA techniques in your development cycle as soon as possible.

…

Don’t forget to join our crash course on speeding up your WordPress site. Learn more below:

SUPPORT OUR WORK

WPShout has been delivering weekly tutorials, reviews, and deep dives for WordPress developers and business owners since 2009. To maintain our independence and continue creating high-quality content, we increasingly rely on donations from our community.

Donate today to support independent technical publishing.

Donation amount
Donation frequency
Yay! 🎉 You made it to the end of the article!
WPShout Editorial
Share:

0 Comments
Most Voted
Newest Oldest