WAI-ARIA Roles

ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with an object in a way that is consistent with user expectations of that type of object.ARIA roles can be used to describe elements that don't natively exist in HTML or exist but don't yet have full browser support.

By default, many semantic elements in HTML have a role; for example,<input type="radio"> has the "radio" role. Non-semantic elements in HTML do not have a role;<div> and<span> without added semantics returnnull. Therole attribute can provide semantics.

ARIA roles are added to HTML elements usingrole="role type", whererole type is the name of a role in the ARIA specification. Some roles require the inclusion of associated ARIA states or properties; others are only valid in association with other roles.

For example,<ul role="tabpanel"> will be announced as a 'tab panel' by screen readers. However, if the tab panel doesn't have nested tabs, the element with the tabpanel role is not in fact a tab panel and accessibility has actually been negatively impacted.

The ARIA states and properties associated with each role are included in the role's pages, with each attribute also having a dedicated page.

Document Structure roles are used to provide a structural description for a section of content. Most of these roles should no longer be used as browsers now support semantic HTML elements with the same meaning. The roles without HTML equivalents, such as presentation, toolbar and tooltip roles, provide information on the document structure to assistive technologies such as screen readers as equivalent native HTML tags are not available.

For most document structure roles, semantic HTML equivalent elements are available and supported. Avoid using:

