ARIA in HTML

W3C Recommendation

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

See also translations.

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. 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 Recommendation using the Recommendation track.

W3C recommends the wide deployment of this specification as a standard for the Web.

Future updates to this Recommendation may incorporate new features.

A W3C Recommendation is a specification that, after extensive consensus-building, is endorsed by W3C and its Members, and has commitments from Working Group members to royalty-free licensing for implementations.

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

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

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

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

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

Example5: 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 hrefrole=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 hrefNo corresponding role

Any role

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

abbrNo corresponding role

Any role

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

addressNo corresponding role

Any role

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

area with hrefrole=link

No role

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

area without hrefNo corresponding role

No role

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

articlerole=article

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

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

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

audioNo corresponding role

Role: application

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

autonomous custom elementRole 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.

bNo corresponding roleAny role

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

baseNo corresponding roleNo role or aria-* attributes
bdiNo corresponding roleAny role

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

bdoNo corresponding roleAny role

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

blockquoteNo corresponding role

Any role

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

bodyNo corresponding role

No role

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

brNo corresponding role

Roles: presentation or none.

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

buttonrole=button

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

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

canvasNo corresponding role

Any role

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

captionNo corresponding role

No role

Global aria-* attributes

citeNo corresponding roleAny role

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

codeNo corresponding roleAny role

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

colNo corresponding roleNo role or aria-* attributes
colgroupNo corresponding roleNo role or aria-* attributes
dataNo corresponding roleAny role

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

datalistrole=listbox

No role

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

ddrole=definition

No role

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

delNo corresponding role

Any role

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

dfnrole=termAny role

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

detailsrole=group

No role

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

dialogrole=dialog

Role: alertdialog

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

divNo corresponding role

Any role

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

dlNo corresponding role

Roles: group, list, presentation or none.

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

dtrole=term

Role: listitem

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

emNo corresponding role

Any role

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

embedNo corresponding role

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

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

fieldsetrole=group

Roles: none, presentation or radiogroup.

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

figcaptionNo corresponding role

Roles: group, presentation or none.

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

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

formIf 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 elementRole 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, searcx, slider, spinbutton, switch or textbox.

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

h1 to h6role=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.

headNo corresponding roleNo role or aria-* attributes
headerIf 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.

hgroupNo corresponding role

Any role.

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

hrrole=separator

Roles: none or presentation.

DPub Role: doc-pagebreak

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

htmlrole=documentNo role or aria-* attributes
iNo corresponding role

Any role

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

iframeNo 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=presentationNo role or aria-* attributes except aria-hidden="true".
img without an alt attributerole=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=buttonrole=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=colorNo corresponding role

No role

Global aria-* attributes

input type=dateNo corresponding role

No role

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

input type=datetime-localNo corresponding role

No role

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

input type=email with no list attributerole=textbox

No role

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

input type=fileNo corresponding role

No role

Global aria-* attributes

input type=hiddenNo corresponding roleNo role or aria-* attributes
input type=imagerole=button

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

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

input type=monthNo corresponding role

No role

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

input type=numberrole=spinbutton

No role

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

input type=passwordNo corresponding role

No role

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

input type=radiorole=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=rangerole=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=resetrole=button

No role

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

input type=submitrole=button

No role

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

input type=tel, with no list attributerole=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 attributerole=textbox

Roles: combobox, searcx 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 attributerole=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=timeNo corresponding role

No role

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

input type=url with no list attributerole=textbox

No role

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

input type=weekNo corresponding role

No role

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

insNo corresponding role

Any role

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

kbdNo corresponding role

Any role

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

labelNo corresponding role

No role

Global aria-* attributes

legendNo corresponding role

No role

Global aria-* attributes

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

mainrole=main

No role

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

mapNo corresponding roleNo role or aria-* attributes
mathrole=math

No role

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

markNo corresponding role

Any role

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

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

metaNo corresponding roleNo role or aria-* attributes
meterNo corresponding role

No role

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

Otherwise, any global aria-* attributes.

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

noscriptNo corresponding roleNo role or aria-* attributes
objectNo corresponding role

Roles: application, document or img.

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

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

optgrouprole=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 datalistrole=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.

outputrole=status

Any role

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

pNo corresponding role

Any role

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

paramNo corresponding roleNo role or aria-* attributes
pictureNo corresponding roleNo role or aria-* attributes
preNo corresponding role

Any role

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

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

qNo corresponding role

Any role

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

rpNo corresponding role

Any role

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

rtNo corresponding role

Any role

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

rubyNo corresponding role

Any role

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

sNo corresponding role

Any role

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

sampNo corresponding role

Any role

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

scriptNo corresponding roleNo role or aria-* attributes
sectionrole=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.

slotNo corresponding roleNo role or aria-* attributes
smallNo corresponding role

Any role

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

