Accessible Rich Internet Applications (WAI-ARIA) Version 1.0

Base role from which all other roles in this taxonomy inherit.

Properties of this role describe the structural and functional purpose of objects that are assigned this role (known in RDF terms as "instances"). A Role is a concept that can be used to understand and operate instances.

Note: This is used for the ontology and authors must not use this role in content.

A component of a Graphical User Interface (GUI).

Widgets are discrete user interface elements with which the user can interact. Widget roles all map to standard features in accessibility APIs.

Note: This is used for the ontology and authors must not use this role in content.

A document structural element.

Roles for document structure support the accessibility of dynamic Web content by helping assistive technology to determine active content vs. static document content. Structural roles by themselves do not all map to accessibility APIs, but are used to create widget roles or assist content adaptation.

The taxonomy of structural roles is likely to evolve as new use cases are added to the scope of this specification.

Note: This is used for the ontology and authors must not use this role in content.

A widget that may contain navigable descendants or owned children.

The composite widget SHOULD exist as a single navigation stop within the larger navigation system of the web page. Once the composite widget has focus, it SHOULD provide a separate navigation mechanism for users to document elements that are descendants or owned children of the composite element.

Descendants of this role MUST NOT have the "nameFrom" value of "subtree" set. This role and its descendants must not have a childrenArePresentational value of "true".

Note: This is used for the ontology and authors must not use this role in content.

Browser or application window.

Elements with this role have a window-like behavior in a GUI context, regardless of whether they are implemented as a window in the OS. This is helpful when there is the visual appearance of a window that is merely a styled section of the document.

Note: This is used for the ontology and authors must not use this role in content.

Generic type for widgets for which users can input a value.

A form widget that allows the user to make selections from a set of choices.

An element with role select MUST contain elements with role option.

Note: This is used for the ontology and authors must not use this role in content.

A widget that allows the user to select one or more items from a list of choices.

Items within the list are static and may contain images. List boxes contain children whose role is option.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

Although listbox inherits the expanded state, if there is a use case to use that state, authors should consider using a combobox instead.

Combobox is a presentation of a select, where users can type to select an item.

Combobox is the combined presentation of a single line textbox with a drop down select widget. The combobox may be editable. Typically editable combo boxes are used for autocomplete behavior, and the autocomplete property would be used on the child textbox.

NOTE: In XForms [XFORMS] the same select can have one of 3 appearances: combo-box, drop-down box, or group of radio-buttons. Many browsers (if not all of them) allow users to type in a drop-down select as well. This specification does not constrain the presentation of the combobox.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

A selectable item in a list represented by a select.

An option MUST appear inside an element with select role.

A widget that has three possible values: "true", "false", or "mixed".

Many checkboxes do not use the "mixed" value, and thus are effectively boolean checkboxes. However, the checked state supports the "mixed" value to support cases such as installers where an option has been partially installed.

A group of radio buttons.

A radiogroup is a type of select list that can only have single entries checked, not mutliple. User agents MUST enforce that only one radio button in a radiogroup can be checked at the same time. When another button is checked, previously checked buttons become unchecked (their checked state becomes "false").

An option in single-select list.

Elements with role radio MUST be be explicitly grouped in order to indicate which ones affect the same value. This should be done by enclosing them in an element with role radiogroup. If it is not possible to make the radio buttons DOM children of the radiogroup, use the owns property on the radiogroup element to indicate the relationship.

Inputs that allow free-form text as their value.

If the multiline property is true, the widget accepts line breaks within the input, as in a HTML textarea. Otherwise this is a simple text box.

Intended use is in languages that do not have a text input object (such as SVG), or cases in which an element with different semantics is repurposed as an input box. Another use is for a rich text edit textbox, or one that validates input as users type (perhaps marking specific subregions with errors with the invalid state ). Content authors MAY also use this role when additional states or properties are applied to a standard text input widget. This is to indicate to the user agent that it must process additional states and properties such as invalid and required.

Represents a range of values that can be set by the user.

Note: This is used for the ontology and authors must not use this role in content.

A user input where the user selects a value from within a given range.

