ARIA in HTML

W3C Working Draft

This version:
https://www.w3.org/TR/2021/WD-html-aria-20210309/
Latest published version:
https://www.w3.org/TR/html-aria/
Latest editor's draft:
https://w3c.github.io/html-aria/
Previous version:
https://www.w3.org/TR/2021/WD-html-aria-20210308/
Editors:
Steve Faulkner (The Paciello Group)
Scott O'Hara (The Paciello Group)
Patrick H. Lauke (TetraLogical)
Participate:
GitHub w3c/html-aria
File a bug
Commit history
Pull requests

Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

Abstract

This specification defines the developer rules (author conformance requirements) for the use of Accessible Rich Internet Applications (WAI-ARIA) 1.1 and Digital Publishing WAI-ARIA Module 1.0 attributes on [HTML] elements. It also defines requirements for Conformance Checking tools.

Status of This Document

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 [email protected] (subscribe, 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 15 September 2020 W3C Process Document.

1. Developer requirements for use of ARIA in HTML

Developers MAY use the ARIA role and aria-* attributes on HTML elements, in accordance with the requirements described in WAI-ARIA, except where these conflict with the strong native semantics or are equal to the implicit ARIA semantics of a given HTML element. The implicit ARIA semantics for an HTML element are defined in the HTML Accessibility API Mappings specification.

The constraints defined in this specification 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.

Developers MUST NOT use the ARIA role and aria-* attributes in a manner that conflicts with the semantics described in the § 3. Document conformance requirements for use of ARIA attributes in HTML and §  Document conformance requirements for use of ARIA attributes with HTML attributes tables. It is NOT RECOMMENDED for developers to set the ARIA role and aria-* attributes to values that match the implicit ARIA semantics defined in the table. Doing so is unnecessary and can potentially lead to unintended consequences.

2. Examples of incorrect usage

This section is non-normative.

2.1 Don't override default roles

This section is non-normative.

The following uses a role=heading on a button element. This is not allowed, because the button element has default characteristics that conflict with the heading role.

Example 1: Wrong role 
<button role="heading">search</button>

2.2 Don't add redundant roles

This section is non-normative.

The following uses a role=button on a button element. This is unnecessary, as "button" is already exposed as the implicit role for the element. In practice this redundancy will likely not have any unforeseen side effects, other than unnecessarily making the markup more verbose, and incorrectly signaling to other developers that this practice is useful.

Example 2: Redundant role on button 
<!-- Avoid doing this! -->
<button role="button">...</button>

Similarly, the following uses a role=group on a fieldset element. This is unnecessary, because the fieldset element is implicitly exposed as a role=group. Again, in practice this will likely not have any unforeseen side effects.

Example 3: Redundant role on fieldset 
<!-- Avoid doing this! -->
<fieldset role="group">...</fieldset>

The following uses a role=list on an ul element. This is generally unnecessary, because the ul element is implicitly exposed as a role=list. However, some user agents suppress a list's implicit ARIA semantics if list markers are removed. Developers can use role=list to reinstate the role if necessary, though this practice would generally not be recommended, otherwise.

Example 4: Redundant role on list 
<!-- Avoid doing this! -->
<ul role="list">...</ul>

2.3 Be cautious of side effects

This section is non-normative.

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 different role.

Example 5: Unintended consequences 
<details>
  <!-- Avoid doing this! -->
  <summary role="button">more information</summary>
  ...
</details>

3. Document conformance requirements for use of ARIA attributes in HTML

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 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 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. If a cell in the third column includes the term No role it indicates that developers MUST NOT overwrite the implicit ARIA semantics, or native semantics of the HTML element.

Note

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, in user agents which lack exposing specific implicit ARIA semantics.

Rules of ARIA attribute usage by HTML element
HTML element

Implicit ARIA semantics (explicitly assigning these in markup is NOT RECOMMENDED)

ARIA roles, states and properties which MAY be used
a with href role=link

Roles: button, checkbox, menuitem, menuitemcheckbox, menuitemradio, option, radio, switch, tab or treeitem

DPub Roles: doc-backlink, doc-biblioref, doc-glossref or doc-noteref

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

It is NOT RECOMMENDED to use aria-disabled="true" on an a element with an href attribute. If a link needs to be "disabled", remove the href attribute.
a without href No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

abbr No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

address No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

area with href role=link

No role

Global aria-* attributes and any aria-* attributes applicable to the link role.

area without href No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).
article role=article