application
article (use<article>)
cell (use<td>)
columnheader (use<th scope="col">)
definition (use<dfn>)
directory
document
figure (use<figure> instead)
group
heading (useh1 throughh6)
img (use<img> or<picture> instead)
list (use either<ul> or<ol> instead)
listitem (use<li> instead)
meter (use<meter> instead)
row (use the<tr> with<table>)
rowgroup (use<thead>,<tfoot> and<tbody>)
rowheader (use<th scope="row">)
separator (use<hr> if it doesn't have focus)
table (use<table>)
term (use<dfn>)

These are included for completeness, but in most cases are rarely, if ever, useful:

2. Widget roles

Widget roles are used to define common interactive patterns. Like document structure roles, some widget roles have the same semantics as well-supported native HTML elements, and therefore should be avoided. The key difference is that widget roles typically require JavaScript for interaction, while document structure roles often do not.

Avoid usingbutton,checkbox,gridcell,link,menuitem,menuitemcheckbox,menuitemradio,option,progressbar,radio, andtextbox, which we've included for completeness. For most, semantic equivalents with accessible interactivity are available and supported. See the individual role documentation for more information.

Composite widget roles

Avoid usinggrid,listbox, andradiogroup, which we've included for completeness. See the individual role documentation for more information.

Note that there is also a widget role (role="widget"), which is an abstract role and not in the widget role category.

3. Landmark roles

Landmark roles provide a way to identify the organization and structure of a web page. By classifying and labeling sections of a page, structural information conveyed visually through layout is represented programmatically. Screen readers use landmark roles to provide keyboard navigation to important sections of a page. Use these sparingly. Too many landmark roles create "noise" in screen readers, making it difficult to understand the overall layout of the page.

4. Live region roles

Live Region roles are used to define elements with content that will be dynamically changed. Sighted users can see dynamic changes when they are visually noticeable. These roles help low vision and blind users know if content has been updated. Assistive technologies, like screen readers, can be made to announce dynamic content changes:

5. Window roles

Window roles define sub-windows to the main document window, within the same window, such as pop up modal dialogs:

6. Abstract roles

Abstract roles are only intended for use by browsers to help organize and streamline a document. They should not be used by developers writing HTML markup. Doing so will not result in any meaningful information being conveyed to assistive technologies or to users.

Avoid usingcommand,composite,input,landmark,range,roletype,section,sectionhead,select,structure,widget, andwindow.

Note:Don't use abstract roles in your sites and applications. They are for use by browsers. They are included for reference only.

Warning:"Abstract roles are used for the ontology. AuthorsMUST NOT use abstract roles in content." - TheWAI-ARIA specification

Roles defined on MDN

The following are the reference pages covering the WAI-ARIA roles discussed onMDN.

ARIA: alert role: Thealert role is for important, and usually time-sensitive, information. Thealert is a type ofstatus processed as an atomic live region.
ARIA: alertdialog role: Thealertdialog role is to be used on modal alert dialogs that interrupt a user's workflow to communicate an important message and require a response.
ARIA: application role: Theapplication role indicates to assistive technologies that an elementand all of its children should be treated similar to a desktop application, and no traditional HTML interpretation techniques should be used. This role should only be used to define very dynamic and desktop-like web applications. Most mobile and desktop web appsare not considered applications for this purpose.
ARIA: article role: Thearticle role indicates a section of a page that could easily stand on its own on a page, in a document, or on a website. It is usually set on related content items such as comments, forum posts, newspaper articles or other items grouped together on one page.
ARIA: banner role: Thebanner role is for defining a global site header, which usually includes a logo, company name, search feature, and possibly the global navigation or a slogan. It is generally located at the top of the page.
ARIA: button role: Thebutton role is for clickable elements that trigger a response when activated by the user. Addingrole="button" tells the screen reader the element is a button, but provides no button functionality. Usebutton orinput withtype="button" instead.
ARIA: cell role: Thecell value of the ARIArole attribute identifies an element as being a cell in a tabular container that does not contain column or row header information. To be supported, the cell must be nested in an element with the role ofrow.
ARIA: checkbox role: Thecheckbox role is for checkable interactive controls. Elements containingrole="checkbox" must also include thearia-checked attribute to expose the checkbox's state to assistive technology.
ARIA: columnheader role: Thecolumnheader value of the ARIA role attribute identifies an element as being a cell in a row contains header information for a column, similar to the nativeth element with column scope.
ARIA: combobox role: Thecombobox role identifies an element as either aninput or abutton that controls another element, such as alistbox orgrid, that can dynamically pop up to help the user set the value. A combobox can be either editable (allowing text input) or select-only (only allowing selection from the popup).
ARIA: command role: Thecommand role defines a widget that performs an action but does not receive input data.
ARIA: comment role: Thecomment role semantically denotes a comment/reaction to some content on the page, or to a previous comment.
ARIA: complementary role: Thecomplementarylandmark role is used to designate a supporting section that relates to the main content, yet can stand alone when separated. These sections are frequently presented as sidebars or call-out boxes. If possible, use theHTML <aside> element instead.
ARIA: composite role: Thecompositeabstract role indicates a widget that may contain navigable descendants or owned children.
ARIA: contentinfo role: Thecontentinfo role defines a footer, containing identifying information such as copyright information, navigation links, and privacy statements, found on every document within a site. This section is commonly called a footer.
ARIA: definition role: Thedefinition ARIA role indicates the element is a definition of a term or concept.
ARIA: dialog role: Thedialog role is used to mark up an HTML based application dialog or window that separates content or UI from the rest of the web application or page. Dialogs are generally placed on top of the rest of the page content using an overlay. Dialogs can be either non-modal (it's still possible to interact with content outside of the dialog) or modal (only the content in the dialog can be interacted with).
ARIA: directory role: Thedirectory role was for a list of references to members of a group, such as a static table of contents.
ARIA: document role: Thedocument role is for focusable content within complex compositewidgets orapplications for which assistive technologies can switch reading context back to a reading mode.
ARIA: document structural roles: ARIA document-structure roles are used to provide a structural description for a section of content.
ARIA: feed role: Afeed is a dynamic scrollablelist ofarticles in which articles are added to or removed from either end of the list as the user scrolls. Afeed enables screen readers to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads.
ARIA: figure role: The ARIAfigure role can be used to identify a figure inside page content where appropriate semantics do not already exist. A figure is generally considered to be one or more images, code snippets, or other content that puts across information in a different way to a regular flow of text.
ARIA: form role: Theform role can be used to identify a group of elements on a page that provide equivalent functionality to an HTML form. The form is not exposed as a landmark region unless it has anaccessible name.
ARIA: generic role: Thegeneric role creates a nameless container element which has no semantic meaning on its own.
ARIA: grid role: The grid role is for a widget that contains one or more rows of cells. The position of each cell is significant and can be focused using keyboard input.
ARIA: gridcell role: Thegridcell role is used to make a cell in agrid ortreegrid. It is intended to mimic the functionality of the HTMLtd element for table-style grouping of information.
ARIA: group role: Thegroup role identifies a set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies.
ARIA: heading role: Theheading role defines this element as a heading to a page or section, with thearia-level attribute providing for more structure.
ARIA: img role: The ARIAimg role can be used to identify multiple elements inside page content that should be considered as a single image. These elements could be images, code snippets, text, emojis, or other content that can be combined to deliver information in a visual manner.
ARIA: input role: Theinput abstract role is a generic type of widget that allows user input.
ARIA: landmark role: A landmark is an important subsection of a page. Thelandmark role is an abstract superclass for the aria role values for sections of content that are important enough that users will likely want to be able to navigate directly to them.
ARIA: link role: Alink widget provides an interactive reference to a resource. The target resource can be either external or local; i.e., either outside or within the current page or application.
ARIA: list role: The ARIAlist role can be used to identify a list of items. It is normally used in conjunction with thelistitem role, which is used to identify a list item contained inside the list.
ARIA: listbox role: Thelistbox role is used for lists from which a user may select one or more items which are static and, unlike HTMLselect elements, may contain images.
ARIA: listitem role: The ARIAlistitem role can be used to identify an item inside a list of items. It is normally used in conjunction with thelist role, which is used to identify a list container.
ARIA: log role: Thelog role is used to identify an element that creates alive region where new information is added in a meaningful order and old information may disappear.
ARIA: main role: Themain landmark role is used to indicate the primary content of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the main function of an application.
ARIA: mark role: Themark role denotes content which is marked or highlighted for reference or notation purposes, due to the content's relevance in the enclosing context.
ARIA: marquee role: Amarquee is a type oflive region containing non-essential information which changes frequently.
ARIA: math role: Themath role indicates that the content represents a mathematical expression.
ARIA: menu role: Themenu role is a type of composite widget that offers a list of choices to the user.
ARIA: menubar role: Amenubar is a presentation ofmenu that usually remains visible and is usually presented horizontally.
ARIA: menuitem role: Themenuitem role indicates the element is an option in a set of choices contained by amenu ormenubar.
ARIA: menuitemcheckbox role: Amenuitemcheckbox is amenuitem with a checkable state whose possible values aretrue,false, ormixed.
ARIA: menuitemradio role: Amenuitemradio is checkable menuitem in a set of elements with the same role, only one of which can be checked at a time.
ARIA: meter role: Themeter role is used to identify an element being used as a meter.
ARIA: navigation role: Thenavigation role is used to identify major groups of links used for navigating through a website or page content.
ARIA: none role: Thenone role is a synonym for thepresentation role; they both remove an element's implicit ARIA semantics from being exposed to the accessibility tree.
ARIA: note role: Anote role suggests a section whose content is parenthetic or ancillary to the main content.
ARIA: option role: Theoption role is used for selectable items in alistbox.
ARIA: presentation role: Thepresentation role and its synonymnone remove an element's implicit ARIA semantics from being exposed to the accessibility tree.
ARIA: progressbar role: Theprogressbar role defines an element that displays the progress status for tasks that take a long time.
ARIA: radio role: Theradio role is one of a group of checkable radio buttons, in aradiogroup, where no more than a single radio button can be checked at a time.
ARIA: radiogroup role: Theradiogroup role is a group ofradio buttons.
ARIA: range role: Therange abstract role is a generic type of structure role representing a range of values.
ARIA: region role: Theregion role is used to identify document areas the author deems significant. It is a generic landmark available to aid in navigation when none of the other landmark roles are appropriate.
ARIA: roletype role: Theroletype role, anabstract role, is the base role from which all other ARIA roles inherit.
ARIA: row role: An element withrole="row" is a row of cells within a tabular structure. A row contains one or more cells, grid cells or column headers, and possibly a row header, within agrid,table ortreegrid, and optionally within arowgroup.
ARIA: rowgroup role: An element withrole="rowgroup" is a group ofrows within a tabular structure. Arowgroup contains one or more rows ofcells,grid cells,column headers, orrow headers within agrid,table ortreegrid.
ARIA: rowheader role: An element withrole="rowheader" is acell containing header information for arow within a tabular structure of agrid,table ortreegrid.
ARIA: scrollbar role: Ascrollbar is a graphical object that controls the scrolling of content within a viewing area.
ARIA: search role: Thesearch role is used to identify the search functionality; the section of the page used to search the page, site, or collection of sites.
ARIA: searchbox role: Thesearchbox role indicates an element is a type oftextbox intended for specifying search criteria.
ARIA: section role: Thesection role, an abstract role, is a superclass role for renderable structural containment components.
ARIA: sectionhead role: Thesectionhead role, an abstract role, is superclass role for labels or summaries of the topic of its related section.
ARIA: select role: Theselect role, an abstract role, is superclass role for form widgets that allows the user to make selections from a set of choices.
ARIA: separator role: Theseparator role indicates the element is a divider that separates and distinguishes sections of content or groups of menuitems. The implicit ARIA role of the native thematic breakhr element isseparator.
ARIA: slider role: Theslider role defines an input where the user selects a value from within a given range.
ARIA: spinbutton role: Thespinbutton role defines a type of range that expects the user to select a value from among discrete choices.
ARIA: status role: Thestatus role defines alive region containing advisory information for the user that is not important enough to be analert.
ARIA: structure role: Thestructure role is for document structural elements.
ARIA: suggestion role: Thesuggestion role semantically denotes a single proposed change to an editable document. This should be used on an element that wraps an element with aninsertion role, and one with adeletion role.
ARIA: switch role: The ARIAswitch role is functionally identical to thecheckbox role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, theswitch role represents the states "on" and "off."
ARIA: tab role: The ARIAtab role indicates an interactive element inside atablist that, when activated, displays its associatedtabpanel.
ARIA: table role: Thetable value of the ARIArole attribute identifies the element containing the role as having a non-interactive table structure containing data arranged in rows and columns, similar to the nativetable HTML element.
ARIA: tablist role: Thetablist role identifies the element that serves as the container for a set oftabs. The tab content are referred to astabpanel elements.
ARIA: tabpanel role: The ARIAtabpanel is a container for the resources of layered content associated with atab.
ARIA: term role: Theterm role can be used for a word or phrase with an optional correspondingdefinition.
ARIA: textbox role: Thetextbox role is used to identify an element that allows the input of free-form text. Whenever possible, rather than using this role, use aninput element withtype="text", for single-line input, or atextarea element for multi-line input.
ARIA: timer role: Thetimer role indicates to assistive technologies that an element is a numerical counter listing the amount of elapsed time from a starting point or the remaining time until an end point. Assistive technologies will not announce updates to a timer as it has an implicitaria-live value ofoff.
ARIA: toolbar role: Thetoolbar role defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form.
ARIA: tooltip role: Atooltip is a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus.
ARIA: tree role: Atree is a widget that allows the user to select one or more items from a hierarchically organized collection.
ARIA: treegrid role: Thetreegrid role identifies an element as being grid whose rows can be expanded and collapsed in the same manner as for atree.
ARIA: treeitem role: Atreeitem is an item in atree.
ARIA: widget role: Thewidget role, anabstract role, is an interactive component of a graphical user interface (GUI).
ARIA: window role: Thewindow role defines a browser or app window.

Help improve MDN

Learn how to contribute

This page was last modified on⁨Aug 14, 2025⁩ byMDN contributors.

View this page on GitHub •Report a problem with this content

Movatterモバイル変換