This should most likely be placed in one of the existing HTML/ARIA documents.
This specification is an experimental breakup of the HTML specification. You can see the full list on the index page and take part in the discussion in the repository.
Authors may use the ARIA role and aria-* attributes on HTML elements, in accordance with the requirements described in the ARIA specifications, except where these conflict with the requirements specified in ARIA in HTML. These exceptions are intended to prevent authors from making assistive technology products report nonsensical states that do not represent the actual state of the document. [[!ARIA]]
In the majority of cases setting an ARIA role and/or aria-* attribute that matches the default implicit ARIA semantics is unnecessary and not recommended as these properties are already set by the browser.
Authors are encouraged to make use of the following documents for guidance on using ARIA in HTML beyond that which is provided in this section:
Conformance checkers are required to implement document conformance requirements for use of the ARIA role and aria-* attributes on HTML elements, as defined in ARIA in HTML.
User agents are required to implement ARIA semantics on all HTML elements, as defined in the ARIA specifications [[!ARIA]] and [[!ARIAIMPL]].
User agents are required to implement Accessibility API semantics on all HTML elements, as defined in the HTML Accessibility API Mappings specification.
The ARIA attributes defined in the ARIA specifications, and the HTML Accessibility API Mappings specification, do not have any effect on CSS pseudo-class matching, user interface modalities that don't use assistive technologies, or the default actions of user interaction events as described in this specification.
Every HTML element may have an ARIA role attribute specified. This is an ARIA Role attribute as defined by [[!ARIA]] Section 5.4 Definition of Roles.
The attribute, if specified, must have a value that is a set of space-separated tokens representing the various WAI-ARIA roles that the element belongs to.
The WAI-ARIA role that an HTML element has assigned to it is the first non-abstract role found in the list of values generated when the role attribute is split on spaces.
Every HTML element may have ARIA state and property attributes specified. These attributes are defined by [[!ARIA]] in Section 6.6, Definitions of States and Properties (all aria-* attributes).
A subset of the ARIA State and Property attributes are defined as "Global States and Properties" in Section 6.4. Global States and Properties of the [[!ARIA]] Specification.
These attributes, if specified, must have a value that is the ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate HTML value type according to [[!ARIA]] Section 10.2 Mapping WAI-ARIA Value types to languages using the HTML 5 mapping.
ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM. State and property attributes are processed according to the requirements of the HTML Accessibility API Mappings specification, as well as [[!ARIA]] and [[!ARIAIMPL]].
This section is non-normative.
The following table provides an informative reference to the ARIA roles, states and properties permitted for use in HTML. All ARIA roles, states and properties are normatively defined in the [[!ARIA]] specification. Links to ARIA roles, states and properties in the table reference the normative [[!ARIA]] definitions.
| Role | Description | Required Properties | Supported Properties |
|---|---|---|---|
| any | ARIA global states and properties can be used on any HTML element. | none | |
| alert | A message with important, and usually time-sensitive, information. See related alertdialog and status. | none | |
| alertdialog | A type of dialog that contains an alert message, where initial focus goes to an element within the dialog. See related alert and dialog. | none | |
| application | A region declared as a web application, as opposed to a web document. | none | |
| article | A section of a page that consists of a composition that forms an independent part of a document, page, or site. | none | |
| banner | A region that contains mostly site-oriented content, rather than page-specific content. | none | |
| button | An input that allows for user-triggered actions when clicked or pressed. See related link. | none | |
| checkbox | A checkable input that has three possible values: true, false, or mixed. | ||
| columnheader | A cell containing header information for a column. | none | |
| combobox | A presentation of a select; usually similar to a textbox where users can type ahead to select an option, or type to enter arbitrary text as a new item in the list. See related listbox. | ||
| complementary | A supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content. | none | |
| contentinfo | A large perceivable region that contains information about the parent document. | none | |
| definition | A definition of a term or concept. | none | |
| dialog | A dialog is an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. See related alertdialog. | none | |
| directory | A list of references to members of a group, such as a static table of contents. | none | |
| document | A region containing related information that is declared as document content, as opposed to a web application. | none | |
| form | A landmark region that contains a collection of items and objects that, as a whole, combine to create a form. See related search. | none | |
| grid | A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table. | none | |
| gridcell | A cell in a grid or treegrid. | none | |
| group | A set of user interface objects which are not intended to be included in a page summary or table of contents by assistive technologies. | none | |
| heading | A heading for a section of the page. | none | |
| img | A container for a collection of elements that form an image. | none | |
| link | An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See related button. | none | |
| list | A group of non-interactive list items. See related listbox. | none | |
| listbox | A widget that allows the user to select one or more items from a list of choices. See related combobox and list. | none | |
| listitem | A single item in a list or directory. | none | |
| log | A type of live region where new information is added in meaningful order and old information may disappear. See related marquee. | none | |
| main | The main content of a document. | none | |
| marquee | A type of live region where non-essential information changes frequently. See related log. | none | |
| math | Content that represents a mathematical expression. | none | |
| menu | A type of widget that offers a list of choices to the user. | none | |
| menubar | A presentation of menu that usually remains visible and is usually presented horizontally. | none | |
| menuitem | An option in a group of choices contained by a menu or menubar. | none | |
| menuitemcheckbox | A checkable menuitem that has three possible values: true, false, or mixed. | ||
| menuitemradio | A checkable menuitem in a group of menuitemradio roles, only one of which can be checked at a time. | ||
| navigation | A collection of navigational elements (usually links) for navigating the document or related documents. | none | |
| note | A section whose content is parenthetic or ancillary to the main content of the resource. | none | |
| option | A selectable item in a select list. | none | |
| presentation | An element whose implicit native role semantics will not be mapped to the accessibility API. | none | |
| progressbar | An element that displays the progress status for tasks that take a long time. | none | |
| radio | A checkable input in a group of radio roles, only one of which can be checked at a time. | ||
| radiogroup | A group of radio buttons. | none | |
| region | A large perceivable section of a web page or document, that the author feels is important enough to be included in a page summary or table of contents, for example, an area of the page containing live sporting event statistics. | none | |
| row | A row of cells in a grid. | none | |
| rowgroup | A group containing one or more row elements in a grid. | none | |
| rowheader | A cell containing header information for a row in a grid. | none | |
| scrollbar | A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area. | ||
| search | A landmark region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related form. | none | |
| separator | A divider that separates and distinguishes sections of content or groups of menuitems. |
|
|
| slider | A user input where the user selects a value from within a given range. | ||
| spinbutton | A form of range that expects the user to select from among discrete choices. | ||
| status | A container whose content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar. See related alert. | none | |
| tab | A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user. | none | |
| tablist | A list of tab elements, which are references to tabpanel elements. | none | |
| tabpanel | A container for the resources associated with a tab, where each tab is contained in a tablist. | none | |
| textbox | Input that allows free-form text as its value. | none | |
| timer | A type of live region containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point. | none | |
| toolbar | A collection of commonly used function buttons represented in compact visual form. | none | |
| tooltip | A contextual popup that displays a description for an element. | none | |
| tree | A type of list that may contain sub-level nested groups that can be collapsed and expanded. | none | |
| treegrid | A grid whose rows can be expanded and collapsed in the same manner as for a tree. | none | |
| treeitem | An option item of a tree. This is an element within a tree that may be expanded or collapsed if it contains a sub-level group of treeitems. | none |