See also translations.
Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This specification defines the authoring rules (author conformance requirements) for the use of Accessible Rich Internet Applications (WAI-ARIA) 1.2 and Digital Publishing WAI-ARIA Module 1.0 attributes on [HTML] elements. This specification's primary objective is to define requirements for use with conformance checking tools used by authors (i.e., web developers). These requirements will aid authors in their development of web content, including custom interfaces and widgets, which make use of ARIA to complement or extend the features of the host language [HTML].
This section describes the status of this document at the time of its publication. 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 an [HTML] specification module. Any HTML features, conformance requirements, or terms that this specification module makes reference to, but does not explicitly define, are defined by the HTML Standard.
Since this specification become a W3C Recommendation on 09 December 2021, the following substantive additions and/or corrections have been proposed:
separator
role.
img
element allowances to be based on if the element has an accessible name or not.
address
and hgroup
element allowances per their updated mapping to the group
role.
aside
element to allow the dpub doc-glossary
role.
button
, input type=button
, input type=image
input type=reset
, and input type=submit
elements to align their allowed roles.
s
element allowed roles to indicate use of role=deletion
on the element would be considered redundnat.
aria-*
attributes and roles on summary
element.
li
element role allowances in context to the element's ancestral relationship, or lack of,
to a list element parent.
search
element has been added.
aria-hidden=true
on the body
element.
figure
element role allowances to include doc-example
.
aria-*
attributes on the datalist
element.
aria-checked
is not to be used on elements that support the checked
attribute.
none
and presentation
roles on nav
element.
div
element when it is a child of a dl
element.
combobox
role on button
element.
Allow combobox
and checkbox
roles on input type=button
element.
doc-biblioentry
and doc-endnote
roles on the li
element.
These roles are deprecated in Digital Publishing WAI-ARIA Module 1.1.
radio
role on img alt="some text"
element.
none
and presentation
roles for wbr
element.
Allow only aria-hidden
global attribute for br
and wbr
elements.
group
role on section
element.
link
and button
roles on area
without href
element.
aria-hidden
attribute on the picture
element.
Reviewers of the document can identify candidate additions and/or corrections by their distinctive styling in the document:
Candidate corrections are marked in the document.
Candidate additions are marked in the document.
This document was published by the Web Applications Working Group as a Recommendation using the Recommendation track. It includes candidate amendments, introducing substantive changes and new features since the previous Recommendation.
W3C recommends the wide deployment of this specification as a standard for the Web.
A W3C Recommendation is a specification that, after extensive consensus-building, is endorsed by W3C and its Members, and has commitments from Working Group members to royalty-free licensing for implementations. Future updates to this Recommendation may incorporate new features.
Candidate additions are marked in the document.
Candidate corrections are marked in the document.
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 03 November 2023 W3C Process Document.
This section is non-normative.
Through the use of ARIA, authors can specify semantics that go beyond the current capabilities of native HTML. This can be very useful, as it provides authors the opportunity to create widgets, or expose specific accessible states and properties to native HTML features which would not be possible by the use of HTML alone.
For instance, a button
element has no native HTML feature to expose a "pressed" state.
ARIA allows authors to extend the semantics of the element by specifying the aria-pressed
attribute, allowing for an aural UI that will match the visual presentation of the control.
In the following example, a button
element allows for a user to toggle the state of a
setting within a web application. The aria-pressed
attribute is used to
augment the button
element. When in the "pressed" state that information can be
exposed to users of assistive technologies.
<button aria-pressed=true>...</button>
There are also situations where certain aria-*
attributes are allowed for use on elements
with specific role
s, while the equivalent native attribute is currently not valid in HTML itself.
For instance, HTML has no direct concept of a disabled hyperlink (a href
element).
Constructs such as <a href="..." disabled> ... </a>
are not valid,
and will not be conveyed to assistive technologies.
ARIA diverges from HTML in this regard and does allow for an aria-disabled
attribute to be specified on an element with an explicit role=link
. If an author were
to specify an aria-disabled=true
on an HTML hyperlink, user agents would not functionally
treat the hyperlink any differently (it would still be clickable/operable), however it
would be exposed to assistive technologies as being in the disabled state.
Similarly, while native HTML option
elements that are descendants of a select
can
only be set as being selected
, elements with an explicit option
role can not only
allow the equivalent aria-selected
, but also the aria-checked
attribute, supporting
widgets/constructs that go beyond the capabilities of a native select
element.
Unfortunately, in these situations where ARIA and HTML have feature parity, but diverge in allowances, it can create for a misalignment in support, if not also user experiences. In situations where ARIA allows a feature not supported by HTML, it will often be in the author's and ultimately the user's best interest to instead implement as a fully custom ARIA widget.
In the following example, a hyperlink needs to be communicated as being in the disabled
state. HTML does not allow for the use of the disabled
attribute on a hyperlink,
and using aria-disabled=true
would communicate the hyperlink as being disabled to
assistive technologies, but would not actually disable the element. The most effective way
to both communicate and actually disable a hyperlink would be to remove the href
from
the a
element, creating a placeholder. Then, ARIA can be applied to this
placeholder link to communicate the element's intended role and state.
<a role=link aria-disabled=true>...</a>
This section is non-normative.
ARIA is useful for revising or correcting the role of an element when a different role
is necessary to expose to users. However, it is rarely in the user or author's best interest
to try and use ARIA to override an interactive element, for instance a button
, with a role
generally exposed by a non-interactive element. For instance, a heading.
As an example, the following uses a role=heading
on a button
element. This is
not allowed, because the button
element has default functionality that conflicts with user
expectations for the heading role.
<button role="heading">search</button>
An author would need to take additional steps to ensure the default functionality and presentation of
the button
was removed, and even doing so may still not be enough to fully supress the element's
implicit features depending on how the user chooses to engage with the web page. E.g., by turning on
Windows high contrast themes, or viewing the web page in a browser's reader mode.
The following example illustrates a button
element which has also been
provided an explicit role=button
. Specifying this role is unnecessary, as a "button"
element is already exposed with an implicit button
role. In practice this particular
instance of redundancy will likely not have unforeseen side effects, other than
unnecessarily making the markup more verbose, and incorrectly signaling to other authors
that this practice is useful. Please review the section 3.3
Be cautious of side effects
for an example of where specifying unnecessary roles can be problematic.
<!-- Avoid doing this! -->
<button role="button">...</button>
Similarly, the following uses a role=group
on a fieldset
element, and a role=Main
on a main
element.
This is unnecessary, because the fieldset
element is implicitly exposed as a role=group
, as is the main
element
implicitly exposed as a role=main
. Again, in practice this will likely not have any unforeseen side effects to users
of assistive technology, as long as the declaration of the role
value uses ASCII lowercase.
Please see 4.4
Case requirements for ARIA role, state and property attributes for more information.
<!-- Avoid doing this! -->
<fieldset role="group">...</fieldset>
<!-- or this! -->
<main role="Main">...</main>
The following uses a role=list
on an ul
element. As the ul
element has an implicit role of list
,
explicitly adding the role would generally be considered redundant. However, some user agents suppress a list's
implicit ARIA semantics if the list markers are removed from the visual presentation of the list items.
Generally the redundant declaration of an element's implicit role would not be recommended, but in specific situations
such as this, and where the role is necessary to expose, authors can explicitly add the role.
<!-- Generally avoid doing this! -->
<ul role="list">...</ul>
The following uses a role=button
on a summary
element. This is
unnecessary and can result in cross-platform issues. For instance,
preventing the element from correctly exposing its state, and forcing
the role of button
, when it might otherwise be exposed with a
platform or browser specific role.
<details>
<!-- Avoid doing this! -->
<summary role="button">more information</summary>
...
</details>
Accessible Rich Internet Applications (WAI-ARIA) 1.2 defines a number of roles which are not meant to be used
by authors. Many of these roles are categorized as Abstract Roles
which are explicitly stated as not to be used by authors. The following example illustrates the invalid use of an
abstract select
role, where an author likely meant to use the combobox
role instead.
<!-- Do not do this! -->
<div role="select" ...>...</div>
ARIA also defines a generic
role which is meant to provide
feature parity with a number of HTML elements that do not have more specific ARIA semantics of their
own. For instance, HTML's div
and span
elements, among others. ARIA discourages authors from
using the generic
role as its intended purpose is for use by implementors of user agents.
In the following example, rather than using a generic
role, authors are advised to use a div
in
place of the article
element. If changing the HTML element is not possible, specifying a role of
presentation
or none
would be acceptable alternaties to remove the implicit role of the article
.
<!-- Avoid doing this! -->
<article role="generic" ...>...</article>
Additionally, ARIA specifically mentions in Conflicts with Host Language Semantics that if authors use both native HTML features for exposing states and properties as well as their ARIA counterparts, then the host language features take priority over the explicit ARIA attributes that are also used.
For instance, in the following example an author is using HTML's input type=checkbox
and has specified an aria-checked=true
. However,
user agents are meant to ignore the aria-checked
attribute. Instead user agents would expose the state based on the native features
of the form control.
<!-- Do not do this! -->
<input type="checkbox" checked aria-checked="false">
While ARIA can be used to alter the way HTML features are exposed to users of assistive technologies,
these modifications do not change the underlying parsing and allowed content models of HTML. For instance,
a div
allows an author to specify any role on it. However, this does not mean that the element can then be
used in a way that deviates from the rules HTML has defined for the element.
For instance, in the following example an author has specified a role of link
on a div
element. While
HTML allows for a hyperlink (exposed as a role=link
) to be a descendant of a p
element, the HTML parser does not
allow a div
to be a descendant of a p
element.
<!-- Do not do this! -->
<p>
... <div role=link tabindex=0>...</div> ...
</p>
The HTML parser will modify the above markup to be output as the following:
<!-- The previous example's markup will render as follows -->
<p>...</p>
<div role=link tabindex=0>...</div>
...
<p></p>
<!-- Use a span are allowed in p elements! -->
<p>
... <span role=link tabindex=0>...</span> ...
</p>
While this specification indicates the allowed ARIA attributes that can be specified on each HTML element, this example illustrates that even if a role is allowed, the context in which it is used can still result in potential rendering and accessibility issues.
The following table provides normative per-element document conformance requirements for the use of ARIA markup in HTML documents. Additionally, it identifies the implicit ARIA semantics that apply to HTML elements. The implicit ARIA semantics of these elements are defined in HTML AAM.
Each language feature (element) in a cell in the first column implies the ARIA semantics
(role, states, and properties) given in the cell in the second column of the same row.
The third cell in each row defines the ARIA role
values and aria-*
attributes which authors MAY specify
on the element. Where a cell in the third column includes the term Any role
it indicates that any role
value MAY be used on the element. However,
it is NOT RECOMMENDED for authors to specify the implicit role of the element, the generic
role, or a role
deprecated by ARIA on these elements.
If a cell in the third column includes the term No role
it indicates
that authors MUST NOT overwrite the implicit ARIA semantics, or native semantics of the HTML element.
WAI-ARIA identifies roles which have prohibited states and properties. These roles do not allow certain WAI-ARIA attributes to be specified by authors. HTML elements which expose these implicit WAI-ARIA roles also prohibit authors from specifying these WAI-ARIA attributes.
Elements which are identified as Naming prohibited are those which authors MUST NOT specify an
aria-label
or aria-labelledby
attribute, unless the element allows for its implicit role to be overwritten
by an explicit WAI-ARIA role which allows naming from authors. For more information see 4.1
Requirements for use of ARIA attributes to name elements.
While setting an ARIA role
and/or aria-*
attribute that matches the implicit ARIA semantics
is NOT RECOMMENDED, in some situations explicitly setting these attributes can be helpful – for instance,
for user agents that do not expose implicit ARIA semantics for certain elements.
While it is conforming to use Digital Publishing WAI-ARIA Module 1.0 role
values as outlined in the following table, the current support for
exposing the semantics of these values to users of assistive technology is close to non-existent.
HTML element |
Implicit ARIA semantics (explicitly assigning these in markup is NOT RECOMMENDED) |
ARIA role, state and property allowances |
---|---|---|
a with href
|
role=link
|
Roles:
DPub Roles:
Global
It is NOT RECOMMENDED to use Note
If a link needs to be programmatically communicated as "disabled",
remove the href attribute.
|
a without href
|
role=generic
|
Any
Otherwise, global |
abbr
|
No corresponding role |
Otherwise, global |
address
|
role=group
|
Any
Otherwise, global |
area with href
|
role=link
|
No
Global |
area without href
|
role=generic
|
Roles:
Otherwise, global |
article
|
role=article
|
Roles:
Global |
aside
|
role=complementary
|
Roles:
DPub Roles:
Global |
audio
|
No corresponding role |
Role:
Global |
autonomous custom element |
Role exposed from author defined
Otherwise |
If role defined by
Otherwise, any
Naming Prohibited if exposed as the
Otherwise, global |
b
|
role=generic
|
Any
Otherwise, global |
base
|
No corresponding role |
No |
bdi
|
role=generic
|
Any
Otherwise, global |
bdo
|
role=generic
|
Any
Otherwise, global |
blockquote
|
role=
|
Any
Global |
body
|
role=generic
|
No
Otherwise, global |
br
|
No corresponding role |
Roles:
Authors MAY specify the |
button
|
role=button
|
Roles:
Global |
canvas
|
No corresponding role |
Global |
caption
|
role=
|
No
Otherwise, global |
cite
|
No corresponding role |
Otherwise, global |
code
|
role=
|
Any
Otherwise, global |
col
|
No corresponding role |
No |
colgroup
|
No corresponding role |
No |
data
|
role=generic
|
Any
Otherwise, global |
datalist
|
role=listbox
|
|
dd
|
No corresponding role |
Global |
del
|
role=
|
Any
Otherwise, global |
details
|
role=group
|
No
Global |
dfn
|
role=term
|
Any
Global |
dialog
|
role=dialog
|
Role:
Global |
div
|
role=generic
|
If a direct child of a
Otherwise, global |
dl
|
No corresponding role |
Roles:
Global |
dt
|
No corresponding role |
Role:
Global |
em
|
role=
|
Any
Otherwise, global |
embed
|
No corresponding role |
Roles:
Global |
fieldset
|
role=group
|
Roles:
Global |
figcaption
|
No corresponding role |
Roles:
Otherwise, global |
figure
|
role=figure
|
If the
If the Otherwise,
Global |
footer
|
If not a descendant of an
Otherwise, |
Roles:
DPub Role:
Naming Prohibited if exposed as
Otherwise, global |
form
|
|
Roles:
Global Note
A |
form-associated custom element |
Role exposed from author defined
Otherwise |
If role defined by
Otherwise, form-related roles:
Naming Prohibited if exposed as the
Otherwise, global |
h1 to h6
|
role=heading ,
aria-level = the number in the element's tag name
|
Roles:
DPub Role:
Global |
head
|
No corresponding role |
No |
header
|
If not a descendant of an
Otherwise, |
Roles:
Naming Prohibited if exposed as
Otherwise, global |
hgroup
|
role=group
|
Any
Otherwise, global |
hr
|
role=separator
|
Roles:
DPub Role:
Global |
html
|
role=document
|
No
No |
i
|
role=generic
|
Any
Otherwise, global |
iframe
|
No corresponding role |
Roles:
Global |
img with an accessible name.
|
If the img has non-empty alt (alt="some text" ) or an accessible name is provided another
img naming method:role=img
|
Roles:
DPub Role:
Global |
img with no accessible name.
|
If the
If the |
If the
If the
No
Otherwise, if the |
input type=button
|
role=button
|
Roles:
Global |
input type=checkbox
|
role=checkbox
|
Roles:
Authors MUST NOT use the
Otherwise, any global Note
The HTML |
input type=color
|
No corresponding role |
Global |
input type=date
|
No corresponding role |
Global |
input type=datetime-local
|
No corresponding role |
Global |
input type=email
with no list attribute
|
role=textbox
|
No
Global |
input type=file
|
No corresponding role |
Global |
No corresponding role |
No |
|
input type=image
|
role=button
|
The following roles are allowed, but are NOT RECOMMENDED:
Global
If possible, authors SHOULD consider using a different HTML element which allows the specified role,
such as the |
input type=month
|
No corresponding role |
Global |
input type=number
|
role=spinbutton
|
No
Global |
input type=password
|
No corresponding role |
Global |
input type=radio
|
role=radio
|
Role:
Authors MUST NOT use the
Otherwise, any global Note
The HTML |
input type=range
|
role=slider
|
No
Authors SHOULD NOT use the
Otherwise, any
global |
input type=reset
|
role=button
|
The following roles are allowed, but are NOT RECOMMENDED:
Global
If possible, authors SHOULD consider using a different HTML element which allows the specified role,
such as the |
input type=search ,
with no list attribute
|
role=searchbox
|
No
Global |
input type=submit
|
role=button
|
The following roles are allowed, but are NOT RECOMMENDED:
Global
If possible, authors SHOULD consider using a different HTML element which allows the specified role,
such as the |
input type=tel ,
with no list attribute
|
role=textbox
|
No
Global |
input type=text
or with a missing or invalid type , with no list attribute
|
role=textbox
|
Roles:
Global |
input type=text ,
search ,
tel ,
url ,
email ,
or with a missing or invalid type , with a list attribute
|
role=combobox
|
No
Authors SHOULD NOT use the
Otherwise, any
global |
input type=time
|
No corresponding role |
Global |
input type=url
with no list attribute
|
role=textbox
|
No
Global |
input type=week
|
No corresponding role |
Global |
ins
|
role=
|
Any
Otherwise, global |
kbd
|
No corresponding role |
Otherwise, global |
label
|
No corresponding role |
Otherwise, global |
legend
|
No corresponding role |
Otherwise, global |
li
|
If the
Otherwise, if the |
No
Otherwise, any
Global Authors SHOULD NOT use the following deprecated DPub Roles:
|
link
|
No corresponding role |
No |
main
|
role=main
|
No
Global |
map
|
No corresponding role |
No |
mark
|
No corresponding role |
Otherwise, global |
math
|
role=math
|
No
Global |
menu
|
role=list
|
Roles:
Global Authors SHOULD NOT use deprecated |
meta
|
No corresponding role |
No |
meter
|
role=
|
No
Authors SHOULD NOT use the
Otherwise, any
global |
nav
|
role=navigation
|
Roles:
DPub Roles:
Global |
noscript
|
No corresponding role |
No |
object
|
No corresponding role |
Roles:
Global |
ol
|
role=list
|
Roles:
Global Authors SHOULD NOT use deprecated |
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
Authors SHOULD NOT use the
Global |
output
|
role=status
|
Any
Global |
p
|
role=
|
Any
Otherwise, global |
param
|
No corresponding role |
No |
picture
|
No corresponding role |
Authors MAY specify the |
pre
|
role=generic
|
Any
Otherwise, global |
progress
|
role=progressbar
|
No
Authors SHOULD NOT use the
Otherwise,
any global |
q
|
role=generic
|
Any
Otherwise, global |
rp
|
No corresponding role |
Global |
rt
|
No corresponding role |
Otherwise, global |
ruby
|
No corresponding role |
Global |
s
|
role=
|
Any
Otherwise, global |
samp
|
role=generic
|
Any
Otherwise, global |
script
|
No corresponding role |
No |
search
|
|
Roles:
Global |
section
|
Otherwise, |
Roles:
DPub Roles:
Global |
select (with NO multiple attribute and NO size
attribute having value greater than 1 )
|
role=combobox
|
Role:
Authors SHOULD NOT use the
Otherwise,
any global |
select (with a multiple attribute or a size attribute
having value greater than 1 )
|
role=listbox
|
No
Authors SHOULD NOT use the
Otherwise,
any global |
slot
|
No corresponding role |
No |
small
|
role=generic
|
Any
Otherwise, global |
source
|
No corresponding role |
No |
span
|
role=generic
|
Any
Otherwise, global |
strong
|
role=
|
Any
Otherwise, global |
style
|
No corresponding role |
No |
sub
|
role=
|
Any
Otherwise, global |
summary
|
Note
Many, but not all, user agents expose the summary element with an implicit ARIA
role=button .
|
No
Global
Otherwise, authors MAY specifiy Any |
sup
|
role=superscript
|
Any
Otherwise, global |
SVG
|
role=graphics-document as defined by
SVG AAM
|
Any
Global |
table
|
role=table
|
Any
Global |
tbody
|
role=rowgroup
|
Any
Global |
td
|
No corresponding role if the ancestor |
If the ancestor
Otherwise, if the ancestor
Global |
template
|
No corresponding role |
No |
textarea
|
role=textbox
|
No
Global |
tfoot
|
role=rowgroup
|
Any
Global |
th
|
No corresponding role if the ancestor |
If the ancestor
Otherwise, if the ancestor
Global |
thead
|
role=rowgroup
|
Any
Global |
time
|
role=time
|
Any
Otherwise, global |
title
|
No corresponding role |
No |
tr
|
role=row
|
If the ancestor
Global |
track
|
No corresponding role |
No |
u
|
role=generic
|
Any
Otherwise, global |
ul
|
role=list
|
Roles:
Global
Authors SHOULD NOT use the deprecated
|
var
|
No corresponding role |
Otherwise, global |
video
|
No corresponding role |
Role:
Global |
wbr
|
No corresponding role |
Roles:
Authors MAY specify the |
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 authors 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 MAY use aria-label
and aria-labelledby
attributes to specify accessible names for elements which have an implicit or explicit ARIA role which allows naming from authors. Accessible Rich Internet Applications (WAI-ARIA) 1.2 defines roles which allow naming from authors as well as roles where author naming is prohibited.
Authors MUST NOT specify aria-label
or aria-labelledby
on elements with implicit WAI-ARIA roles which cannot be named. HTML elements whose implicit WAI-ARIA roles prohibit naming from authors are identified in 4.
Document conformance requirements for use of ARIA attributes in HTML.
The following markup example demonstrates a selection of HTML elements with implicit ARIA roles that prohibit naming from authors.
<!-- DO NOT do the following! -->
<p aria-label="...">...</p>
<span aria-label="...">...<span>
<code aria-label="...">...<code>
<div aria-labelledby="...">...</div>
The following markup example demonstrates elements which have explicit WAI-ARIA roles which allow naming from authors. Due to the explicit roles specified on these elements, aria-label
and aria-labelledby
attributes are allowed.
<p role="link" tabindex="0" aria-label="...">...</p>
<span role="button" tabindex="0" aria-label="...">...<span>
<div role="article" aria-labelledby="...">...</div>
Unless otherwise stated, authors MAY use aria-*
attributes in place of their HTML equivalents on HTML elements where the aria-*
semantics would
be expected. For example, authors MAY specify aria-disabled=true
on a button
element, while also implementing the necessary scripting to functionally
disable the button
, rather than the use disabled
attribute.
As stated in WAI-ARIA's Conflicts with Host Language Semantics,
when HTML elements use both aria-*
attributes and their host language (HTML) equivalents, user agents MUST ignore the WAI-ARIA attributes – the
native HTML attributes with the same implicit ARIA semantics take precedence. For this reason, authors SHOULD NOT specify both the native HTML attribute
and the equivalent aria-*
attribute on an element. Please review each attribute for any further author specific requirements.
The following table represents HTML elements and their attributes which have aria-*
attribute parity.
Each language feature (element and attribute) in a cell in the first
column implies the ARIA semantics (states, and properties) given in
the cell in the second column of the same row. The third cell in each
row defines how authors can use the native HTML feature, along with
requirements for using the aria-*
attributes that supply the same
implicit ARIA semantics.
HTML feature |
Implicit ARIA semantics |
HTML feature and aria-* attribute author guidance
|
---|---|---|
Any element where the checked attribute is allowed
|
aria-checked="true"
|
Use the
Authors MUST NOT use the
Authors MAY use the |
Any element where the disabled
attribute is allowed, including
option disabled and
optgroup disabled
|
aria-disabled="true"
|
Use the
Authors MAY use the
Authors SHOULD NOT use
Authors MUST NOT use |
Any element where the placeholder attribute is allowed
|
aria-placeholder="..."
|
Use the
Authors MAY use the
Authors MUST NOT use the |
Any element where the max attribute is allowed: meter max , progress max , and input max
|
aria-valuemax="..."
|
Use the
Authors MAY use the
Authors SHOULD NOT use
Authors MUST NOT use |
Any element where the min attribute is allowed: meter min and input min
|
aria-valuemin="..."
|
Use the
Authors MAY use the
Authors SHOULD NOT use
Authors MUST NOT use |
Any element which allows the readonly attribute:
input readonly , textarea readonly and form-associated custom element which allows readonly
|
aria-readonly="true"
|
Use the
Authors MAY use the
Authors SHOULD NOT use the
Authors MUST NOT use |
Element with Note
This is equivalent to the |
aria-readonly="false"
|
Authors MUST NOT set aria-readonly="true" on an element that has isContentEditable="true" .
|
Any element where the required attribute is allowed: input required , textarea required , and select required
|
aria-required="true"
|
Use the
Authors MAY use the
Authors SHOULD NOT use the
Authors MUST NOT use |
Any element where the colspan attribute is allowed: td and th
|
aria-colspan="..."
|
Use the
Authors SHOULD NOT use the
Authors MUST NOT use |
Any element where the rowspan attribute is allowed:
td and th
|
aria-rowspan="..."
|
Use the
Authors SHOULD NOT use the
Authors MUST NOT use |
The ARIA Specification's Deprecated Requirements section indicates that if an ARIA feature is marked as deprecated then authors are advised not to use said feature for new content.
The following roles and attributes are deprecated features of ARIA and DPub ARIA. Conformance checkers MUST warn authors about the deprecated status of these features. Whenever possible, authors are advised to use alternatives to deprecated features.
The directory
role is marked for deprecation in WAI-ARIA 1.2. In reality, the directory
role had no functional difference to an element with an implicit or explicit list
role. Authors are advised to use one of HTML's native list elements, or an ARIA list
instead.
The doc-biblioentry
and doc-endnote
roles are marked for deprecation in Digital Publishing WAI-ARIA Module 1.1, as they are not valid children for an element with an implicit or explicit role of list
. Authors can use standard list and child li
elements without the need for these roles.
The aria-dropeffect
and aria-grabbed
attributes were deprecated in WAI-ARIA 1.1. There is presently no feature in ARIA to replace their proposed functionality.
Authors SHOULD use ASCII lowercase for all role
token values
and any state or property attributes (aria-*
) whose values are
defined as tokens.
While modern browsers treat the role
or aria-*
attribute values as ASCII case-insensitive, not all assistive technologies will correctly parse these values.
To reduce interoperability issues, authors are strongly encouraged to use ASCII lowercase for aria-*
and role
attribute values. Further, authors are encouraged to rigorously test with different browser and assistive technology combinations to ensure that their content will be correctly exposed to their users.
This section is non-normative.
The following table maps (and extends) the Kinds of content and allowed descendant
information (defined in the
[HTML] specification) to elements that have an equivalent role
.
Column 1 links to the normative Accessible Rich Internet Applications (WAI-ARIA) 1.2 definitions for each ARIA role
.
Column 2 identifies the Kinds of content
categories each role
has when it is used on an HTML element.
Column 3 indicates what kinds of HTML elements can be descendants of
an element with an explicit role
specified, often matching the HTML element with
the same implicit role.
For example, a button
element has an implicit role=button
.
In HTML a button
element allows phrasing content as descendants, and does not allow interactive content
or descendants with a tabindex
attribute. Therefore, any elements specified with a role=button
would follow
the same descendant restrictions, and not allow any interactive content descendants,
elements with a tabindex
specified, or 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>
Additionally, there are certain roles which Accessible Rich Internet Applications (WAI-ARIA) 1.2 has specified specific requirements for their allowed descendants. These have been identified in column 3 (Descendant allowances) by indicating to "Refer to the 'Required Owned Elements'" for those particular roles.
Role | Kind of content | Descendant allowances |
---|---|---|
alert
|
Flow content | Flow content but with no main element descendants. |
alertdialog
|
Flow content | Flow content |
application
|
Flow content | Flow content |
article
|
Flow content but with no main element descendants. | |
banner
|
Flow content but with no main, header, or footer element descendants. | |
blockquote
|
Flow content but with no main element descendants. | |
button
|
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
|
caption
|
N/A | Flow content but with no main or table element descendants. |
cell
|
N/A | Flow content but with no main element descendants. |
checkbox
|
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
|
code
|
Phrasing content | |
columnheader
|
N/A | Flow content but with no main, header, or footer element descendants. |
combobox
|
Flow content but with no main element descendants. | |
complementary
|
Flow content but with no main element descendants. | |
contentinfo
|
Flow content but with no main, header, or footer element descendants. | |
definition
|
Phrasing content | |
deletion
|
Phrasing content | |
dialog
|
Flow content | Flow content |
directory
|
Flow content | Flow content but with no main element descendants. |
document
|
Flow content | Flow content |
emphasis
|
Phrasing content | |
feed
|
Flow content | Flow content but with no main element descendants. |
figure
|
Flow content but with no main element descendants. | |
form
|
Flow content, but with no form element descendants.
|
|
generic
|
Flow content | |
grid
|
Refer to the "Required Owned Elements" as defined for the ARIA grid role.
|
|
gridcell
|
Interactive content | Flow content but with no main element descendants. |
group
|
Flow content | |
heading
|
Phrasing content | |
img
|
Phrasing content, but with no interactive content descendants. | |
insertion
|
Phrasing content | |
link
|
Flow content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
|
|
list
|
Flow content |
Refer to the "Required Owned Elements" as defined for the ARIA list role.
|
listbox
|
Refer to the "Required Owned Elements" as defined for the ARIA listbox role.
|
|
listitem
|
N/A | Flow content but with no main element descendants. |
log
|
Flow content | Flow content, but with no main element descendants. |
main
|
Flow content | Flow content, but with no main element descendants. |
marquee
|
Flow content | Flow content, but with no main element descendants. |
math
|
Flow content | Flow content |
menu
|
Refer to the "Required Owned Elements" as defined for the ARIA menu role.
|
|
menubar
|
Refer to the "Required Owned Elements" as defined for the ARIA menubar role.
|
|
menuitem
|
Interactive content |
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
menuitemcheckbox
|
Interactive content |
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
menuitemradio
|
Interactive content |
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
meter
|
Phrasing content, but with no meter element descendants. | |
navigation
|
Flow content, but with no main element descendants. | |
none
|
N/A | Transparent |
note
|
Flow content | Flow content, but with no main element descendants. |
option
|
Interactive content |
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
paragraph
|
Phrasing content | |
presentation
|
N/A | Transparent |
progressbar
|
Phrasing content, but with no progress element descendants. | |
radio
|
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
|
radiogroup
|
Flow content | |
region
|
Flow content, but with no main element descendants. | |
row
|
N/A |
Refer to the "Required Owned Elements" as defined for the ARIA row role.
|
rowgroup
|
N/A |
Refer to the "Required Owned Elements" as defined for the ARIA rowgroup role.
|
rowheader
|
N/A | Flow content but with no main element descendants. |
scrollbar
|
Interactive content | Phrasing content |
search
|
Flow content but with no main element descendants. | |
searchbox
|
Flow content but with no main element descendants. | |
separator
|
Interactive content (if focusable) | Phrasing content |
slider
|
Phrasing content | |
spinbutton
|
Flow content but with no main element descendants. | |
status
|
Flow content | Flow content but with no main element descendants. |
strong
|
Phrasing content | |
subscript
|
Phrasing content | |
superscript
|
Phrasing content | |
switch
|
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
|
tab
|
Interactive content |
Phrasing content, but with no
interactive content descendants, and no descendants with a tabindex attribute specified.
|
table
|
Refer to the "Required Owned Elements" as defined for the ARIA table role.
|
|
tablist
|
Refer to the "Required Owned Elements" as defined for the ARIA tablist role.
|
|
tabpanel
|
Flow content | Flow content |
term
|
Phrasing content | Phrasing content |
textbox
|
Interactive content | Flow content but with no main element descendants. |
time
|
Phrasing content | |
timer
|
Flow content | Flow content but with no main element descendants. |
toolbar
|
Flow content | Flow content but with no main element descendants. |
tooltip
|
Flow content | Phrasing content |
tree
|
Flow content |
Refer to the "Required Owned Elements" as defined for the ARIA tree role.
|
treegrid
|
Flow content |
Refer to the "Required Owned Elements" as defined for the ARIA treegrid role.
|
treeitem
|
Interactive content | Phrasing 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, SHOULD, 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 ARIA in HTML documents
MUST implement checks for the conformance requirements for use of the ARIA role
and aria-*
attributes on HTML elements as defined in this specification.
A conforming document MUST NOT contain any elements with author defined role
or aria-*
attributes with values other than those which, per this specification,
authors MAY use on each HTML element in 4.
Document conformance requirements for use of ARIA attributes in HTML.
Conformance checkers SHOULD flag instances where authors are explicitly providing
an element with a role
which matches its
implicit ARIA semantics as failures,
as it is NOT RECOMMENDED for authors to explicitly set these roles.
A conformance checker MAY define their own terminology, and level or levels of severity, when surfacing document failures to conform to this specification.
This section is non-normative.
This specification does not define the features of [wai-aria-1.2], [dpub-aria-1.0] or [HTML]. Rather it provides rules and guidance for conformance checkers that claim support for checking ARIA in HTML, as well as providing guidance to authors.
Therefore, there are no known privacy or security impacts of this specification, as it defines no new features to introduce potential concern.
Referenced in:
Referenced in:
Referenced in:
Referenced in: