This specification defines the authoring rules (author conformance requirements) for the use of [[[wai-aria-1.1]]] and [[[dpub-aria-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]].

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|HTML specification]].

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-1.1|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-aam-1.0|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 [[[#docconformance]]] and [[[#docconformance-attr]]] 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.

Examples of incorrect usage

Don't override default roles

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.

          <button role="heading">search</button>
        

Don't add redundant roles

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.

          <!-- 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 [[[#case-sensitivity]]] for more information.

          <!-- Avoid doing this! -->
          <fieldset role="group">...</fieldset>
          <!-- or this! -->
          <main role="Main">...</main>
        

The following uses a `role=list` on an [^ul^] element. 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.

          <!-- Generally avoid doing this! -->
          <ul role="list">...</ul>
        

Be cautious of side effects

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.

          <details>
            <!-- Avoid doing this! -->
            <summary role="button">more information</summary>
            ...
          </details>
        

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

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.

While it is conforming to use [[[dpub-aria-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 [^a/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.

If a link needs to be "disabled", remove the `href` attribute.
[^a^] without [^a/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 [^area/href^] role=link

No `role`

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

[^area^] without [^area/href^] No corresponding role

No `role`

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

[^article^] role=article

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

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

[^aside^] role=complementary

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

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

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

[^audio^] No corresponding role

Role: `application`

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

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

If role defined by `ElementInternals`, no `role`.

Otherwise, any `role`

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

[^b^] No corresponding role Any `role`

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

[^base^] No corresponding role No `role` or `aria-*` attributes
[^bdi^] No corresponding role Any `role`

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

[^bdo^] No corresponding role Any `role`

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

[^blockquote^] No corresponding role

Any `role`

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

[^body^] No corresponding role

No `role`

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

[^br^] No corresponding role

Roles: `presentation` or `none`.

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

[^button^] role=button

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

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

[^canvas^] No corresponding role

Any `role`

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

[^caption^] No corresponding role

No `role`

Global `aria-*` attributes

[^cite^] No corresponding role Any `role`

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

[^code^] No corresponding role Any `role`

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

[^col^] No corresponding role No `role` or `aria-*` attributes
[^colgroup^] No corresponding role No `role` or `aria-*` attributes
[^data^] No corresponding role Any `role`

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

[^datalist^] role=listbox

No `role`

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

[^dd^] role=definition

No `role`

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

[^del^] No corresponding role

Any `role`

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

[^dfn^] role=term Any `role`

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

[^details^] role=group

No `role`

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

[^dialog^] role=dialog

Role: `alertdialog`

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

[^div^] No corresponding role

Any `role`

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

[^dl^] No corresponding role

Roles: `group`, `list`, `presentation` or `none`.

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

[^dt^] role=term

Role: `listitem`

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

[^em^] No corresponding role

Any `role`

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

[^embed^] No corresponding role

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

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

[^fieldset^] role=group

Roles: `none`, `presentation` or `radiogroup`.

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

[^figcaption^] No corresponding role

Roles: `group`, `presentation` or `none`.

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

[^figure^] role=figure

If the `figure` has no `figcaption` descendant:
Any `role`

If the `figure` has a `figcaption` descendant:
No `role`.

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

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

Roles: `search`, `none` or `presentation`.

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

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

If role defined by `ElementInternals`, no `role`.

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

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

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

Roles: `none`, `presentation` or `tab`.

DPub Role: `doc-subtitle`

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

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

Roles: `group`, `none` or `presentation`.

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

[^hgroup^] No corresponding role

Any `role`.

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

[^hr^] role=separator

Roles: `none` or `presentation`.

DPub Role: `doc-pagebreak`

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

[^html^] role=document No `role` or `aria-*` attributes
[^i^] No corresponding role

Any `role`

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

[^iframe^] No corresponding role

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

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

[^img^] with [^img/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 [^img/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.

The HTML [^input/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 [^input/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.

The HTML [^input/checked^] attribute can be used instead of the `aria-checked` attribute for the `menuitemradio` role when used on `type=radio`.

`input type=range` role=slider

No `role`

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

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

`input type=reset` role=button

No `role`

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

`input type=submit` role=button

No `role`

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

`input type=tel`, with no [^input/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 [^input/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 [^input/list^] attribute role=combobox

No `role`

Authors SHOULD NOT use the `aria-haspopup` attribute on the indicated `input`s 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 [^input/list^] attribute role=textbox

No `role`

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

`input type=week` No corresponding role

No `role`

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

[^ins^] No corresponding role

Any `role`

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

[^kbd^] No corresponding role

Any `role`

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

[^label^] No corresponding role

No `role`

Global `aria-*` attributes

[^legend^] No corresponding role

No `role`

Global `aria-*` attributes

[^li^] role=listitem

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

DPub Roles: `doc-biblioentry`, `doc-endnote`.

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

[^main^] role=main

No `role`

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

[^map^] No corresponding role No `role` or `aria-*` attributes
`math` role=math

No `role`

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

[^mark^] No corresponding role

Any `role`

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

[^menu^] role=list

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

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

[^meta^] No corresponding role No `role` or `aria-*` attributes
[^meter^] No corresponding role

No `role`

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

Otherwise, any global `aria-*` attributes.

[^nav^] role=navigation

Roles: `menu`, `menubar` or `tablist`.

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

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

[^noscript^] No corresponding role No `role` or `aria-*` attributes
[^object^] No corresponding role

Roles: `application`, `document` or `img`.

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

[^ol^] role=list

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

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

[^optgroup^] role=group

No `role`

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

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

No `role`

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

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

[^output^] role=status

Any `role`

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

[^p^] No corresponding role

Any `role`

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

[^param^] No corresponding role No `role` or `aria-*` attributes
[^picture^] No corresponding role No `role` or `aria-*` attributes
[^pre^] No corresponding role

Any `role`

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

[^progress^] role=progressbar

No `role`

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

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

[^q^] No corresponding role

Any `role`

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

[^rp^] No corresponding role

Any `role`

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

[^rt^] No corresponding role

Any `role`

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

[^ruby^] No corresponding role

Any `role`

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

[^s^] No corresponding role

Any `role`

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

[^samp^] No corresponding role

Any `role`

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

[^script^] No corresponding role No `role` or `aria-*` attributes
[^section^] role=region if the [^section^] element has an accessible name. Otherwise, no corresponding role.

Roles: `alert`, `alertdialog`, `application`, `banner`, `complementary`, `contentinfo`, `dialog`, `document`, `feed`, `log`, `main`, `marquee`, `navigation`, `none`, `note`, `presentation`, `search`, `status` or `tabpanel`

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

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

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

Role: `menu`

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

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

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

No `role`

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

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

[^slot^] No corresponding role No `role` or `aria-*` attributes
[^small^] No corresponding role

Any `role`

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

[^source^] No corresponding role No `role` or `aria-*` attributes
[^span^] No corresponding role

Any `role`

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

[^strong^] No corresponding role

Any `role`

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

[^style^] No corresponding role No `role` or `aria-*` attributes
[^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

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.

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

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 [^input/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 [^input/disabled^] attribute is allowed, including `option` [^option/disabled^] and `optgroup` [^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 [^html-global/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 [^input/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` [^meter/max^], `progress` [^progress/max^], and `input` [^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` [^meter/min^] and `input` [^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` [^input/readonly^], `textarea` [^textarea/readonly^] and form-associated custom element which allows [^form-associated custom elements/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 [^html-global/contenteditable^]`=true` or element without `contenteditable` attribute whose closest ancestor with a `contenteditable` attribute has `contenteditable="true"`.

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` [^input/required^], `textarea` [^textarea/required^], and `select` [^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 [^th/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 [^th/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.

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.

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.

Allowed descendants of ARIA roles

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 [[[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 [[[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=]
  • [=Sectioning content=]
  • [=Palpable content=]
[=Flow content=] but with no main element descendants.
`banner`
  • [=Flow content=]
  • [=Palpable content=]
[=Flow content=] but with no main, header, or footer element descendants.
`button`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
  • [=Palpable content=]
[=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`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
[=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=]
  • [=Phrasing content=]
  • [=Interactive content=]
  • [=Palpable content=]
[=Flow content=] but with no main element descendants.
`complementary`
  • [=Flow content=]
  • [=Sectioning content=]
  • [=Palpable content=]
[=Flow content=] but with no main element descendants.
`contentinfo`
  • [=Flow content=]
  • [=Palpable content=]
[=Flow content=] but with no main, header, or footer element descendants.
`definition`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Palpable content=]
[=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=]
  • [=Palpable content=]
[=Flow content=] but with no main element descendants.
`form`
  • [=Flow content=]
  • [=Palpable content=]
[=Flow content=], but with no [^form^] element descendants.
`grid`
  • [=Flow content=]
  • [=Interactive content=]
  • [=Palpable content=]
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=]
  • [=Palpable content=]
[=Flow content=]
`heading`
  • [=Flow content=]
  • [=Heading content=]
  • [=Palpable content=]
[=Flow content=] but with no main element, [=heading content=], [=sectioning content=], or sectioning roots descendants.
`img`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Embedded content=]
  • [=Palpable content=]
[=Phrasing content=], but with no [=interactive content=] descendants.
`link`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
  • [=Palpable content=]
[=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`
  • [=Flow content=]
  • [=Interactive content=]
  • [=Palpable content=]
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`
  • [=Flow content=]
  • [=Interactive content=]
Refer to the "Required Owned Elements" as defined for the ARIA `menu` role.
`menubar`
  • [=Flow content=]
  • [=Interactive content=]
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=]
  • [=Sectioning content=]
  • [=Palpable content=]
[=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`
  • [=Flow content=]
  • [=Phrasing content=]
[=Phrasing content=], but with no progress element descendants.
`radio`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
[=Phrasing content=], but with no [=interactive content=] descendants, and no descendants with a `tabindex` attribute specified.
`radiogroup`
  • [=Flow content=]
  • [=Palpable content=]
[=Flow content=]
`region`
  • [=Flow content=]
  • [=Sectioning content=]
  • [=Palpable content=]
[=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=]
  • [=Palpable content=]
[=Flow content=] but with no main element descendants.
`searchbox`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
[=Flow content=] but with no main element descendants.
`separator` [=Interactive content=] (if focusable) [=Phrasing content=]
`slider`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
[=Phrasing content=]
`spinbutton`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
[=Flow content=] but with no main element descendants.
`status` [=Flow content=] [=Flow content=] but with no main element descendants.
`switch`
  • [=Flow content=]
  • [=Phrasing content=]
  • [=Interactive content=]
[=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`
  • [=Flow content=]
  • [=Palpable content=]
Refer to the "Required Owned Elements" as defined for the ARIA `table` role.
`tablist`
  • [=Flow content=]
  • [=Palpable content=]
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=]

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 [[[#docconformance]]]. 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.

Privacy and security considerations

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.

Change log

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