ARIA in HTML

W3C Candidate Recommendation Snapshot

This version:
https://www.w3.org/TR/2021/CR-html-aria-20210706/
Latest published version:
https://www.w3.org/TR/html-aria/
Latest editor's draft:
https://w3c.github.io/html-aria/
Implementation report:
https://w3c.github.io/html-aria/results/implementation-results.html
Previous version:
https://www.w3.org/TR/2021/WD-html-aria-20210628/
Editors:
Steve Faulkner (TPGi)
Scott O'Hara (Microsoft)
Patrick H. Lauke (TetraLogical)
Participate:
GitHub w3c/html-aria
File an issue
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 authoring 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. 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/widgets, that makes use of ARIA to complement or extend the features of the host language [HTML].

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 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 in the HTML specification.

This document was published by the Web Applications Working Group as a Candidate Recommendation Snapshot. 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-webapps@w3.org (subscribe, archives).

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. A Candidate Recommendation Snapshot has received wide review and is intended to gather implementation experience.

This Candidate Recommendation is not expected to advance to Proposed Recommendation any earlier than 03 August 2021.

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. Author requirements for use of ARIA in HTML

Authors MAY use the ARIA role and aria-* attributes to change the exposed meaning (semantics) of 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 HTML elements are defined in the HTML Accessibility API Mappings specification.

The constraints defined in this specification are intended to prevent authors from making assistive technology products report nonsensical user interface (UI) information that does not represent the actual UI of the document.

Authors 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 § 3.1 Requirements for use of ARIA attributes in place of equivalent HTML attributes tables. It is NOT RECOMMENDED for authors 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 authors 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, 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 § 3.2 Case requirements for ARIA role, state and property attributes for more information.

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

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. Authors 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 
<!-- Generally 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 authors 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 that don't expose specific implicit ARIA semantics.

Note

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.

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.

It is NOT RECOMMENDED to use aria-disabled="true" on an a element with an href attribute.

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

abbr No corresponding role

Any role

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

address No corresponding role

Any role

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

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.
article role=article

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

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

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.

audio No corresponding role

Role: application

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

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

If role defined by ElementInternals, no role.

Otherwise, any role

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

b No corresponding role Any role

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

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.

bdo No corresponding role Any role

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

blockquote No corresponding role

Any role

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

body No corresponding role

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.

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.

canvas No corresponding role

Any role

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

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.

code No corresponding role Any role

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

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.

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.

dfn role=term Any role

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

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.

dl No corresponding role

Roles: group, list, presentation or none.

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

dt role=term

Role: listitem

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

em No corresponding role

Any role

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

embed No corresponding role

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

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

fieldset role=group

Roles: none, presentation or radiogroup.

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

figcaption No corresponding role

Roles: group, presentation or none.

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

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.

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.

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

If role defined by ElementInternals, no role.

Otherwise, form-related roles: button, checkbox, combobox, listbox, progressbar, group, radio, radiogroup, searchbox, slider, spinbutton, switch or textbox.

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

h1 to h6 role=heading, aria-level = the number in the element's tag name.

Roles: none, presentation or tab.

DPub Role: doc-subtitle

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

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.

hgroup No corresponding role

Any role.

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

hr role=separator

Roles: none or presentation.

DPub Role: doc-pagebreak

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

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

Any role

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

iframe No corresponding role

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

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

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.

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

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

Otherwise, if the img has an author 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.

input type=checkbox

role=checkbox

Roles: menuitemcheckbox, option or switch; button if used with aria-pressed.

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

Note

The HTML checked attribute can be used instead of the aria-checked attribute for menuitemcheckbox, option or switch roles 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.

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

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

Otherwise, any global aria-* attributes and any aria-* attributes applicable to the allowed roles.

Note

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

input type=range role=slider

No role

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

Otherwise, any global aria-* attributes and any other 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

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

Otherwise, any global aria-* attributes and any other 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.

kbd No corresponding role

Any role

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

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.

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.

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.

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

No role

Authors SHOULD NOT use the aria-valuemax or aria-valuemin attributes on meter elements.

Otherwise, any 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.

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.

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.

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

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

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

output role=status

Any role

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

p No corresponding role

Any role

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

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.

progress role=progressbar

No role

Authors SHOULD NOT use the aria-valuemax attribute on progress elements.

Otherwise, any global aria-* attributes and any other 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.

rp No corresponding role

Any role

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

rt No corresponding role

Any role

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

ruby No corresponding role

Any role

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

s No corresponding role

Any role

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

samp No corresponding role

Any role

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

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.

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

Role: menu

Authors 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

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

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.

strong No corresponding role

Any role

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

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.

sub No corresponding role

Any role

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

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.

table role=table

Any role

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

tbody role=rowgroup

Any role

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

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.

thead role=rowgroup

Any role

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

time No corresponding role

Any role

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

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 corresponding role if the ancestor table element is not exposed as a role=table, 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.

