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. This is unnecessary, because the `fieldset` element is implicitly exposed as a `role=group`. Again, in practice this will likely not have any unforeseen side effects.

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

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

          <!-- 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^] role=document

No `role`

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

[^br^] No corresponding role

Roles: `presentation` or `none`.

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

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

Any `role`

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

[^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
`SVG` `role=graphics-document` as defined by SVG AAM

Any Role

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

[^sub^] No corresponding role

Any `role`

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

[^summary^] role=button

No `role`

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

[^sup^] No corresponding role

Any `role`

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

[^table^] role=table

Any `role`

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

[^tbody^] role=rowgroup

Any `role`

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

[^template^] No corresponding role No `role` or `aria-*` attributes
[^textarea^] role=textbox

No `role`

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

[^tfoot^] role=rowgroup

Any `role`

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

[^thead^] role=rowgroup

Any `role`

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

[^time^] No corresponding role

Any `role`

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

[^title^] No corresponding role No `role` or `aria-*` attributes
[^td^]

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

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

No corresponding role if the ancestor `table` element is not exposed as a `role=table`, `grid` or `treegrid`.

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

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

[^th^]

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

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

No corresponding role if the ancestor `table` element is not exposed as a `role=table`, `grid` or `treegrid`.

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

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

[^tr^] role=row

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

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

[^track^] No corresponding role No `role` or `aria-*` attributes
[^u^] No corresponding role

Any `role`

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

[^ul^] role=list

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

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

[^var^] No corresponding role

Any `role`

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

[^video^] No corresponding role

Role: `application`

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

[^wbr^] No corresponding role

Any `role`

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

The elements marked with No corresponding role, in the second column of the table do not have any implicit ARIA semantics, but they do have meaning and this meaning may be represented in roles, states and properties not provided by ARIA, and exposed to users of assistive technology via accessibility APIs. It is therefore recommended that authors add a `role` attribute to a semantically neutral element such as a [^div^] or [^span^], rather than overriding the semantics of the listed elements.

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 use `aria-disabled=true` on a [^button^] element, rather than the `disabled` attribute. However, authors SHOULD NOT use both the native HTML attribute and the `aria-*` attribute together, and MUST NOT use the these features together when their values are in opposition to each other. As stated in WAI-ARIA's Conflicts with Host Language Semantics, user agents MUST ignore WAI-ARIA attributes and use the host language (HTML) attribute with the same implicit ARIA semantics.

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

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

Rules of ARIA attribute usage by HTML feature
HTML feature

Implicit ARIA semantics

HTML feature and `aria-*` attribute author guidance
Any element where the [^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 attribute.

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

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

Any element where the `min` attribute is allowed: `meter` [^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 attribute.

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

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

Any element which allows the `readonly` attribute: `input` [^input/readonly^], `textarea` [^textarea/readonly^] and form-associated custom element which allows the [^face/readonly^] `aria-readonly="true"`

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

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

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

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

Element with [^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 MAY use the `aria-colspan` attribute on any element that is allowed the `colspan` attribute in HTML, or any element with a WAI-ARIA role which allows the `aria-colspan` attribute.

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

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

Any element where the [^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 MAY use the `aria-rowspan` attribute on any element that is allowed the `rowspan` attribute in HTML, or any element with a WAI-ARIA role which allows the `aria-rowspan` attribute.

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

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

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

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

Case requirements for ARIA role, state and property attributes

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

Allowed ARIA roles, states and properties

Columns 1 to 3 of the ARIA Roles, States and Properties table provide an informative (non-normative) reference to the ARIA roles, states and properties permitted for use in HTML. All ARIA roles, states and properties are normatively defined in the [[[wai-aria-1.1]]] specification. Links to ARIA roles, states and properties in the table reference the normative [[[wai-aria-1.1]]] definitions.

Column 4 of the ARIA Roles, States and Properties table defines extensions to the Kinds of content (defined in the [[HTML]] specification) categories each `role` has when it is used on a HTML element. Column 5 defines what HTML elements can be descendants of an element with a particular implicit or explicit `role` value.

For example, a [^button^] element has an implicit `role=button`. A `button` element allows [=phrasing content=] as descendants and does not allow [=interactive content=] or descendants with a `tabindex` attribute. Therefore, any elements specified with a `role=button` also MUST NOT allow any interactive content descendants, elements with a `tabindex` specified or any elements with role values that are in the interactive content category (identified in Column 4).

Examples of non-conforming descendants
<!-- conformance checkers will report an error -->
<button>
  <div role="button">...</div>
</button>

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

<div role="link">
  <textarea>...</textarea>
</div>
        
ARIA Roles, States and Properties
Role Required Properties Supported Properties Kind of content Descendant restrictions
any none Not applicable Not applicable
`alert` none `aria-expanded` [=Flow content=] [=Flow content=]
`alertdialog` none [=Flow content=] [=Flow content=]
`application` none [=Flow content=] [=Flow content=]
`article` none

`aria-expanded`

[=Flow content=] No main element descendants.
`banner` none `aria-expanded` Document region No main, header or footer element descendants.
`button` none [=Interactive content=] [=Phrasing content=], but there must be no [=interactive content=] descendant.
`checkbox` `aria-checked` `aria-readonly` [=Interactive content=] [=Phrasing content=], but there must be no [=interactive content=] descendant.
`cell` none [=Flow content=] [=Flow content=]
`columnheader` none [=Flow content=] [=Flow content=]
`combobox` [=Interactive content=] [=Flow content=]
`complementary` none `aria-expanded` [=Flow content=] [=Flow content=], but with no main element descendants.
`contentinfo` none `aria-expanded` [=Flow content=] [=Flow content=], but with no main, header or footer element descendants.
`definition` none

`aria-expanded`

[=Phrasing content=] [=Phrasing content=]
`dialog` none [=Flow content=] [=Flow content=]
`directory` none `aria-expanded` [=Flow content=] [=Flow content=]
`document` none `aria-expanded` [=Flow content=] [=Flow content=]
`feed` none `aria-expanded` [=Flow content=] [=Flow content=]
`figure` none `aria-expanded` [=Flow content=] [=Flow content=]
`form` none `aria-expanded` [=Flow content=] [=Flow content=]
`grid` none

[=Flow content=]

[=Interactive content=]

[=Flow content=]
`gridcell` none

[=Flow content=]

[=Interactive content=]

[=Flow content=]
`group` none [=Flow content=] [=Flow content=]
`heading` none [=Heading content=] [=Flow content=], but with no [=Heading content=], [=Sectioning content=], or Sectioning roots.
`img` none `aria-expanded` [=Flow content=] [=Phrasing content=]
`link` none `aria-expanded` [=Flow content=] [=Flow content=], but with no [=interactive content=] or a element descendants.
`list` none `aria-expanded` [=Flow content=] [=Flow content=]
`listbox` none

[=Flow content=]

[=Interactive content=]

[=Flow content=]
`listitem` none [=Flow content=] [=Flow content=]
`log` none `aria-expanded` [=Flow content=] [=Flow content=]
`main` none `aria-expanded` [=Flow content=] [=Flow content=], but with no main element descendants.
`marquee` none `aria-expanded` [=Flow content=] [=Flow content=]
`math` none `aria-expanded` [=Flow content=] [=Flow content=]
`menu` none

[=Flow content=]

[=Interactive content=]

[=Flow content=]
`menubar` none

[=Flow content=]

[=Interactive content=]

[=Flow content=]
`menuitem` none [=Interactive content=] [=Flow content=], but with no [=interactive content=] descendants.
`menuitemcheckbox` `aria-checked` [=Interactive content=] [=Phrasing content=], but with no [=interactive content=] descendants.
`menuitemradio` `aria-checked` [=Interactive content=] [=Phrasing content=], but with no [=interactive content=] descendants.
`navigation` none `aria-expanded` [=Flow content=] [=Flow content=], but with no main element descendants.
`none` none   [=Flow content=] [=Flow content=]
`note` none `aria-expanded` [=Flow content=] [=Flow content=]
`option` none [=Interactive content=] [=Phrasing content=], but with no [=interactive content=] descendants.
`presentation` none [=Flow content=] [=Flow content=]
`progressbar` none [=Flow content=] [=Phrasing content=]
`radio` `aria-checked` [=Interactive content=] [=Phrasing content=], but with no [=interactive content=] descendants.
`radiogroup` none [=Flow content=] [=Flow content=]
`region` none `aria-expanded` [=Flow content=] [=Flow content=]
`row` none

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

Also, if child of `role=treegrid`:

none [=Flow content=]
`rowgroup` none none [=Flow content=]
`rowheader` none none [=Flow content=]
`scrollbar`

[=Flow content=]

[=Interactive content=]

[=Phrasing content=]
`search` none `aria-expanded` [=Flow content=] [=Flow content=]
`searchbox` none [=Interactive content=] [=Flow content=], but with no [=interactive content=] descendants.
`separator` [=Interactive content=] (if focusable) [=Phrasing content=]
`slider` [=Interactive content=] [=Phrasing content=]
`spinbutton`

[=Flow content=]

[=Interactive content=]

[=Flow content=]
`status` none `aria-expanded` [=Flow content=] [=Flow content=]
`switch` `aria-checked` `aria-readonly` [=Interactive content=] [=Phrasing content=], but with no [=interactive content=] descendants.
`tab` none [=interactive content=] [=Phrasing content=], but with no [=interactive content=] descendants.
`table` none [=Flow content=] [=Flow content=]
`tablist` none [=Flow content=] [=Flow content=]
`tabpanel` none

`aria-expanded`

[=Flow content=] [=Flow content=]
`term` none `aria-expanded` [=Phrasing content=] [=Phrasing content=]
`textbox` none [=Interactive content=] [=Flow content=], but with no [=interactive content=] descendants.
`timer` none `aria-expanded` [=Flow content=] [=Flow content=]
`toolbar` none [=Flow content=] [=Flow content=]
`tooltip` none `aria-expanded` [=Flow content=] [=Flow content=]
tree none [=Flow content=] [=Flow content=]
`treegrid` none [=Flow content=] [=Flow content=]
`treeitem` none [=Interactive content=] [=Flow content=]

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. 07-Mar-2021: Update allowed roles for `nav` element. Adds `menu`, `menubar` and `tablist` as allowed roles
  2. 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`
  3. 19-Feb-2021: Allow any role on `svg`
  4. 19-Feb-2021: `aria-disabled` not recommended on `a` with `href`
  5. 13-Feb-2021: Clarify custom element role allowances
  6. 13-Feb-2021: Update allowed children for roles with child presentational
  7. 25-Nov-2020: No allowed roles for `img` with `alt=""`
  8. 15-Feb-2020: Update allowances for `figure` element
  9. 15-Feb-2020: Limits allowed roles on `img alt="some text"`
  10. 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.
  11. 19-Dec-2019: Adds form-associated custom element
  12. 06-Dec-2019: Adds `br` element. Allows `role=presentation` or `none`
  13. 18-Oct-2019: Specify author requirements for "No Role"
  14. 08-Oct-2019: Allow `role=doc-epigraph` on `section` element
  15. 30-Sep-2019: Allow `role=doc-dedication` on `aside` element
  16. 29-Sep-2019: Adds `menu` and autonomous custom element
  17. 28-Sep-2019: Allow `role=note` on `section` element
  18. 27-Jul-2019: Allow `role=radiogroup` on `fieldset` element
  19. 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
  20. 24-Mar-2019: Adds `data` element
  21. 08-Jul-2018: Allow `role=none` and `presentation` on `iframe` element
  22. 26-Jun-2018: Allow `role=combobox` and `spinbutton` on `input type=text`
  23. 14-Apr-2018: Adds `abbr` element
  24. 01-Oct-2017: Clarify rules for use of `aria-invalid`
  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