Roles: application, document, feed, main, none, presentation or region.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

aside role=complementary

Roles: feed, none, note, presentation, region or search.

DPub Roles: doc-dedication, doc-example, doc-footnote, doc-pullquote or doc-tip

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

audio No corresponding role

Role: application

Global aria-* attributes and any aria-* attributes applicable to the application role.

autonomous custom element Role exposed from developer defined ElementInternals. Otherwise no corresponding role.

If no developer defined role,
Any role

Otherwise only allowed roles for the role exposed by the custom element's ElementInternals.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

b No corresponding role Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

base No corresponding role No role or aria-* attributes
bdi No corresponding role Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

bdo No corresponding role Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

blockquote No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

body role=document

No role

Global aria-* attributes and any aria-* attributes applicable to the document role.

br No corresponding role

Roles: presentation or none.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

button role=button

Roles: checkbox, link, menuitem, menuitemcheckbox, menuitemradio, option, radio, switch or tab.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

canvas No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

caption No corresponding role

No role

Global aria-* attributes

cite No corresponding role Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

code No corresponding role Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

col No corresponding role No role or aria-* attributes
colgroup No corresponding role No role or aria-* attributes
data No corresponding role Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

datalist role=listbox

No role

Global aria-* attributes and any aria-* attributes applicable to the listbox role.

dd role=definition

No role

Global aria-* attributes and any aria-* attributes applicable to the definition role.

del No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

dfn role=term Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

details role=group

No role

Global aria-* attributes and any aria-* attributes applicable to the group role.

dialog role=dialog

Role: alertdialog

Global aria-* attributes and any aria-* attributes applicable to the dialog role.

div No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

dl No corresponding role

Roles: group, list, presentation or none.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

dt role=term

Role: listitem

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

em No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

embed No corresponding role

Roles: application, document, img, presentation or none.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

fieldset role=group

Roles: none, presentation or radiogroup.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

figcaption No corresponding role

Roles: group, presentation or none.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

figure role=figure

If the figure has no figcaption descendant:
Any role

If the figure has a figcaption descendant:
No role.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

form If the form element has an accessible name: role=form. Otherwise, no corresponding role.

Roles: search, none or presentation.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

form-associated custom element Role exposed from developer defined ElementInternals. Otherwise no corresponding role.

If no developer defined role,
Roles: application, button, checkbox, combobox, group, listbox, progressbar, radio, radiogroup, searchbox, slider, spinbutton, switch or textbox.

Otherwise only allowed roles for the role exposed by the custom element's ElementInternals.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

h1 to h6 role=heading, with the aria-level = positive integer.

Roles: none, presentation or tab.

DPub Role: doc-subtitle

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

head No corresponding role No role or aria-* attributes
header If not a descendant of an article, aside, main, nav or section element, or an element with role=article, complementary, main, navigation or region then role=banner. Otherwise no corresponding role

Roles: group, none or presentation.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

hgroup No corresponding role

Any role.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

hr role=separator

Roles: none or presentation.

DPub Role: doc-pagebreak

Global aria-* attributes and any aria-* attributes applicable to the separator role.

html No corresponding role No role or aria-* attributes
i No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

iframe No corresponding role

Roles: application, document, img, none or presentation.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

img with alt="some text" role=img

Roles: button, checkbox, link, menuitem, menuitemcheckbox, menuitemradio, option, progressbar, scrollbar, separator, slider, switch, tab or treeitem

DPub Role: doc-cover.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

img with alt="" No corresponding role No role or aria-* attributes except aria-hidden="true".
img without alt attribute role=img

