This page lists reference pages covering all the WAI-ARIA roles discussed on MDN. For a full list of roles, see Using ARIA: Roles, States, and Properties
ARIA roles provide semantic meaning to content, allowing screen readers and other tools to present and support interaction with 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, semantic elements have a role;
<p> has the "paragraph" role,
<input type="radio"> has the "radio" role. Non-semantic elements do not have a role;
<span> without added semantics return null. The
role attribute can provide semantics.
ARIA roles are HTML attributes. They are added to elements using role="role type", where role 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.
<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.
There are 6 categories of ARIA roles:
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 element 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
<dd> in a
<dl>), directory, document, figure (use
<figure> instead), group, heading (use
<h6>), img (use
<picture> instead), list (use either
<ol> instead), listitem (use
<li> instead), meter (use
<meter> instead), row (use the
<table>), rowgroup (use
<tbody>), rowheader (use <tr col="row">), separator (use
<hr> if it doesn't have focus), table (use
<table>), and term (use
<dt> in a
<dl>). These are included for completeness, but in most cases are rarely, if ever, useful.
Avoid using button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, progressbar, radio, and textbox, which we've included for completeness. For most, semantic equivalents with accessible interactivity are available and supported. See the individual role documention for more information.
Composite widget roles
Note that there is also a widget role (
role="widget"), which is an abstract role and not in the widget role category.
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.
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:
Window roles define sub-windows to the main document window, within the same window, such as pop up modal dialogs:
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.
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. Authors MUST NOT use abstract roles in content." - The WAI-ARIA specification
The following are the reference pages covering the WAI-ARIA roles discussed on MDN.
- ARIA: alert role
alertrole is for important, and usually time-sensitive, information. The
alertis a type of
statusprocessed as an atomic live region.
- ARIA: alertdialog role
- The alertdialog 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
applicationrole indicates to assistive technologies that an element and 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 apps are not considered applications for this purpose.
- ARIA: article role
articlerole 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
bannerrole is for defining a global site header, which usually includes a logo, company name, search icon, and possibly a slogan, generally at the top of the page.
- ARIA: button role
buttonrole is for clickable elements that trigger a response when activated by the user. Adding
role="button"tells the screen reader the element is a button, but provides no button functionality. Use
- ARIA: cell role
cellvalue of the ARIA role 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 of
- ARIA: checkbox role
checkboxrole is for checkable interactive controls. Elements containing
role="checkbox"must also include the
aria-checkedattribute to expose the checkbox's state to assistive technology.
- ARIA: columnheader role
columnheadervalue of the ARIA role attribute identifies an element as being a cell in a row contains header information for a column, similar to the native
thelement with column scope.
- ARIA: combobox role
comboboxrole is for input that controls another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the input.
- ARIA: command role
commandrole defines a widget that performs an action but does not receive input data.
- ARIA: comment role
commentlandmark role semantically denotes a comment/reaction to some content on the page, or to a previous comment.
- ARIA: complementary role
complementarylandmark 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 the HTML <aside> element instead.
- ARIA: composite role
compositeabstract role indicates a widget that may contain navigable descendants or owned children.
- ARIA: contentinfo role
contentinforole 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
definitionARIA role indicates the element is a definition of a term or concept.
- ARIA: dialog role
dialogrole 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
directoryrole was for a list of references to members of a group, such as a static table of contents.
- ARIA: document role
documentrole is for focusable content within complex composite widgets or applications for which assistive technologies can switch reading context back to a reading modelement.
- ARIA: feed role
feedis a dynamic scrollable
articlesin which articles are added to or removed from either end of the list as the user scrolls. A
feedenables 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 ARIA
figurerole 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
formrole can be used to identify a group of elements on a page that provide equivalent functionality to an HTML form.
- 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
- The gridcell role is used to make a cell in a grid or treegrid. It is intended to mimic the functionality of the HTML
tdelement for table-style grouping of information.
- ARIA: group role
grouprole can be used for sets of UI feature not intended to be included in a page summary or table of contents by assistive technologies.
- ARIA: heading role
headingrole defines this element as a heading to a page or section, with the
aria-levelattribute providing for more structure.
- ARIA: img role
- The ARIA
imgrole 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
inputabstract role is a generic type of widget that allows user input.
- ARIA: landmark role
- A landmark is an important subsection of a page. The
landmarkrole 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: list role
- The ARIA
listrole can be used to identify a list of items. It is normally used in conjunction with the
listitemrole, which is used to identify a list item contained inside the list.
- ARIA: listbox role
listboxrole is used for lists from which a user may select one or more items which are static and, unlike HTML
selectelements, may contain images.
- ARIA: listitem role
- The ARIA
listitemrole can be used to identify an item inside a list of items. It is normally used in conjunction with the
listrole, which is used to identify a list container.
- ARIA: log role
logrole is used to identify an element that creates a live region where new information is added in a meaningful order and old information may disappear.
- ARIA: main role
mainlandmark 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
markrole semantically denotes HTML elements containing text that is marked/highlighted for reference purposes. This is semantically equivalent to the HTML
markelement. If possible, you should use this element instead.
- ARIA: marquee role
marqueeis a type of live region containing non-essential information which changes frequently.
- ARIA: math role
mathrole indicates that the content represents a mathematical expression.
- ARIA: menu role
- ARIA: menubar role
- ARIA: menuitem role
- ARIA: menuitemcheckbox role
- ARIA: menuitemradio role
- ARIA: meter role
meterrole is used to identify an element being used as a meter.
- ARIA: navigation Role
navigationrole is used to identify major groups of links used for navigating through a website or page content.
- ARIA: none role
nonerole is a synonym for the
presentationrole; they both remove the element with the role and its descendants from the accessibility tree.
- ARIA: note role
noterole suggests a section whose content is parenthetic or ancillary to the main content.
- ARIA: option role
optionrole is used for selectable items in a
- ARIA: presentation role
presentationrole and its synonym
noneremove an elements implicit native semantics, such as headings, lists, etc., from the accessibility tree.
- ARIA: radio role
radiorole is one of a group of checkable buttons, in a
radiogroup, where no more than one of the buttons can be checked at a time.
- ARIA: range role
rangeabstract role is a generic type of structure role representing a range of values.
- ARIA: region role
regionrole 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
roletyperole, an abstract role, is the base role from which all other ARIA roles inherit.
- ARIA: row role
- An element with
role="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 a
treegrid, and optionally within a
- ARIA: rowgroup role
- An element with
role="rowgroup"is a group of rows within a tabular structure. A
rowgroupcontains one or more rows of cells, grid cells, column headers, or row headers within a
- ARIA: rowheader role
- An element with
role="rowheader"is a cell containing header information for a row within a tabular structure of a
- ARIA: scrollbar role
- ARIA: search role
searchrole 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
- ARIA: section role
sectionrole, an abstract role, is superclass role for renderable structural containment components.
- ARIA: sectionhead role
sectionheadrole, an abstract role, is superclass role for labels or summaries of the topic of its related section.
- ARIA: select role
selectrole, an abstract role, is superclass role for form widgets that allows the user to make selections from a set of choices.
- ARIA: separator role
separatorrole indicates the element is a divider that separates and distinguishes sections of content or groups of menuitems. The implicit ARIA role the native thematic break
- ARIA: status role
statusrole defines a live region containing advisory information for the user that is not important enough to be an
- ARIA: structure role
structurerole is for document structural elements.
- ARIA: suggestion role
suggestionlandmark role semantically denotes a single proposed change to an editable document. This should be used on an element that wraps an element with an
insertionrole, and one with a
- ARIA: switch role
- The ARIA
switchrole is functionally identical to the checkbox role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, the
switchrole represents the states "on" and "off."
- ARIA: tab role
- The ARIA
tabrole indicates an interactive element inside a
tablistthat, when activated, displays its associated
- ARIA: table role
tablevalue of the ARIA
roleattribute identifies the element containing the role as having a non-interactive table structure containing data arranged in rows and columns, similar to the native
- ARIA: tablist role
- ARIA: tabpanel role
- The ARIA tabpanel role indicates
- ARIA: term role
termrole can be used for a word or phrase with an optional corresponding
- ARIA: textbox role
textboxrole is used to identify an element that allows the input of free-form text. Whenever possible, rather than using this role, use an
inputelement with type="text", for single-line input, or a
textareaelement for multi-line input.
- ARIA: timer role
timerrole 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.
- ARIA: toolbar role
toolbarrole defines the containing element as a collection of commonly used function buttons or controls represented in a compact visual form.
- ARIA: tooltip role
tooltipis a contextual text bubble that displays a description for an element that appears on pointer hover or keyboard focus.
- ARIA: tree role
- ARIA: treegrid role
- ARIA: treeitem role
- ARIA: widget role
widgetrole, an abstract role, is an interactive component of a graphical user interface (GUI).
- ARIA: window role
windowrole defines a browser or app window.