th

role=columnheader, rowheader or cell if the ancestor table element is exposed as a role=table.

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

No corresponding role if the ancestor table element is not exposed as a role=table, 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.

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.

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.

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.

var No corresponding role

Any role

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

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.

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.

Note

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

3.1 Requirements for use of ARIA attributes in place of equivalent HTML attributes

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 use aria-disabled=true on a button element, rather than the disabled attribute. However, authors 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 authors 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 author 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.

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

Authors 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, including option disabled and optgroup disabled aria-disabled="true"

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

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

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

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

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

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

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

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

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

Any element where the max attribute is allowed: meter max, progress max, and input max aria-valuemax="..."

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

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

Authors SHOULD NOT use aria-valuemax on any element which allows the max attribute. Use the max attribute instead.

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

Any element where the min attribute is allowed: meter min and input min aria-valuemin="..."

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

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

Authors SHOULD NOT use aria-valuemin on any element which allows the min attribute. Use the min attribute instead.

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

Any element which allows the readonly attribute: input readonly, textarea readonly and form-associated custom element which allows readonly aria-readonly="true"

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

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

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

Authors 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" 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 required attribute on any element that is allowed the required attribute in HTML.

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

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

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

Any element where the colspan attribute is allowed: td and th aria-colspan="..."

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

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

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

Authors 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: td and th aria-rowspan="..."

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

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

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

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

3.2 Case requirements for ARIA role, state and property attributes

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

Note

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.

4. Allowed descendants of ARIA roles

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

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>

Additionally, there are certain roles which Accessible Rich Internet Applications (WAI-ARIA) 1.1 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.

Allowed descendants of ARIA 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.
button Phrasing content, but but with no interactive content descendants, and no descendants with a tabindex attribute specified.
cell N/A Flow content but with no main element descendants.
checkbox Phrasing content, but but with no interactive content descendants, and no descendants with a tabindex attribute specified.
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
dialog Flow content Flow content
directory Flow content Flow content but with no main element descendants.
document Flow content Flow 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.
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 Flow content but with no main element, heading content, sectioning content, or sectioning roots descendants.
img Phrasing content, but with no interactive content descendants.
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.
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.
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.
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.
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

5. 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, 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 checking requirements

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

6. Privacy and security considerations

This section is non-normative.

This specification does not define the features of [wai-aria-1.1], [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.

7. Change log

This section is non-normative.

The following are some significant changes that were made since last wide review:

  1. 13-May-2021: Update allowed descendants for ARIA roles, where specific children / descendants are necessary - link to ARIA specification.
  2. 07-Mar-2021: Update allowed roles for nav element. Adds menu, menubar and tablist as allowed roles
  3. 20-Feb-2021: Add separate conformance guidance for specific aria-* attributes in HTML. Specifically, clarifies or specifies guidance for use of aria-checked, aria-disabled, aria-hidden, aria-placeholder, aria-valuemax, aria-valuemin, aria-readonly, aria-required, aria-colspan, aria-rowspan, aria-invalid
  4. 19-Feb-2021: Allow any role on svg
  5. 19-Feb-2021: aria-disabled not recommended on a with href
  6. 13-Feb-2021: Clarify custom element role allowances
  7. 13-Feb-2021: Update allowed children for roles with child presentational
  8. 25-Nov-2020: No allowed roles for img with alt=""
  9. 15-Feb-2020: Update allowances for figure element
  10. 15-Feb-2020: Limits allowed roles on img alt="some text"
  11. 15-Feb-2020: Remove allowance of role=button on summary element. Adding role=button without also re-implementing aria-expanded breaks the implicit mapping of the element.
  12. 19-Dec-2019: Adds form-associated custom element
  13. 06-Dec-2019: Adds br element. Allows role=presentation or none
  14. 18-Oct-2019: Specify author requirements for "No Role"
  15. 08-Oct-2019: Allow role=doc-epigraph on section element
  16. 30-Sep-2019: Allow role=doc-dedication on aside element
  17. 29-Sep-2019: Adds menu and autonomous custom element
  18. 28-Sep-2019: Allow role=note on section element
  19. 27-Jul-2019: Allow role=radiogroup on fieldset element
  20. 21-May-2019: Adds hgroup, a with and without href, input type=datetime-local, slot, i, rp, img with no alt and removes elements not part of the HTML Living Standard
  21. 24-Mar-2019: Adds data element
  22. 08-Jul-2018: Allow role=none and presentation on iframe element
  23. 26-Jun-2018: Allow role=combobox and spinbutton on input type=text
  24. 14-Apr-2018: Adds abbr element
  25. 29-Sep-2017: Allow role=none on any element that allows role=presentation, Add to hr element. Add to ul element
  26. 27-Aug-2017: Added conformance requirements for use of DPUB roles. Specifically for a with href, aside, dl, footer, h1-h6, header, li, nav, and section elements

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/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[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/