If no accessible name is provided via other img naming methods: No role, and no aria-* attributes except aria-hidden="true".

Otherwise, if the img has an developer defined accessible name, see img with alt="some text".

input type=button role=button

Roles: link, menuitem, menuitemcheckbox, menuitemradio, option, radio, switch or tab.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

input type=checkbox

role=checkbox

Roles: button (when used with aria-pressed), menuitemcheckbox, option or switch.

Developers SHOULD NOT use the aria-checked attribute on input type=checkbox elements.

Otherwise, any global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

Note: the HTML checked attribute can be used instead of the aria-checked attribute for menuitemcheckbox, option or switch when used on type=checkbox.

input type=color No corresponding role

No role

Global aria-* attributes

input type=date No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=datetime-local No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=email with no list attribute role=textbox

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=file No corresponding role

No role

Global aria-* attributes

input type=hidden No corresponding role No role or aria-* attributes
input type=image role=button

Roles: link, menuitem, menuitemcheckbox, menuitemradio, radio or switch.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

input type=month No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=number role=spinbutton

No role

Global aria-* attributes and any aria-* attributes applicable to the spinbutton role.

input type=password No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=radio role=radio

Role: menuitemradio

Developers SHOULD NOT use the aria-checked attribute on input type=radio elements.

Otherwise, any global aria-* attributes and any aria-* attributes applicable to the exposed role.

Note: the HTML checked attribute can be used instead of the aria-checked attribute for menuitemradio when used on type=radio.

input type=range role=slider

No role

Developers SHOULD NOT use the aria-valuemax or aria-valuemin attributes on input type=range.

Otherwise, any global aria-* attributes and any aria-* attributes applicable to the slider role.

input type=reset role=button

No role

Global aria-* attributes and any aria-* attributes applicable to the button role.

input type=submit role=button

No role

Global aria-* attributes and any aria-* attributes applicable to the button role.

input type=tel, with no list attribute role=textbox

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=text or with a missing or invalid type, with no list attribute role=textbox

Roles: combobox, searchbox or spinbutton.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles.

input type=text, search, tel, url, email, or with a missing or invalid type, with a list attribute role=combobox

No role

Developers SHOULD NOT use the aria-haspopup attribute on the indicated inputs with a list attribute.

Otherwise, any global aria-* attributes and any aria-* attributes applicable to the combobox role.

input type=time No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=url with no list attribute role=textbox

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

input type=week No corresponding role

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

ins No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

kbd No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

label No corresponding role

No role

global aria-* attributes

legend No corresponding role

No role

global aria-* attributes

li role=listitem

Roles: menuitem, menuitemcheckbox, menuitemradio, option, none, presentation, radio, separator, tab or treeitem

DPub Roles: doc-biblioentry, doc-endnote.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

main role=main

No role

Global aria-* attributes and any aria-* attributes applicable to the main role.

map No corresponding role No role or aria-* attributes
math role=math

No role

Global aria-* attributes and any aria-* attributes applicable to the math role.

mark No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

menu role=list

Roles: directory, group, listbox, menu, menubar, none, presentation, radiogroup, tablist, toolbar or tree.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

meta No corresponding role No role or aria-* attributes
meter No corresponding role

No role

Global aria-* attributes.

nav role=navigation

Roles: menu, menubar or tablist.

DPub Roles: doc-index, doc-pagelist, doc-toc.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

noscript No corresponding role No role or aria-* attributes
object No corresponding role

Roles: application, document or img.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

ol role=list

Roles: directory, group, listbox, menu, menubar, none, presentation, radiogroup, tablist, toolbar or tree

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

optgroup role=group

No role

Global aria-* attributes and any aria-* attributes applicable to the group role.

option element that is in a list of options or that represents a suggestion in a datalist role=option

No role

Developers SHOULD NOT use the aria-selected attribute on the option element.

Global aria-* attributes and any aria-* attributes applicable to the option role.