A slider represents the current value and range of possible values via the size of the slider and position of the thumb. It is typically possible to add or subtract to the value by using directional keys such as arrow keys.

A form of range that expects a user to select from amongst discrete choices.

A spinbutton typically allows the user to select from the given range through the use of an up and down button on the keyboard. Visibly, the current value is incremented or decremented until a maximum or minimum value is reached. This functionality SHOULD be accomplished programmatically through the use of up and down arrows on the keyboard.

Allows for user-triggered actions.

Buttons are mostly used for discrete, atomic actions. Standardizing the appearance of buttons enhances recognition as buttons and arraying them compactly in toolbars, for example.

Buttons support the optional state pressed. Buttons with a non-empty pressed state are toggle buttons. When pressed is "true" the button is depressed, when pressed is "false" it is not depressed. If the state is not present, the button is a simple command button.

Interactive reference to a resource.

Activating the link causes the user agent to navigate to that resource.

Offers a list of choices to the user.

A menu is often a list of links to important sections of a document or a site. The menu role is appropriate when the list of links is presented in a manner similar to a menu on a desktop application.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

A container of menu items (items with role menuitem).

The menubar role is used to create a menubar similar to those found in Windows, the Mac, and Gnome desktops. A menubar is used to create a consistent climate of frequently used commands. Navigation behavior SHOULD be similar to the typical menu bar graphical user interface.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

A collection of commonly used functions represented in compact visual form.

The toolbar is often a subset of functions found in a menubar, designed to reduced user effort in using these functions.

If this is not keyboard accessible the actions defined in the toolbar MUST be reproduced in an accessible, device independent fashion.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

An option in a group of choices contained in a menu.

A menuitem MAY be disabled. Each menu item MAY activate a new sub-menu, which is indicated with the haspopup property.

Defines a menuitem which is checkable.

The checked state indicates whether the menu item is checked, unchecked, or mixed.

Indicates a menuitem which is part of a group of menuitemradio roles, only one of which can be checked at a time.

User agents MUST enforce that only one menuitemradio in a group can be checked at the same time. When another widget is checked, previously checked widget become unchecked (their checked state becomes "false").

Menu items SHOULD be in an element with role menu in order to identify that they are related widgets, and MAY also be separated into a group by a separator, or an element with an equivalent role from the native markup language.

A popup that displays a description for an element when a user passes over or rests on that element. Supplement to the normal tooltip processing of the user agent.

Objects with this role should be referenced through the use of describedby, at latest by the time the tooltip is displayed.

A container for the resources associated with a tab.

Note: There MUST be a means to associate a tabpanel element with its associated tab in a tablist. Using the labelledby property on the tabpanel to reference the tab is the recommended way to achieve this.

For detailed information about how to use tab panels, see the TabPanel Widget in WAI-ARIA Best Practices ([ARIA-PRACTICES], Section 9.2).

A list of tabs, which are references to tabpanels.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

A header for a tabpanel.

tab is used as a grouping label, providing a link for selecting the tab content to be rendered to the user. If the tab or an object in the associated tabpanel has focus, the tab is the active one in the list.

One (and only one) of the tabs in the tablist MUST be the current tab. The tabpanel associated with the current tab MUST be rendered to the user. Other tabpanels SHOULD be hidden from the user until the user selects the tab associated with that tabpanel.

User agents manage the determination and indication of the current tab. There is no property in the taxonomy for this.

A form of a list having groups inside groups, where sub trees can be collapsed and expanded.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

An option item of a tree. This is an element within a tree that may be expanded or collapsed.

A collection of treeitems to be expanded and collapsed are enclosed in a group.

A renderable structural containment unit in a document or application.

Note: This is used for the ontology and authors must not use this role in content.

Labels or summarizes the topic of its related section.

Note: This is used for the ontology and authors must not use this role in content.

Content that contains related information.

The document role informs screen readers of the need to augment browser keyboard support in order to allow users to visit and read any content within the document region. In contrast, additional commands are not necessary for screen reader users to read text withn a region with role="application", where all text should be semantically associated with focusable elements. An important trait of documents is that they have some text which is not associated with widgets or groups thereof.

