Copyright © 2019 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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 [HTML] 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 [HTML] specification.
This is a draft document and its contents are subject to change without notice.
This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-html@w3.org (archives).
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 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 2019 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 (UI) information 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
§ 2.
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.
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 1.0 [html-aam-1.0] 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:
DPub Roles:
global |
a element without a href
|
No corresponding role |
global |
abbr
|
No corresponding role |
global |
address
|
No corresponding role |
global |
area with a href
|
role=link
|
No
global |
area without a href |
No corresponding role | No global |
article
|
role=article
|
Roles: |
aside
|
role=complementary
|
Roles:
DPub 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
|
No corresponding role |
Role:
global |
dt
|
role=term
|
Role:
global |
embed
|
No corresponding role |
Role:
global |
figcaption - (new)
|
No corresponding role |
Roles:
global |
fieldset
|
role=group
(changed)
|
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:
DPub Roles:
global |
form
|
role=form if the
form element has an accessible name. Otherwise, no corresponding
role.
|
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:
DPub Role:
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:
DPub Role:
global |
hgroup |
No corresponding role |
global |
hr
|
role=separator
|
Roles:
DPub 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 with alt="some
text"
|
role=img
|
Any
global |
img with no alt=""
|
role=img
|
Any
global |
input type=
|
role=button
|
Role:
global |
input type=checkbox
|
|
Role:
global
Note: the HTML |
input type=color
|
No corresponding role |
No role
|
input type=date
|
No corresponding role |
No |
input type=datetime-local
|
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
global |
input type=radio
|
role=radio
|
global
Note: the HTML |
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=tel , with
no list attribute
|
role=textbox
|
No
global |
input type=text ,
with no list attribute
|
role=textbox
|
Role:
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 |
|
label
|
No corresponding role |
No |
legend
|
No corresponding role |
No |
li element whose parent is an
ol or ul
|
role=listitem
|
Role:
DPub Roles:
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 |
meta
|
No corresponding role |
No role or aria-*
attributes
|
meter
|
No corresponding role |
No |
nav
|
role=navigation
|
DPub Roles:
global |
noscript
|
No corresponding role |
No role or aria-*
attributes
|
object
|
No corresponding role |
Role:
global |
ol
|
role=list
Note that some UAs may suppress a list's semantics if its list
markers have been removed. Authors MAY add |
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 if the
section element has an accessible name. Otherwise, no corresponding
role.
|
Roles:
DPub Roles:
global |
select (with NO
multiple attribute and NO size
attribute having value greater than 1 ) (changed)
|
role=combobox
|
Role:
global |
select (with a
multiple attribute or a size attribute
having value greater than 1 ) (new)
|
role=listbox
|
No
global |
slot |
No corresponding role | No role or aria-*
attributes |
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
|
|
global |
Text level semantic elements not listed elsewhere:
|
No corresponding role |
Any role
global |
th
|
role=columnheader or
rowheader
|
global |
role=row , may be
explicitly declared when child of a table element
with role=grid
|
global |
|
track
|
No corresponding role |
No role or aria-* attributes
|
ul
|
role=list
Note that some UAs may suppress a list's semantics if its list
markers have been removed. Authors MAY add |
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:
Authors MUST use lowercase ASCII
letters for all role
token values and any state or property
attributes (aria-*
) whose values are defined as tokens.
Columns 1 to 4 of the ARIA Roles, States and Properties table provide an informative (non-normative) reference to the ARIA roles, states and properties permitted for use in HTML. All ARIA roles, states and properties are normatively defined in the Accessible Rich Internet Applications (WAI-ARIA) 1.1 specification. Links to ARIA roles, states and properties in the table reference the normative Accessible Rich Internet Applications (WAI-ARIA) 1.1 definitions.
Column 5 of the ARIA Roles, States and
Properties table, defines extensions to the Kinds of content (defined in the
[HTML] specification) categories each role
has when it is used on a
HTML element. Column 6 defines what HTML elements can be descendants of
an element with a particular implicit or
explicit role
value.
For example, an element with role=button
is interactive
content and therefore cannot contain interactive content
descendants. A button
element has an implicit
role=button
, so cannot contain any elements with role
values that are in the interactive content category (identified in
Column 3).
<!-- conformance checkers will report an error -->
<button>
<div role="button">...</div>
</button>
<div role="button">
<button>...</button>
</div>
<div role="link">
<textarea>...</textarea>
</div>
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 - (new) | Descendant restrictions - (new) |
---|---|---|---|---|---|
any | ARIA global states and properties can be used on any HTML element. | none |
|
n/a | n/a |
alert
|
A type of live region with important, and usually
time-sensitive, information. See related alertdialog
and status .
|
none | Flow content | Flow content | |
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 |
|
Flow content | Flow content |
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 | 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 | No main element descendants. | |
banner
|
A region that contains mostly site-oriented content, rather than page-specific content. | none | Document region | no main element descendants, or header, footer elements that are not descendants of sectioning content which is a descendant of the header. | |
button
|
An input that allows for user-triggered actions when clicked or
pressed. See related link .
|
none | Interactive content | Flow content, but there must be no interactive content descendant. | |
checkbox
|
A checkable input that has three possible values: true, false, or mixed. |
|
Interactive content | Flow content, but there must be no interactive content descendant. | |
cell -
(new)
|
A cell in a tabular container. | none |
|
Flow content | Flow content |
columnheader
|
A cell containing header information for a column. | none |
|
Flow content | 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 | Flow 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 | Flow content | Flow content, but with no main element descendants. | |
contentinfo
|
A large perceivable region that contains information about the parent document. | none | Flow content | Flow content, but with no main element descendants, or header, footer elements that are not descendants of sectioning content which is a descendant of the header. | |
definition
|
A definition of a term or concept. | none | Phrasing content | 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 |
|
Flow content | Flow content |
directory
|
A list of references to members of a group, such as a static table of contents. | none | Flow content | Flow content | |
document
|
A region containing related information that is declared as document content, as opposed to a web application. | none | Flow content | 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 | 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 | 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 | Flow content | Flow content | |
grid
|
A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table. | none | Flow content | ||
gridcell
|
A cell in a grid or treegrid. | none |
|
Flow 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 | Flow content | |
heading
|
A heading for a section of the page. | none | Heading content | Flow content, but with no Heading content, Sectioning content, Sectioning roots | |
img
|
A container for a collection of elements that form an image. | none | Flow content | Flow 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 | Flow content, but with no interactive content or a element descendants. | |
list
|
A group of non-interactive list items. See related
listbox .
|
none | Flow content | 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 | ||
listitem
|
A single item in a list or directory .
|
none | Flow content | Flow content | |
log
|
A type of live region where new information is added in
meaningful order and old information may disappear. See related
marquee .
|
none | Flow content | Flow content | |
main
|
The main content of a document. | none | Flow content | Flow content, but with no main element descendants | |
marquee
|
A type of live region where non-essential information changes
frequently. See related log .
|
none | Flow content | Flow content | |
math
|
Content that represents a mathematical expression. | none | Flow content | Flow content | |
menu
|
A type of widget that offers a list of choices to the user. | none | Flow content | ||
menubar
|
A presentation of menu that usually remains visible and is usually presented horizontally. | none | Flow content | ||
menuitem
|
An option in a group of choices contained by a menu
or menubar .
|
none | Interactive content | Flow content, but with no interactive content descendants. | |
menuitemcheckbox
|
A checkable menuitem that has three possible values: true, false, or mixed. | Interactive content | Flow content, but with no interactive content descendants. | ||
menuitemradio
|
A checkable menuitem in a group of menuitemradio
roles, only one of which can be checked at a time.
|
Interactive content | Flow content, but with no interactive content descendants. | ||
navigation
|
A collection of navigational elements (usually links) for navigating the document or related documents. | none | Flow content | Flow content, but with no main element descendants | |
none -
(new)
|
An element whose implicit native role semantics will not be mapped to the accessibility API. See synonym presentation | none | Flow content | Flow content | |
note
|
A section whose content is parenthetic or ancillary to the main content of the resource. | none | Flow content | Flow content | |
option
|
A selectable item in a select list. | none | Interactive content | Flow content, but with no interactive content descendants. | |
presentation
|
An element whose implicit native role semantics will not be mapped to the accessibility API. | none | Flow content | Flow content | |
progressbar
|
An element that displays the progress status for tasks that take a long time. | none | Flow content | Flow content | |
radio
|
A checkable input in a group of radio roles, only one of which can be checked at a time. | Interactive content | Flow content, but with no interactive content descendants. | ||
radiogroup
|
A group of radio buttons. | none | Flow content | Flow content | |
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 | Flow content | Flow content | |
row
|
A row of cells in a tabular container. |
none | none | Flow content | |
rowgroup
|
A group containing one or more row elements in a grid. | none | none | Flow content | |
rowheader
|
A cell containing header information for a row in a grid. | none |
|
none | Flow content |
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. | Flow content | |||
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 | Flow content | ||
searchbox
- (new)
|
A type of textbox intended for specifying search criteria. | none | Interactive content | Flow content, but with no interactive content descendants. | |
separator
|
A divider that separates and distinguishes sections of content or groups of menuitems. |
|
|
Interactive content (if focusable) |
Flow content |
slider
|
A user input where the user selects a value from within a given range. | Interactive content | Flow content | ||
spinbutton
|
A form of range that expects the user to select from among discrete choices. | Flow content | |||
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 | Flow content | ||
switch -
(new)
|
A type of checkbox that represents on/off values, as opposed to checked/unchecked values. |
aria-readonly
|
Flow content, but with no interactive content descendants. | ||
tab
|
A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user. | none | Flow content | ||
table -
(new)
|
A section containing data arranged in rows and columns. The table role is intended for tabular containers which are not interactive. | none |
|
Flow content | Flow content |
tablist
|
A list of tab elements, which are references to tabpanel elements. | none | Flow content | Flow content | |
tabpanel
|
A container for the resources associated with a tab ,
where each tab is contained in a
tablist .
|
none | Flow content | Flow content | |
term -
(new)
|
A word or phrase with a corresponding definition. See related definition. | none |
aria-expanded
(state)
|
Phrasing content | Phrasing content |
textbox
|
Input that allows free-form text as its value. | none | Interactive content | Flow content, but with no interactive content descendants. | |
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 | Flow content | Flow content | |
toolbar
|
A collection of commonly used function buttons represented in compact visual form. | none | Flow content | Flow content | |
tooltip
|
A contextual popup that displays a description for an element. | none | Flow content | Flow content | |
tree
|
A type of list that may contain sub-level nested groups that can be collapsed and expanded. | none | Flow content | Flow content | |
treegrid
|
A grid whose rows can be expanded and collapsed in the same manner as for a tree. | none |
|
Flow content | Flow content |
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 | Interactive content | Flow content |
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, NOT RECOMMENDED, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
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 § 2.
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.