output role=status

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

p No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

param No corresponding role No role or aria-* attributes
picture No corresponding role No role or aria-* attributes
pre No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

progress role=progressbar

No role

Global aria-* attributes and any aria-* attributes applicable to the progressbar role.

q No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

rp No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

rt No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

ruby No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

s No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

samp No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

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: alert, alertdialog, application, banner, complementary, contentinfo, dialog, document, feed, log, main, marquee, navigation, none, note, presentation, search, status or tabpanel

DPub Roles: doc-abstract, doc-acknowledgments, doc-afterword, doc-appendix, doc-bibliography, doc-chapter, doc-colophon, doc-conclusion, doc-credit, doc-credits, doc-dedication, doc-endnotes, doc-epigraph, doc-epilogue, doc-errata, doc-example, doc-foreword, doc-glossary, doc-index, doc-introduction, doc-notice, doc-pagelist, doc-part, doc-preface, doc-prologue, doc-pullquote, doc-qna, doc-toc

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

select (with NO multiple attribute and NO size attribute having value greater than 1) role=combobox

Role: menu

Developers SHOULD NOT use the aria-multiselectable attribute on a select element.

Otherwise, any global aria-* attributes and any other aria-* attributes applicable to the combobox or menu role.

select (with a multiple attribute or a size attribute having value greater than 1) role=listbox

No role

Developers SHOULD NOT use the aria-multiselectable attribute on a select element.

Otherwise, any global aria-* attributes and any other aria-* attributes applicable to the listbox role.

slot No corresponding role No role or aria-* attributes
small No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

source No corresponding role No role or aria-* attributes
span No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

strong No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

style No corresponding role No role or aria-* attributes
SVG role=graphics-document as defined by SVG AAM

Any Role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

sub No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

summary role=button

No role

Global aria-* attributes and any aria-* attributes applicable to the button role.

sup No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

table role=table

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

tbody role=rowgroup

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

template No corresponding role No role or aria-* attributes
textarea role=textbox

No role

Global aria-* attributes and any aria-* attributes applicable to the textbox role.

tfoot role=rowgroup

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

thead role=rowgroup

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

time No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

title No corresponding role No role or aria-* attributes
td

role=cell if the ancestor table element is exposed as a role=table.

role=gridcell if the ancestor table element is exposed as a role=grid or treegrid.

No role if the ancestor table element has role=table, grid, or treegrid; otherwise any role.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

th

If the ancestor table element is exposed as a role=table: role=columnheader, rowheader or cell according to HTML AAM.

If the ancestor table element is exposed as a role=grid or treegrid: role=columnheader, rowheader or gridcell according to HTML AAM.

No role if the ancestor table element has role=table, grid, or treegrid; otherwise any role.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

tr role=row

No role if the ancestor table element has role=table, grid, or treegrid; otherwise any role.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

track No corresponding role No role or aria-* attributes
u No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

ul role=list

Roles: directory, group, listbox, menu, menubar, none, presentation, radiogroup, tablist, toolbar or tree.

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

var No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

video No corresponding role

Role: application

Global aria-* attributes and any aria-* attributes applicable to the application role.

wbr No corresponding role

Any role

Global aria-* attributes and any aria-* attributes applicable to the allowed roles and implied role (if any).

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 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.

Note

Developers are encouraged to make use of the following documents for guidance on using ARIA in HTML beyond that which is provided here:

  • Using ARIA - A practical guide for developers on how to add accessibility information to HTML elements using the Accessible Rich Internet Applications specification (ARIA 1.1).
  • WAI-ARIA Authoring Practices 1.2 - An author's guide to understanding and implementing Accessible Rich Internet Applications.

Document conformance requirements for use of ARIA attributes with HTML attributes