To properly set the role of document, an author should set the document role on an element which encompasses the entirety of the region for which assistive technology browser navigation mode is applied.If it applies to the entire Web page, it should be set on the root note for content, e.g., body in HTML or svg in SVG.

Documents MUST have a document title or label. This should be suitable for use as a navigation preview or table-of-contents entry for the page section in question. The label SHOULD come from one of the following sources:

• The title element in HTML labels the entire document;
• Any group element in SVG may contain a non-empty title element;
• The element with the document role may have a labelledby property referencing one or more elements with non-empty text content.

Region is a large perceivable section on the web page.

This role defines a group of elements that together form a large perceivable section, that the author feels should be included in a summary of page features. A region MUST have a heading, provided via an instance of the heading role or using the labelledby property to reference an element. A region does not necessarily follow the logical structure of the content, but follows the perceivable structure of the page.

When defining regions of a web page, authors should consider using standard document landmark roles. If the definition of these regions are inadequate, authors should use the region role and provide the appropriate title text.

A heading for a section of the page.

This indicates that an object serves as a header. Often, headings will be referenced with the labelledby property of the section for which they serve as a header. If headings are organized into a logical outline, the level property can be used to indicate the nesting level.

Group of non-interactive list items.

Lists contain children whose role is listitem, or elements whose role is group which in turn contains children whose role is listitem.

A single item in a list.

A section of user interface objects which would not be included in a page summary or table of contents by an assistive technology.

Contrast with region which is sections of user interface objects that should be included in a page summary or table of contents.

Authors should use a group to form logical collection of items in a widget such as children in a tree widget forming a collection of siblings in a hierarchy, or a collection of items having the same container in a directory. Therefore, proper handling of group by assistive technologies must be determined by the context in which it is provided.

Groups may also be nested. If the author believes a section is significant enough in terms of the entire delivery unit web page then the author should assign the section a role of region or a standard landmark role.

Group members that are outside the DOM subtree of the group would need to have explicit relationships assigned to participate in the group using the owns property.

A grid contains cells of tabular data arranged in rows and columns (e.g., a table).

This does not necessarily imply presentation. The grid construct describes relationships between data such that it may be used for different presentations. Grids allow the user to move focus between grid cells with two dimensional navigation.

Grids MUST contain rows with role row, which in turn contain cells. Grid cells may be focusable. Grids MAY have row and column headers, provided with rowheader and columnheader roles, which also assist the user agent in supporting navigation. Grid cells MAY have contents determined by a calculation.

Grid cells with the selected state set can be selected for user interaction, and multiple cells can be selected if the multiselectable property of the grid is true. Grids may be used for spreadsheets like those in Open Office, Microsoft Office, etc.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

A row of grid cells.

Rows contain gridcells, and thus serve to organize the grid.

In a treegrid, rows MAY be expandable, using the expanded state to indicate the present status. This is not the case for an ordinary grid, in which the expanded state is not present.

A cell in a grid.

Grid cell may be active, editable, and selectable. Cells may have relationships such as controls to address the application of functional relationships.

Grid cells should explicitly indicate which header cells are relevant to them. They do this by referencing elements with role rowheader or columnheader using the describedby property.

In a treegrid, cells MAY be expandable and use the expanded state. If the expanded property is provided, it applies only to the individual cell. It is not a proxy for the container row, which also can be expanded. The main use case for providing this property on a cell is pivot table type behavior.

A table cell containing header information for a row.

Rowheader can be used as a row header in a table or grid. It also could be used in a pie chart to show a similar relationship in the data.

The rowheader establishes a relationship between it and all cells in the corresponding row. It is a structural equivalent to an HTML th element with a "row" scope.

A table cell containing header information for a column.

Columnheader can be used as a column header in a table or grid. It could also be used in a pie chart to show a similar relationship in the data.

The columnheader establishes a relationship between it and all cells in the corresponding column. It is a structural equivalent to an HTML th element with a "column" scope.

Note: because grid cells are organized into rows, there is not a single container element for the column. The column is the set of gridcells in a particular position within their respective row containers.