sourceNo corresponding roleNo role or aria-* attributes
spanNo corresponding role

Any role

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

strongNo corresponding role

Any role

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

styleNo corresponding roleNo role or aria-* attributes
subNo corresponding role

Any role

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

summaryrole=button

No role

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

supNo corresponding role

Any role

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

SVGrole=graphics-document as defined by SVG AAM

Any role

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

tablerole=table

Any role

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

tbodyrole=rowgroup

Any role

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

templateNo corresponding roleNo role or aria-* attributes
textarearole=textbox

No role

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

tfootrole=rowgroup

Any role

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

theadrole=rowgroup

Any role

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

timeNo corresponding role

Any role

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

titleNo corresponding roleNo 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.

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

trackNo corresponding roleNo role or aria-* attributes
uNo corresponding role

Any role

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

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

varNo corresponding role

Any role

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

videoNo corresponding role

Role: application

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

wbrNo 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 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 allowedaria-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 disabledaria-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 attributearia-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 allowedaria-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 maxaria-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 minaria-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 readonlyaria-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 requiredaria-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 tharia-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 tharia-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.

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
RoleKind of contentDescendant allowances
alertFlow contentFlow content but with no main element descendants.
alertdialogFlow contentFlow content
applicationFlow contentFlow content
articleFlow content but with no main element descendants.
bannerFlow content but with no main, header, or footer element descendants.
buttonPhrasing content, but but with no interactive content descendants, and no descendants with a tabindex attribute specified.
cellN/AFlow content but with no main element descendants.
checkboxPhrasing content, but but with no interactive content descendants, and no descendants with a tabindex attribute specified.
columnheaderN/AFlow content but with no main, header, or footer element descendants.
comboboxFlow content but with no main element descendants.
complementaryFlow content but with no main element descendants.
contentinfoFlow content but with no main, header, or footer element descendants.
definitionPhrasing content
dialogFlow contentFlow content
directoryFlow contentFlow content but with no main element descendants.
documentFlow contentFlow content
feedFlow contentFlow content but with no main element descendants.
figureFlow content but with no main element descendants.
formFlow content, but with no form element descendants.
gridRefer to the "Required Owned Elements" as defined for the ARIA grid role.
gridcellInteractive contentFlow content but with no main element descendants.
groupFlow content
headingFlow content but with no main element, heading content, sectioning content, or sectioning roots descendants.
imgPhrasing content, but with no interactive content descendants.
linkFlow content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
listFlow contentRefer to the "Required Owned Elements" as defined for the ARIA list role.
listboxRefer to the "Required Owned Elements" as defined for the ARIA listbox role.
listitemN/AFlow content but with no main element descendants.
logFlow contentFlow content, but with no main element descendants.
mainFlow contentFlow content, but with no main element descendants.
marqueeFlow contentFlow content, but with no main element descendants.
mathFlow contentFlow content
menuRefer to the "Required Owned Elements" as defined for the ARIA menu role.
menubarRefer to the "Required Owned Elements" as defined for the ARIA menubar role.
menuitemInteractive contentPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
menuitemcheckboxInteractive contentPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
menuitemradioInteractive contentPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
navigationFlow content, but with no main element descendants.
noneN/ATransparent
noteFlow contentFlow content, but with no main element descendants.
optionInteractive contentPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
presentationN/ATransparent
progressbarPhrasing content, but with no progress element descendants.
radioPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
radiogroupFlow content
regionFlow content, but with no main element descendants.
rowN/ARefer to the "Required Owned Elements" as defined for the ARIA row role.
rowgroupN/ARefer to the "Required Owned Elements" as defined for the ARIA rowgroup role.
rowheaderN/AFlow content but with no main element descendants.
scrollbarInteractive contentPhrasing content
searchFlow content but with no main element descendants.
searcxFlow content but with no main element descendants.
separatorInteractive content (if focusable)Phrasing content
sliderPhrasing content
spinbuttonFlow content but with no main element descendants.
statusFlow contentFlow content but with no main element descendants.
switchPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
tabInteractive contentPhrasing content, but with no interactive content descendants, and no descendants with a tabindex attribute specified.
tableRefer to the "Required Owned Elements" as defined for the ARIA table role.
tablistRefer to the "Required Owned Elements" as defined for the ARIA tablist role.
tabpanelFlow contentFlow content
termPhrasing contentPhrasing content
textboxInteractive contentFlow content but with no main element descendants.
timerFlow contentFlow content but with no main element descendants.
toolbarFlow contentFlow content but with no main element descendants.
tooltipFlow contentPhrasing content
treeFlow contentRefer to the "Required Owned Elements" as defined for the ARIA tree role.
treegridFlow contentRefer to the "Required Owned Elements" as defined for the ARIA treegrid role.
treeitemInteractive contentPhrasing 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.1Normative 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.2Informative 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/