Unless otherwise stated, developers MAY use aria-* attributes in place of their HTML equivalents on HTML elements where the aria-* semantics would be expected. For example, developers MAY use aria-disabled=true on a button element, rather than the disabled attribute. However, developers SHOULD NOT use both the native HTML attribute and the aria-* attribute together, and MUST NOT use the these features together when their values are in opposition to each other. As stated in WAI-ARIA's Conflicts with Host Language Semantics, user agents MUST ignore WAI-ARIA attributes and use the host language (HTML) attribute with the same implicit ARIA semantics.

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 developers can use the native HTML feature, along with requirements for using the aria-* attributes that supply the same implicit ARIA semantics.

Rules of ARIA attribute usage by HTML feature
HTML feature

Implicit ARIA semantics

HTML feature and aria-* attribute developer guidance
Any element where the checked attribute is allowed aria-checked="true"

Use the checked attribute on any element that is allowed the checked attribute in HTML.

Developers SHOULD NOT use the aria-checked attribute on any element where the checkedness of the element can be in opposition to the current value of the aria-checked attribute.

Developers MAY use the aria-checked attribute on any other element with a WAI-ARIA role which allows the attribute.

Any element where the disabled attribute is allowed aria-disabled="true"

Use the disabled attribute on any element that is allowed the disabled attribute in HTML.

Developers MAY use the aria-disabled attribute on any element that is allowed the disabled attribute in HTML, or any element with a WAI-ARIA role which allows the aria-disabled attribute.

Developers SHOULD NOT use aria-disabled="true" on any element which also has a disabled attribute.

Developers MUST NOT use aria-disabled="false" on any element which also has a disabled attribute.

Any element with a hidden attribute aria-hidden="true"

Developers MAY use the aria-hidden attribute on any HTML element that allows global aria-* attributes, with the following exceptions:

Developers SHOULD NOT use the aria-hidden="true" attribute on any element which also has a hidden attribute.

Any element where the placeholder attribute is allowed aria-placeholder="..."

Use the placeholder attribute on any element that is allowed the placeholder attribute in HTML.

Developers MAY use the aria-placeholder attribute on any element that is allowed the placeholder attribute in HTML, or any element with a WAI-ARIA role which allows the aria-placeholder attribute.

Developers MUST NOT use the aria-placeholder attribute on any element which also has a placeholder attribute.

Any element where the max attribute is allowed aria-valuemax="..."

Use the max attribute on any element that is allowed the max attribute in HTML. It is NOT RECOMMENDED to use the aria-valuemax attribute on these elements.

Developers MAY use the aria-valuemax attribute on any other element with a WAI-ARIA role which allows the attribute.

Developers SHOULD NOT use aria-valuemax on any element which also has a max attribute, even if the values of each attribute match.

Developers MUST NOT use aria-valuemax on any element which also has a max attribute, and the values of each attribute do not match.

Any element where the min attribute is allowed aria-valuemin="..."

Use the min attribute on any element that is allowed the min attribute in HTML. It is NOT RECOMMENDED to use the aria-valuemin attribute on these elements.

Developers MAY use the aria-valuemin attribute on any other element with a WAI-ARIA role which allows the attribute.

Developers SHOULD NOT use aria-valuemin on any element which also has a min attribute, even if the values of each attribute match.

Developers MUST NOT use aria-valuemin on any element which also has a min attribute, and the values of each attribute do not match.

Any element where the readonly attribute is allowed aria-readonly="true"

Use the readonly attribute on any element that is allowed the readonly attribute in HTML. It is NOT RECOMMENDED to use aria-readonly on these elements.

Developers MAY use the aria-readonly attribute on any element with a WAI-ARIA role which allows the aria-readonly attribute.

Developers SHOULD NOT use the aria-readonly="true" on any element which also has a readonly attribute.

Developers MUST NOT use aria-readonly="false" on any element which also has a readonly attribute.

Element with contenteditable="true"; or
Element without contenteditable attribute whose closest ancestor with a contenteditable attribute has contenteditable="true".

Note: this is equivalent to the isContentEditable IDL attribute.

aria-readonly="false" Developers MUST NOT set aria-readonly="true" on an element that has isContentEditable="true".
Any element where the required attribute is allowed aria-required="true"