A grid whose rows can be expanded and collapsed in the same manner as for a tree.

Instances of this role MUST manage focus of descendants, as described in Managing Focus.

Descriptive content for a page element.

A description MUST be referenced from the element it describes via describedby.

A list of references to members of a single group.

Authors SHOULD use this role for static tables of contents. This includes tables of contents built with lists, including nested lists. Dynamic tables of contents, however, would be a tree.

Note: directories do not have to contain links. They can have simply unlinked references.

A container for a collection of elements that form an image.

An img can contain captions and descriptive text, as well as multiple image files that when viewed together give the impression of a single image. An img represents a single graphic within a document, whether or not it is formed by a collection of drawing objects. Elements with a role of img MUST have alternative text or a label associated via the labelledby property.

An element whose role is decorative, not meaningful, and does not need to be mapped to the accessibility API.

The intended use is when an element is used to change the look of the page but does not have all the functional, interactive, or structural relevance implied by the element type.

Example use cases:

• A layout table;
• An object in HTML whose content is decorative like a white space image or decorative object;
• An image used for white space;
• A div in HTML used to force line breaks before and after its contents.

The user agent MAY choose not to present all structural aspects of the element being repurposed. For example, for a table marked as presentation, the user agent would remove the table, td, th, tr, etc. elements from the accessibility API mapping, while preserving the individual text elements within them. Because the user agent knows to ignore the structural aspects implied in a table, no harm is done by using a table for layout.

User agents should ignore elements with the presentation role for the purpose of determining the containment of items with ARIA roles. For example, in the following code sample:

<ul role="group">
  <li role="presentation">
    <a role="presentation>...</a>
  </li>
</ul>

the a should be considered a child of the ul element with the group role.

A line or bar that separates and distinguishes sections of content.

This is a visual separator between sections of content. For example, separators are found between groups of menu items in a menu.

Content that represents a mathematical expression.

This is for sections that represent math, such as images and ASCII art, but are not in a formal mathematical language. Such images MUST be labeled by text that can be converted to an accessible format, using the describedby property with a reference to a description of the math expression as it would be spoken. This is designed to facilitate conversion to speech. The text description should have no special markup used to control a speech device. Authors MAY store image alternative text in the image formats themselves. In these scenarios the alternative text from the image SHOULD also be brought into the text of the document and referenced by the describedby property.

A software unit executing a set of tasks for its users.

The intent is to hint to the assistive technology to switch its normal browsing mode functionality to one in which they would for an application. Screen readers have a browse navigation mode where keys, such as up and down arrows, are used to browse the document. This breaks use of these keys by a web application.

To properly set the role of application, an author should set the application role on an element which encompasses the entirety of the region for which assistive technology browser navigation mode is applied. If it applies to the entire Web page, it should be set on the root node for content, e.g., body in HTML or svg in SVG.

For example, an email application has a document and an application in it. The author would want to use typical application navigation mode to cycle through the list of emails. Much of this navigation would be defined by the application author. However, when reading an email message the content should appear in a region with a document role in order to use browsing navigation.

All non-decorative static text or image content inside the application must be either associated with a form widget or group via labelledby or describedby, or separated out into an element with role of document or article of its own.

Applications MUST have a document title or label. This should be suitable for use as a navigation preview or table-of-contents entry for the page section in question. The label SHOULD come from one of the following sources:

• The title element in HTML labels the entire document;
• Any group element in SVG may contain a non-empty title element;
• The element with the application role may have a labelledby property referencing one or more elements with non-empty text content.

A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response.

Dialog boxes SHOULD have a title, which may be provided with a labelledby property if other mechanisms are not available. They MUST have a focused item, i.e., a descendant element that has the keyboard focus, which is managed by the user agent.

A message with important information.

Alerts are used to convey messages to alert the user. In the case of audio warnings this is an accessible alternative for a hearing impaired user. The alert role goes on the container of the subtree containing the alert message. Alerts are specialized forms of the status role, which should be processed as an atomic live region.

