ARIA in HTML

W3C Editor's Draft

More details about this document
This version:
https://w3c.github.io/html-aria/
Latest published version:
https://www.w3.org/TR/html-aria/
Latest editor's draft:
https://w3c.github.io/html-aria/
History:
https://www.w3.org/standards/history/html-aria
Commit history
Implementation report:
https://w3c.github.io/html-aria/results/implementation-results.html
Editors:
Steve Faulkner (TPGi)
Scott O'Hara (Microsoft)
Patrick H. Lauke (TetraLogical)
Feedback:
GitHub w3c/html-aria (pull requests, new issue, open issues)
[email protected] with subject line [html-aria] … message topic … (archives)

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 is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/html-aria/ for the Editor's draft.

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

ARIA in HTML is an [HTML] specification module. Any HTML features, conformance requirements, or terms that this specification module makes reference to, but does not explicitly define, are defined in the HTML specification.

This document was published by the Web Applications Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement by W3C and its Members.

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. Future updates to this specification may incorporate new features.

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 2 November 2021 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 § 4. Document conformance requirements for use of ARIA attributes in HTML and § 4.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. ARIA semantics that extend and diverge from HTML

This section is non-normative.

Through the use of ARIA, authors can express semantics that go beyond the current native HTML capabilities. This can be very useful, as it provides authors the opportunity to create widgets, or extend HTML features beyond what they'd be able to do with HTML alone.

For instance, a button element has no native HTML feature to indicate a "pressed" state. ARIA allows authors to extend the semantics of the element by use of the aria-pressed attribute, allowing for an aural UI that will match the visual presentation of the control.

In the following example, a button allows for a user to toggle the state of a setting within a web application. Native HTML does not presently have a way to communicate a button being in a "pressed" or "unpressed" state, so ARIA can be used to extend the button element's semantics.

Example 1: Communicate a button's pressed state with ARIA 
<button aria-pressed=true>...button>

But then there are also situations where certain aria-* attributes are allowed for use on elements with particular roles, while the equivalent native attribute is currently not valid in HTML itself.

For instance, HTML has no direct concept of a disabled hyperlink (a href element). Constructs such as ... are not valid, and will not be conveyed to assistive technologies.

ARIA, however, diverges from HTML in this regard and does allow for an aria-disabled attribute to be specified on an element with an explicit role=link. If an author were to specify an aria-disabled=true on an HTML hyperlink, user agents would not functionally treat the hyperlink any differently (it would still be clickable/operable), however it would be exposed to assistive technologies as being in the disabled state.

Similarly, while native HTML option elements that are descendants of a select can only be set as being selected, elements with an explicit option role can not only allow the equivalent aria-selected, but also the aria-checked attribute, supporting widgets/constructs that go beyond the capabilities of a native select.

Unfortunately, in these situations where ARIA and HTML have feature parity, but diverge in allowances, it can create for a misalignment in support, if not also user experiences. In the situations where ARIA allows a feature which HTML does not support, it will often be in the author's, and ultimately the user's best interest to instead implement as a fully custom ARIA implementation.

In the following example, a hyperlink needs to be communicated as being in the disabled state. HTML does not allow for the use of the disabled attribute on a hyperlink, and using aria-disabled=true would communicate the hyperlink as being disabled to assistive technologies, but would not actually disable the element. The most effective way to both communicate and actually disable a hyperlink would be to remove the href from the a element, thus creating a placeholder link. Then, use ARIA can be applied to this placeholder link to communicate the element's intended role and state.

3. Examples of incorrect usage

This section is non-normative.

3.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 3: Wrong role 
<button role="heading">searchbutton>

3.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 4: Redundant role on button 

<button role="button">...button>

Similarly, the following uses a role=group on a fieldset element, and a role=Main on a main element. This is unnecessary, because the fieldset element is implicitly exposed as a role=group, as is the main element implicitly exposed as a role=main. Again, in practice this will likely not have any unforeseen side effects to users of assistive technology, as long as the declaration of the role value uses ASCII lowercase. Please see § 4.2 Case requirements for ARIA role, state and property attributes for more information.

Example 5: Redundant role on fieldset and main 

<fieldset role="group">...fieldset>

<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 6: Redundant role on list 

<ul role="list">...ul>

3.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 7: Unintended consequences 
<details>
  
  <summary role="button">more informationsummary>
  ...
details>

4. 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 programmatically communicated as "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

Roles: button or link

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.

br No corresponding role

Roles: presentation or none

Authors MAY specify the aria-hidden attribute on the br element. Otherwise, no other allowed aria-* attributes.

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.

details role=group

No role

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

dfn role=term

Any role

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

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.

footer

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=contentinfo

Otherwise, no corresponding role

Roles: group, none or presentation

DPub Role: doc-footnote

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, radio, 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=search, with no list attribute role=searchbox

No role

Global aria-* attributes and any aria-* attributes applicable to the searchbox 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.

link No corresponding role

No role or aria-* attributes

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

mark No corresponding role

Any role

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

math role=math

No role

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

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

Authors MAY specify the aria-hidden attribute on the picture element. Otherwise, no other allowed 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, group, 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

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.

SVG role=graphics-document as defined by SVG AAM

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

Roles: presentation or none

Authors MAY specify the aria-hidden attribute on the wbr element. Otherwise, no other allowed aria-* attributes.

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.

4.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 specify aria-disabled=true on a button element, while also implementing the necessary scripting to functionally disable the button, rather than the use disabled attribute.

As stated in WAI-ARIA's Conflicts with Host Language Semantics, when HTML elements use both aria-* attributes and their host language (HTML) equivalents, user agents MUST ignore the WAI-ARIA attributes – the native HTML attributes with the same implicit ARIA semantics take precedence. For this reason, authors SHOULD NOT specify both the native HTML attribute and the equivalent aria-* attribute on an element. Please review each attribute for any further author specific requirements.

The following table represents HTML elements and their attributes which have aria-* attribute parity.

Each language feature (element and attribute) in a cell in the first column implies the ARIA semantics (states, and properties) given in the cell in the second column of the same row. The third cell in each row defines how authors can use the native HTML feature, along with requirements for using the aria-* attributes that supply the same implicit ARIA semantics.

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

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

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

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

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

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

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, 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 § 4. Document conformance requirements for use of ARIA attributes in HTML. Conformance checkers SHOULD flag instances where authors are explicitly providing an element with a role which matches its implicit ARIA semantics as failures, as it is NOT RECOMMENDED for authors to explicitly set these roles.

A conformance checker MAY define their own terminology, and level or levels of severity, when surfacing document failures to conform to this specification.

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

8. Change log

This section is non-normative.

Substantive changes since the last published Recommendation

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; Scott O'Hara; Alexander Surkov; Bogdan Brinza; Jason Kiss; Cynthia Shelly. W3C. 13 August 2021. 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://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/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. W3C. 29 November 2021. W3C Working Group Note. URL: https://www.w3.org/TR/wai-aria-practices-1.2/