Use the required attribute on any element that is allowed the required attribute in HTML.

Developers MAY use the aria-required attribute on any element that is allowed the required attribute in HTML, or any element with a WAI-ARIA role which allows the aria-required attribute.

Developers SHOULD NOT use the aria-required="true" on any element which also has a required attribute.

Developers MUST NOT use aria-required="false" on any element which also has a required attribute.

Any element where the colspan attribute is allowed aria-colspan="..."

Use the colspan attribute on any element that is allowed the colspan attribute in HTML.

Developers MAY use the aria-colspan attribute on any element that is allowed the colspan attribute in HTML, or any element with a WAI-ARIA role which allows the aria-colspan attribute.

Developers SHOULD NOT use the aria-colspan attribute on any element which also has a colspan attribute.

Developers MUST NOT use aria-colspan on any element which also has a colspan attribute, and the values of each attribute do not match.

Any element where the rowspan attribute is allowed aria-rowspan="..."

Use the rowspan attribute on any element that is allowed the rowspan attribute in HTML.

Developers MAY use the aria-rowspan attribute on any element that is allowed the rowspan attribute in HTML, or any element with a WAI-ARIA role which allows the aria-rowspan attribute.

Developers SHOULD NOT use the aria-rowspan attribute on any element which also has a rowspan attribute.

Developers MUST NOT use aria-rowspan on any element which also has a rowspan attribute, and the values of each attribute do not match.

Element that is a candidate for constraint validation but that does not satisfy its constraints aria-invalid="true"

The aria-invalid attribute MAY be used on any HTML element that allows global aria-* attributes except for a submittable element that does not satisfy its validation constraints.

4. Case requirements for ARIA role, state and property attributes

Developers MUST use lowercase ASCII letters for all role token values and any state or property attributes (aria-*) whose values are defined as tokens.

5. Allowed ARIA roles, states and properties

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, a button element has an implicit role=button. 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 also MUST 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).

Examples of non-conforming descendants 
<!-- conformance checkers will report an error -->

<button>
<div role="button">...</div>
</button>

<div role="button">
<button>...</button>
</div>

<div role="link">
<textarea>...</textarea>
</div>
ARIA Roles, States and Properties
Role Required Properties Supported Properties Kind of content Descendant restrictions
any none n/a n/a
alert none aria-expanded (state) Flow content Flow content
alertdialog none Flow content Flow content
application none Flow content Flow content
article none

aria-expanded (state)

Flow content No main element descendants.
banner none aria-expanded (state) 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 none Interactive content Phrasing content, but there must be no interactive content descendant.
checkbox aria-checked (state) aria-readonly Interactive content Phrasing content, but there must be no interactive content descendant.
cell none Flow content Flow content
columnheader none Flow content Flow content
combobox Interactive content Flow content
complementary none aria-expanded (state) Flow content Flow content, but with no main element descendants.
contentinfo none aria-expanded (state) 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 none

aria-expanded (state)

Phrasing content Phrasing content
dialog none Flow content Flow content
directory none aria-expanded (state) Flow content Flow content
document none

aria-expanded (state)

Flow content Flow content
feed none aria-expanded (state) Flow content Flow content
figure none aria-expanded (state) Flow content Flow content
form none

aria-expanded (state)

Flow content Flow content
grid none

Flow content

Interactive content

Flow content
gridcell none

Flow content

Interactive content

Flow content
group none Flow content Flow content
heading none Heading content Flow content, but with no Heading content, Sectioning content, Sectioning roots.
img none

aria-expanded (state)

Flow content Phrasing content
link none

aria-expanded (state)

Flow content Flow content, but with no interactive content or a element descendants.
list none

aria-expanded (state)

Flow content Flow content
listbox none

Flow content

Interactive content

Flow content
listitem none Flow content Flow content
log none

aria-expanded (state)

Flow content Flow content
main none

aria-expanded (state)

Flow content Flow content, but with no main element descendants
marquee none

