Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This specification defines the web developer rules (author conformance requirements) for the use of [wai-aria-1.1] attributes on [HTML51] elements. It also defines requirements for Conformance Checking tools.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
ARIA in HTML is a [ HTML51] specification module. Any HTML features, conformance requirements, or terms that this specification module makes reference to, but does not explicitly define, are defined in the [HTML51] specification.
Feedback and bug reports are welcome. File a bug.
This is a draft document and its contents are subject to change without notice.
This document was published by the Web Platform Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives). All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2017 W3C Process Document.
Web developers MAY use the ARIA role and aria-* attributes on HTML elements, in accordance with the requirements described in [wai-aria-1.1], except where these conflict with the strong native semantics or are equal to the implicit ARIA semantics of a given HTML element. These constraints, are intended to prevent developers from making assistive technology products report nonsensical user interface information (UI) that does not represent the actual UI of the document.
Web developers MUST NOT use the ARIA role and aria-* attributes in a manner that conflicts with the semantics described in the Document conformance requirements for use of ARIA attributes in HTML table. Web developers SHOULD NOT set the ARIA role and aria-* attributes to values that match the implicit ARIA semantics defined in the table.
role=heading on a button element. This is not allowed, because the button element has default characteristics that conflict with the heading role.
<button role="heading">search</button>
If you check this file using a HTML5 conformance checker an error will be displayed.
The following table provides normative per-element document-conformance requirements for the use of ARIA markup in HTML documents and describes the implicit ARIA semantics that apply to HTML elements as defined in the HTML Accessibility API Mappings specification. Each language feature (element or attribute) in a cell in the first column implies the ARIA semantics (any role, states, and properties) given in the cell in the second column of the same row. The third cell in each row defines which ARIA role values and aria-* attributes which MAY be used. Where a cell in the third column includes the term Any role it indicates that any role value apart from the implicit ARIA semantics role value, MAY be used.
Setting an ARIA role and/or aria-* attribute that matches the implicit ARIA semantics is unnecessary and is NOT RECOMMENDED as these properties are already set by the browser.
The (new) and (changed) markers in the following table indicate new (in ARIA 1.1) or changed (between ARIA 1.0/1.1) ARIA roles, states and properties
| HTML language feature |
Implicit ARIA semantics - SHOULD NOT be used |
ARIA roles, states and properties which MAY be used |
|---|---|---|
a element with a href |
role=link |
Roles: global |
a element without a href |
No corresponding role |
global |
address
|
No corresponding role |
global |
area with a href |
role=link |
No global |
article |
role=article |
Roles: |
aside |
role=complementary |
Roles: global |
audio |
No corresponding role |
Role: |
base
|
No corresponding role | No role or aria-* attributes |
body |
role=document |
No global |
button
|
role=button |
Roles: |
button type="menu"
|
role=button |
Roles: |
canvas
|
No corresponding role |
global |
caption
|
No corresponding role |
No |
| No corresponding role | No role or aria-* attributes |
|
datalist
|
role=listbox |
No global |
dd
|
role=definition |
No global |
details
|
role=group |
No global |
dialog |
role=dialog |
Role: global |
div
|
No corresponding role |
global |
dl
|
role=list |
Role: global |
dt
|
role=listitem |
No global |
embed
|
No corresponding role |
Role: global |
figcaption - (new)
|
No corresponding role |
Roles: global |
fieldset
|
No corresponding role |
Roles: global |
figure
|
role=figure - (new) |
Roles: global |
footer
|
If not a descendant of an article, aside, main, nav - (changed) or section element role=contentinfo, otherwise No corresponding role |
Roles: global |
form |
role=form |
Role: global |
|
grouping content elements not listed elsewhere:
|
No corresponding role |
Any global |
h1 to h6 element |
role=heading, with the aria-level = positive integer |
Role: tab or presentation
global |
head
|
No corresponding role | No role or aria* attributes |
header
|
If not a descendant of an article, aside, main, nav - (changed) or section element role=banner, otherwise No corresponding role |
Roles: global |
hr
|
role=separator |
Role: global |
html
|
No corresponding role | No role or aria* attributes |
iframe
|
No corresponding role |
Role: global |
img with alt="" |
No corresponding role |
Role: No |
img |
role=img |
Any global |
input type= button |
role=button |
Role: global |
input type= checkbox |
|
Role: global |
input type = color |
No corresponding role | No role
|
input type = date |
No corresponding role |
No |
input type = datetime |
No corresponding role |
No |
input type = email with no list attribute |
role=textbox |
No global |
input type = file |
No corresponding role |
No |
input type= image |
role=button |
Role: global |
input type = month |
No corresponding role |
No |
input type = number |
role=spinbutton |
No global |
input type = password |
No corresponding role - (changed) |
No |
input type = radio |
role=radio |
global |
input type = range |
role=slider |
No global |
input type= reset |
role=button |
No global |
input type = search, with no list attribute |
role=searchbox - (new) |
No global |
input type = submit |
role=button |
No global |
input type = telwith no list attribute |
role=textbox |
No global |
input type = textwith no list attribute |
role=textbox |
No global |
input type = text, search, tel, url, or email with a list attribute |
role=combobox |
No global |
input type= time |
No corresponding role |
No |
input type =url with no list attribute |
role=textbox |
No global |
input type = week |
No corresponding role |
No |
| No corresponding role |
Any global |
|
keygen
|
No corresponding role |
No |
label
|
No corresponding role |
No |
legend
|
No corresponding role |
No |
li element whose parent is an ol or ul
|
role=listitem |
Role: global |
link element with a href |
role=link |
No role or aria* attributes |
main |
role=main |
No global |
map |
No corresponding role | No role or aria* attributes |
math |
role=math |
No global |
menu type = context |
role=menu |
No global |
menuitem type = command
|
role=menuitem |
No global |
menuitem type = checkbox
|
role=menuitemcheckbox |
No global |
menuitem type = radio
|
role=menuitemradio |
No global |
meta
|
No corresponding role | No role or aria* attributes |
meter
|
No corresponding role |
No |
nav
|
role=navigation |
No global |
noscript
|
No corresponding role | No role or aria* attributes |
object
|
No corresponding role |
Role: global |
ol
|
role=list |
Role: global |
optgroup
|
role=group |
No global |
option element that is in a list of options or that represents a suggestion in a datalist
|
role=option |
No global |
output
|
role=status |
global |
param
|
No corresponding role | No role or aria* attributes |
picture
|
No corresponding role | No role or aria* attributes |
progress
|
role=progressbar |
No global |
script
|
No corresponding role | No role or aria* attributes |
section
|
role=region |
Role: global |
select |
role=listbox |
Role: global |
source
|
No corresponding role | No role or aria* attributes |
span
|
No corresponding role |
global |
style
|
No corresponding role | No role or aria* attributes |
SVG
|
No corresponding role |
Role: global |
summary
|
role=button |
Role: global |
table
|
role=table - (new) |
global |
template
|
No corresponding role | No role or aria* attributes |
textarea
|
role=textbox |
No global |
role=rowgroup |
global |
|
title
|
No corresponding role | No role or aria* attributes |
td
|
role=cell - (new) |
global |
|
Text level semantic elements not listed elsewhere:
|
No corresponding role | Any role
global |
th
|
role=columnheader or rowheader |
global |
role=row |
global |
|
track
|
No corresponding role | No role or aria* attributes |
ul
|
role=list |
Role: global |
video
|
No corresponding role |
Role: global |
Element with a disabled attribute |
aria-disabled="true" |
Use the Only use the |
Element with a placeholder attribute -(new) |
aria-placeholder="" |
Use the Only use the |
Element with a required attribute |
aria-required="true" |
Use the MAY also be used for elements that have an ARIA role which allows the |
Element with a readonly attribute |
aria-readonly="true" |
Use the Only use the |
| Element that is a candidate for constraint validation but that does not satisfy its constraints | aria-invalid="true" |
The |
Element with contenteditable attribute |
aria-readonly="false" |
Do not set aria-readonly="true" on an element that has a contenteditable attribute set. - (new) |
The elements marked with No corresponding role, in the second column of the table do not have any implicit ARIA semantics, but they do have meaning and this meaning may be represented in roles, states and properties not provided by ARIA, and exposed to users of assistive technology via accessibility APIs. It is therefore recommended that web developers add a role attribute to a semantically neutral element such as a div or span, rather than overriding the semantics of the listed elements.
Authors are encouraged to make use of the following documents for guidance on using ARIA in HTML beyond that which is provided here:
These features can be used to make accessibility tools render content to their users in more useful ways. For example, ASCII art, which is really an image, appears to be text, and in the absence of appropriate roles and properties would end up being rendered by screen readers as a nonsensical string of punctuation characters. Using the features described in this section, one can instead make the ATs skip the ASCII art and just read the caption:
<figure role="img" aria-labelledby="fish-caption">
<pre>
o .'`/
' / (
O .-'` ` `'-._ .')
_/ (o) '. .' /
) ))) >< <
`\ |_\ _.' '. \
'-._ _ .-' '.)
jgs `\__\
</pre>
<figcaption id="fish-caption">
Joan G. Stark, "<cite>fish</cite>".
October 1997. ASCII on electrons. 28×8.
</figcaption>
</figure>
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 1.1 specification. Links to ARIA roles, states and properties in the table reference the normative ARIA 1.1 definitions.
The (new) and (changed) markers in the following table indicate new (in ARIA 1.1) or changed (between ARIA 1.0/1.1) ARIA roles, states and properties
| Role | Description | Required Properties | Supported Properties | Kind of content (work in progress) |
|---|---|---|---|---|
| any | ARIA global states and properties can be used on any HTML element. | none |
|
n/a |
alert |
A type of live region 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 structure containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by a widget role. - changed) | none | Flow content | |
article |
A section of a page that consists of a composition that forms an independent part of a document, page, or site. | none | Flow content | |
banner |
A region that contains mostly site-oriented content, rather than page-specific content. | none | Document region | |
button |
An input that allows for user-triggered actions when clicked or pressed. See related link. |
none | Interactive content | |
checkbox |
A checkable input that has three possible values: true, false, or mixed. | |
Interactive content | |
cell - (new) |
A cell in a tabular container. | none |
|
Flow content |
columnheader |
A cell containing header information for a column. | none | Flow content | |
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. |
|
Interactive content | |
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 | Document region | |
contentinfo |
A large perceivable region that contains information about the parent document. | none | Document region | |
definition |
A definition of a term or concept. | none | Phrasing content | |
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 |
|
Interactive content |
directory |
A list of references to members of a group, such as a static table of contents. | none | Flow content | |
document |
A region containing related information that is declared as document content, as opposed to a web application. | none | Flow content | |
feed - (new) |
A scrollable list of articles where scrolling may cause articles to be added to or removed from either end of the list. | none | aria-expanded (state) |
Flow content |
figure - (new) |
A perceivable section of content that typically contains a graphical document, images, code snippets, or example text. | none | aria-expanded (state) |
Flow content |
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 | Document region | |
grid |
A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table. | none |
Flow content Interactive content |
|
gridcell |
A cell in a grid or treegrid. | none |
|
Flow content Interactive content |
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 | Flow content | |
heading |
A heading for a section of the page. | none | Heading content | |
img |
A container for a collection of elements that form an image. | none | Embedded content | |
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 | Flow content | |
list |
A group of non-interactive list items. See related listbox. |
none | Flow content | |
listbox |
A widget that allows the user to select one or more items from a list of choices. See related combobox and list. |
none |
Flow content Interactive content |
|
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 | ||
none - (new) |
An element whose implicit native role semantics will not be mapped to the accessibility API. See synonym presentation | 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 tabular container. |
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 |
|
|
searchbox - (new) |
A type of textbox intended for specifying search criteria. | 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 | ||
switch - (new) |
A type of checkbox that represents on/off values, as opposed to checked/unchecked values. | |||
tab |
A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user. | none | ||
table - (new) |
A section containing data arranged in rows and columns. The table role is intended for tabular containers which are not interactive. | 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 | ||
term - (new) |
A word or phrase with a corresponding definition. See related definition. | 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 |
Conformance checkers that claim support for checking of ARIA in HTML, MUST implement checks for the document conformance requirements for use of the ARIA role and aria-* attributes on HTML elements as defined in this specification.
Documents MUST NOT use any role values with elements in the Document conformance requirements for use of ARIA attributes in HTML table, other than the corresponding role value (if any) as listed for that element in the third column, other than those indicated in the second column, which SHOULD NOT be used.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. The key word "OPTIONALLY" in the normative parts of this document is to be interpreted with the same normative meaning as "MAY" and " OPTIONAL". For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]]