Alerts do not require user input and therefore should not receive focus. Since alerts do not receive focus users SHOULD NOT be required to close an alert. The user agent MAY fire an accessibility alert event, when the alert is created, provided one is specified by the intended accessibility API. If an alert requires focus to close the alert, then an alertdialog SHOULD be used instead.

A separate window (may be simulated) with an alert, where initial focus goes to the window or a widget within it.

Alert dialogs are used to convey messages to alert the user. The alertdialog role goes on the container of the subtree containing the alert message.

Unlike alert, alertdialog can receive a response from the user, such as to confirm that the user understands the alert being generated. When the alert dialog is displayed, authors MUST set focus to an active element within the alert dialog, such as a form edit field or an ok pushbutton. The user agent MAY fire an accessibility alert event, when the alert is created, provided one is specified by the intended accessibility API.

A marquee is used to scroll text across the page.

A common usage is a stock ticker. A marquee behaves like a live region, with an assumed default live property value of "off". An example of a marquee is a stock ticker. A major difference between a marquee and a log is how fast it gets updates from timed or real world events.

A region where new information is added and old information may disappear.

Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in this role there is a relationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points.

Container for processing advisory information to give feedback to the user.

A status object must have content within it to provide the actual status information. This object SHOULD NOT receive focus.

Status is a form of live region. Its assumed default value for the live property is "polite".

If another part of the page controls what appears in the status, the relationship should be made explicit with the controls property.

Some cells of a Braille display MAY be reserved to render the status.

Displays the execution status for tasks that take a long time to execute.

This lets the user know that the user's action request has been accepted and that the application continues (or ceases, in the case of a static display) to make progress toward completing the requested action. The author should supply values for valuenow, valuemin, and valuemax, unless the value is indeterminate in which the property should be omitted. These values should be updated when the visual progress indicator is updated. If the progressbar is describing the loading progress of a particular region of a page, the author SHOULD use describedby to point to the status, and set the busy state to "true" on the region until it is finished loading.

A numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.

The text contents of the timer object indicate the current time measurement, and are updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point.

A timer is a form of live region. The default value of live for timer is "off".

Represents a section of a page consisting of a composition forming an independent part of a document, page, or site.

An article could be a forum post, a magazine or newspaper article, a Web log entry, a user-submitted comment, or any other independent item of content. It is "independent" in that its contents could stand alone, for example in syndication. However, the element is still associated with its ancestors; for instance, contact information that applies to a parent body element still covers the article as well. When nesting articles, the inner articles represent articles that are in principle related to the contents of the outer article. For instance, a Web log entry on a site that accepts user-submitted comments could represent the comments as articles nested within the article for the Web log entry. Author, heading, date or other information associated with an article does not apply to nested articles. Assistive technologies must treat and article like a document in that article must must be processed like an application. Unlike a document, the use of articles allows the user to identify them and follow related articles based on the nesting.

When applying the article to a host language element, ensure that the element and the corresponding end tag wrap the entire article.

A region that contains the prime heading or internal title of a page.

Most of the content of a banner is site-oriented, rather than being page-specific. Site-oriented content typically includes things such as the logo of the site sponsor, the main heading for the page, and site-specific search tool. Typically this appears at the top of the page spanning the full width.

Any section of the document that supports but is separable from the main content, but is meaningful on its own even when separated from it.

There are various types of content that would appropriately have this role. For example, in the case of a portal, this may include but not be limited to show times, current weather, related articles, or stocks to watch. The content should be relevant to the main content; if it is completely separable, a more general role should be used instead.

Meta information which applies to the first immediate ancestor whose role is not presentation.

In the context of the page this would apply to a section or the page of which it is the child. For example, footnotes, copyrights, links to privacy statements, etc. would belong here.

Main content in a document.

This marks the content that is directly related to or expands upon the central topic of the page.

A collection of links suitable for use when navigating the document or related documents.

The search tool of a web document.

This is typically a form used to submit search requests about the site or to a more general Internet search service.

A definition of a term or concept.

A role is not provided to specify the term being defined, although host languages may provide such an element; in HTML this is the dfn element. The defined term should be included in such an element even when occurring within an element having the definition role.

The content is parenthetic or ancillary to the main content of the resource.