aria-expanded (state)

Flow content Flow content
math none

aria-expanded (state)

Flow content Flow content
menu none

Flow content

Interactive content

Flow content
menubar none

Flow content

Interactive content

Flow content
menuitem none Interactive content Flow content, but with no interactive content descendants.
menuitemcheckbox aria-checked (state) Interactive content Phrasing content, but with no interactive content descendants.
menuitemradio aria-checked (state) Interactive content Phrasing content, but with no interactive content descendants.
navigation none

aria-expanded (state)

Flow content Flow content, but with no main element descendants
none none   Flow content Flow content
note none

aria-expanded (state)

Flow content Flow content
option none Interactive content Phrasing content, but with no interactive content descendants.
presentation none Flow content Flow content
progressbar none Flow content Phrasing content
radio aria-checked (state) Interactive content Phrasing content, but with no interactive content descendants.
radiogroup none Flow content Flow content
region none

aria-expanded (state)

Flow content Flow content
row none

If child of role=grid, rowgroup, table or treegrid:

Also, if child of role=treegrid:

 none Flow content
rowgroup none   none Flow content
rowheader none none Flow content
scrollbar

Flow content

Interactive content

Phrasing content
search none aria-expanded (state)

Flow content

Flow content
searchbox none Interactive content Flow content, but with no interactive content descendants.
separator

Interactive content (if focusable)

Phrasing content
slider Interactive content Phrasing content
spinbutton

Flow content

Interactive content

Flow content
status none

aria-expanded (state)

Flow content

Flow content
switch aria-checked (state) aria-readonly

Interactive content

Phrasing content, but with no interactive content descendants.
tab none interactive content Phrasing content, but with no interactive content descendants.
table none Flow content Flow content
tablist none Flow content Flow content
tabpanel none

aria-expanded (state)

Flow content Flow content
term none aria-expanded (state) Phrasing content Phrasing content
textbox none Interactive content Flow content, but with no interactive content descendants.
timer none

aria-expanded (state)

Flow content Flow content
toolbar none Flow content Flow content
tooltip none

aria-expanded (state)

Flow content Flow content
tree none Flow content Flow content
treegrid none Flow content Flow content
treeitem none Interactive content Flow content

6. Conformance

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 § 3. 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 (whose explicit use in markup is NOT RECOMMENDED).

A. References

A.1 Normative references

[dpub-aria-1.0]
Digital Publishing WAI-ARIA Module 1.0. Matt Garrish; Tzviya Siegman; Markus Gylling; Shane McCarron. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/dpub-aria-1.0/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[html-aam-1.0]
HTML Accessibility API Mappings 1.0. Steve Faulkner; Alexander Surkov; Scott O'Hara; Bogdan Brinza; Jason Kiss; Cynthia Shelly. W3C. 17 August 2020. W3C Working Draft. URL: https://www.w3.org/TR/html-aam-1.0/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[svg-aam-1.0]
SVG Accessibility API Mappings. Amelia Bellamy-Royds; Ian Pouncey. W3C. 10 May 2018. W3C Working Draft. URL: https://www.w3.org/TR/svg-aam-1.0/
[wai-aria-1.1]
Accessible Rich Internet Applications (WAI-ARIA) 1.1. Joanmarie Diggs; Shane McCarron; Michael Cooper; Richard Schwerdtfeger; James Craig. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/wai-aria-1.1/

A.2 Informative references

[using-aria]
Using ARIA. Steve Faulkner; David MacDonald. W3C. 27 September 2018. W3C Working Draft. URL: https://www.w3.org/TR/using-aria/
[wai-aria-practices-1.2]
WAI-ARIA Authoring Practices 1.2. Matthew King; JaEun Jemma Ku; James Nurthen; Zoë Bijl; Michael Cooper; Joseph Scheuhammer; Lisa Pappas; Richard Schwerdtfeger. W3C. 18 December 2019. W3C Working Draft. URL: https://www.w3.org/TR/wai-aria-practices-1.2/