ARIA in HTML

Abstract

This specification defines the developer rules (author conformance requirements) for the use of Accessible Rich Internet Applications (WAI-ARIA) 1.1 and Digital Publishing WAI-ARIA Module 1.0 attributes on [HTML] elements. It also defines requirements for Conformance Checking tools.

2. Document conformance requirements for use of ARIA attributes in HTML

The following table provides normative per-element document-conformance requirements for the use of ARIA markup in HTML documents and describes the implicit ARIA semantics that apply to HTML elements as defined in HTML AAM.

Each language feature (element) in a cell in the first column implies the ARIA semantics (role, states, and properties) given in the cell in the second column of the same row. The third cell in each row defines the ARIA role values and aria-* attributes which MAY be used. Where a cell in the third column includes the term Any role it indicates that any role value apart from the implicit ARIA semantics role value, MAY be used. If a cell in the third column includes the term No role it indicates that authors MUST NOT overwrite the implicit ARIA semantics, or native semantics of the HTML element.

Note

While setting an ARIA role and/or aria-* attribute that matches the implicit ARIA semantics is NOT RECOMMENDED, in some situations explicitly setting these attributes can be helpful. For instance, in user agents which lack exposing specific implicit ARIA semantics.

Rules of ARIA attribute usage by HTML element
HTML element	Implicit ARIA semantics (explicitly assigning these in markup is NOT RECOMMENDED)	ARIA roles, states and properties which MAY be used
`a` with `href`	`role=link`	Roles: `button`, `checkbox`, `menuitem`, `menuitemcheckbox`, `menuitemradio`, `option`, `radio`, `switch`, `tab` or `treeitem` DPub Roles: `doc-backlink`, `doc-biblioref`, `doc-glossref` or `doc-noteref` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any). 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 `href`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`abbr`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`address`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`area` with `href`	`role=link`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `link` role.
`area` without `href`	No corresponding role	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`article`	`role=article`	Roles: `application`, `document`, `feed`, `main`, `none`, `presentation` or `region`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`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 no author defined role, Any `role` Otherwise only allowed roles for the role exposed by the custom element's `ElementInternals`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`b`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`bdo`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`blockquote`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`canvas`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`code`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`dfn`	`role=term`	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`dl`	No corresponding role	Roles: `group`, `list`, `presentation` or `none`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`dt`	`role=term`	Role: `listitem` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`em`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`embed`	No corresponding role	Roles: `application`, `document`, `img`, `presentation` or `none`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`fieldset`	`role=group`	Roles: `none`, `presentation` or `radiogroup`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`figcaption`	No corresponding role	Roles: `group`, `presentation` or `none`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`footer`	If not a descendant of an `article`, `aside`, `main`, `nav` or `section` element, or an element with `role=article`, `complementary`, `main`, `navigation` or `region` then `role=contentinfo`. Otherwise no corresponding role.	Roles: `group`, `none` or `presentation`. DPub Roles: `doc-footnote`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed.
`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 and implied role (if any).
form-associated custom element	Role exposed from author defined `ElementInternals`. Otherwise no corresponding role.	If no author defined role, Roles: `application`, `button`, `checkbox`, `combobox`, `group`, `listbox`, `progressbar`, `radio`, `radiogroup`, `searchbox`, `slider`, `spinbutton`, `switch` or `textbox`. Otherwise only allowed roles for the role exposed by the custom element's `ElementInternals`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`h1 to h6`	`role=heading`, with the `aria-level` = positive integer.	Roles: `none`, `presentation` or `tab`. DPub Role: `doc-subtitle` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`hgroup`	No corresponding role	Any `role`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`iframe`	No corresponding role	Roles: `application`, `document`, `img`, `none` or `presentation`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`img` with `alt="some text"`	`role=img`	Roles: `button`, `checkbox`, `link`, `menuitem`, `menuitemcheckbox`, `menuitemradio`, `option`, `progressbar`, `scrollbar`, `separator`, `slider`, `switch`, `tab` or `treeitem` DPub Role: `doc-cover`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`img` with `alt=""`	No corresponding role	*No `role` or `aria-` attributes** except `aria-hidden="true"`.
`img` without `alt` attribute	`role=img`	If no author-defined accessible name is provided by other methods: 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 and implied role (if any).
`input type=checkbox`	`role=checkbox`	Roles: `button` (when used with `aria-pressed`), `menuitemcheckbox`, `option` or `switch`. 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 and implied role (if any). Note: the HTML `checked` attribute can be used instead of the `aria-checked` attribute for `menuitemcheckbox`, `option` or `switch` when used on `type=checkbox`.
`input type=color`	No corresponding role	No `role` Global `aria-*` attributes
`input type=date`	No corresponding role	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`input type=datetime-local`	No corresponding role	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`input type=email` with no `list` attribute	`role=textbox`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`input type=file`	No corresponding role	No `role` Global `aria-*` attributes
`input type=hidden`	No corresponding role	*No `role` or `aria-` attributes**
`input type=image`	`role=button`	Roles: `link`, `menuitem`, `menuitemcheckbox`, `menuitemradio`, `radio` or `switch`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 exposed role. Note: the HTML `checked` attribute can be used instead of the `aria-checked` attribute for `menuitemradio` 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 `aria-` attributes applicable to the `slider` role.
`input type=reset`	`role=button`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `button` role.
`input type=search`, with no `list` attribute	`role=searchbox`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `searchbox` role.
`input type=submit`	`role=button`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `button` role.
`input type=tel`, with no `list` attribute	`role=textbox`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`input type=text` or with a missing or invalid `type`, with no `list` attribute	`role=textbox`	Roles: `combobox`, `searchbox` or `spinbutton`. Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles.
`input type=text`, `search`, `tel`, `url`, `email`, or with a missing or invalid `type`, with a `list` attribute	`role=combobox`	No `role` Authors SHOULD NOT use the `aria-haspopup` attribute on the indicated `input`s with a `list` attribute. Otherwise, any global `aria-` attributes and any `aria-` attributes applicable to the `combobox` role.
`input type=time`	No corresponding role	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`input type=url` with no `list` attribute	`role=textbox`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`input type=week`	No corresponding role	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `textbox` role.
`ins`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`kbd`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`link`	No corresponding role	*No `role` or `aria-` attributes**
`main`	`role=main`	No `role` Global `aria-` attributes and any `aria-` attributes applicable to the `main` role.
`map`	No corresponding role	*No `role` or `aria-` attributes**
`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 and implied role (if any).
`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 and implied role (if any).
`meta`	No corresponding role	*No `role` or `aria-` attributes**
`meter`	No corresponding role	No `role` 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 and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`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 `aria-` attributes applicable to the `option` role.
`output`	`role=status`	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`p`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`progress`	`role=progressbar`	No `role` Global `aria-` attributes and any `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 and implied role (if any).
`rp`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`rt`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`ruby`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`s`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`samp`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`strong`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`sub`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`table`	`role=table`	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`tbody`	`role=rowgroup`	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).
`thead`	`role=rowgroup`	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`time`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 `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 and implied role (if any).
`th`	If the ancestor `table` element is exposed as a `role=table`: `role=columnheader`, `rowheader` or `cell` according to HTML AAM. If the ancestor `table` element is exposed as a `role=grid` or `treegrid`: `role=columnheader`, `rowheader` or `gridcell` according to HTML AAM.	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 and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`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 and implied role (if any).
`var`	No corresponding role	Any `role` Global `aria-` attributes and any `aria-` attributes applicable to the allowed roles and implied role (if any).
`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 and implied role (if any).

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 developers add a role attribute to a semantically neutral element such as a div or span, rather than overriding the semantics of the listed elements.

Note

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

Using ARIA - A practical guide for developers on how to add accessibility information to HTML elements using the Accessible Rich Internet Applications specification (ARIA 1.1).
WAI-ARIA Authoring Practices 1.2 - An author's guide to understanding and implementing Accessible Rich Internet Applications.

Example 6

These features can be used to make accessibility tools render content to their users in more useful ways. For example, ASCII art, which is really an image, appears to be text, and in the absence of appropriate roles and properties would end up being rendered by screen readers as a nonsensical string of punctuation characters. Using the features described in this section, one can instead make the ATs skip the ASCII art and just read the caption:

<figure>
  <pre role="img" aria-label="ASCII Fish">
  o           .'`/
    '      /  (
  O    .-'` ` `'-._      .')
      _/ (o)        '.  .' /
      )       )))     ><  <
      `\  |_\      _.'  '. \
        '-._  _ .-'       '.)
    jgs     `\__\
  </pre>
  <figcaption id="fish-caption">
    Joan G. Stark, "<cite>fish</cite>".
    October 1997. ASCII on electrons. 28×8.
  </figcaption>
</figure>

Document conformance requirements for use of ARIA attributes with HTML attributes

Unless otherwise stated, authors MAY use aria-* attributes in place of their HTML equivalents on HTML elements where the aria-* semantics would be expected. For example, authors MAY use aria-disabled=true on a button element, rather than the disabled attribute. However, authors SHOULD NOT use both the native HTML attribute and the aria-* attribute together, and MUST NOT use the these features together when their values are in opposition to each other. As stated in WAI-ARIA's Conflicts with Host Language Semantics, user agents MUST ignore WAI-ARIA attributes and use the host language (HTML) attribute with the same implicit ARIA semantics.

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

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

Rules of ARIA attribute usage by HTML feature
HTML feature	Implicit ARIA semantics	HTML feature and `aria-*` attribute author guidance
Any element where the `checked` attribute is allowed	`aria-checked="true"`	Use the `checked` attribute on any element that is allowed the `checked` attribute in HTML. Authors SHOULD NOT use the `aria-checked` attribute on any element where the checkedness of the element can be in opposition to the current value of the `aria-checked` attribute. Authors MAY use the `aria-checked` attribute on any other element with a WAI-ARIA role which allows the attribute.
Any element where the `disabled` attribute is allowed	`aria-disabled="true"`	Use the `disabled` attribute on any element that is allowed the `disabled` attribute in HTML. Authors MAY use the `aria-disabled` attribute on any element that is allowed the `disabled` attribute in HTML, or any element with a WAI-ARIA role which allows the `aria-disabled` attribute. Authors SHOULD NOT use `aria-disabled="true"` on any element which also has a `disabled` attribute. Authors MUST NOT use `aria-disabled="false"` on any element which also has a `disabled` attribute.
Any element with a `hidden` attribute	`aria-hidden="true"`	Authors MAY use the `aria-hidden` attribute on any HTML element that allows global `aria-` attributes, with the following exceptions: Authors SHOULD NOT* use the `aria-hidden="true"` attribute on any element which also has a `hidden` attribute.
Any element where the `placeholder` attribute is allowed	`aria-placeholder="..."`	Use the `placeholder` attribute on any element that is allowed the `placeholder` attribute in HTML. Authors MAY use the `aria-placeholder` attribute on any element that is allowed the `placeholder` attribute in HTML, or any element with a WAI-ARIA role which allows the `aria-placeholder` attribute. Authors MUST NOT use the `aria-placeholder` attribute on any element which also has a `placeholder` attribute.
Any element where the `max` attribute is allowed	`aria-valuemax="..."`	Use the `max` attribute on any element that is allowed the `max` attribute in HTML. It is NOT RECOMMENDED to use the `aria-valuemax` attribute on these elements. 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 also has a `max` attribute, even if the values of each attribute match. Authors MUST NOT use `aria-valuemax` on any element which also has a `max` attribute, and the values of each attribute do not match.
Any element where the `min` attribute is allowed	`aria-valuemin="..."`	Use the `min` attribute on any element that is allowed the `min` attribute in HTML. It is NOT RECOMMENDED to use the `aria-valuemin` attribute on these elements. 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 also has a `min` attribute, even if the values of each attribute match. Authors MUST NOT use `aria-valuemin` on any element which also has a `min` attribute, and the values of each attribute do not match.
Any element where the `readonly` attribute is allowed	`aria-readonly="true"`	Use the `readonly` attribute on any element that is allowed the `readonly` attribute in HTML. It is NOT RECOMMENDED to use `aria-readonly` on these elements. Authors MAY use the `aria-readonly` attribute on any element with a WAI-ARIA role which allows the `aria-readonly` attribute. Authors SHOULD NOT use the `aria-readonly="true"` on any element which also has a `readonly` attribute. Authors MUST NOT use `aria-readonly="false"` on any element which also has a `readonly` attribute.
Element with `contenteditable="true"`; or Element without `contenteditable` attribute whose closest ancestor with a `contenteditable` attribute has `contenteditable="true"`. Note: this is equivalent to the `isContentEditable` IDL attribute.	`aria-readonly="false"`	Authors MUST NOT set `aria-readonly="true"` on an element that has `isContentEditable="true"`.
Any element where the `required` attribute is allowed	`aria-required="true"`	Use the `required` attribute on any element that is allowed the `required` attribute in HTML. Authors MAY use the `aria-required` attribute on any element that is allowed the `required` attribute in HTML, or any element with a WAI-ARIA role which allows the `aria-required` attribute. Authors SHOULD NOT use the `aria-required="true"` on any element which also has a `required` attribute. Authors MUST NOT use `aria-required="false"` on any element which also has a `required` attribute.
Any element where the `colspan` attribute is allowed	`aria-colspan="..."`	Use the `colspan` attribute on any element that is allowed the `colspan` attribute in HTML. Authors MAY use the `aria-colspan` attribute on any element that is allowed the `colspan` attribute in HTML, or any element with a WAI-ARIA role which allows the `aria-colspan` attribute. Authors SHOULD NOT use the `aria-colspan` attribute on any element which also has a `colspan` attribute. Authors MUST NOT use `aria-colspan` on any element which also has a `colspan` attribute, and the values of each attribute do not match.
Any element where the `rowspan` attribute is allowed	`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.

4. Allowed ARIA roles, states and properties

Columns 1 to 4 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 Accessible Rich Internet Applications (WAI-ARIA) 1.1 specification. Links to ARIA roles, states and properties in the table reference the normative Accessible Rich Internet Applications (WAI-ARIA) 1.1 definitions.

Column 5 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 6 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 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>

ARIA Roles, States and Properties
Role	Description	Required Properties	Supported Properties	Kind of content	Descendant restrictions
any	ARIA global states and properties can be used on any HTML element.	none	`aria-atomic` `aria-busy` (state) `aria-controls` `aria-current` (state) `aria-describedby` `aria-details` `aria-disabled` (state) `aria-dropeffect` `aria-errormessage` `aria-flowto` `aria-grabbed` (state) `aria-haspopup` `aria-hidden` (state) `aria-invalid` (state) `aria-keyshortcuts` `aria-label` `aria-labelledby` `aria-live` `aria-owns` `aria-relevant` `aria-roledescription`	n/a	n/a
`alert`	A type of live region with important, and usually time-sensitive, information. See related `alertdialog` and `status`.	none	`aria-expanded` (state)	Flow content	Flow content
`alertdialog`	A type of dialog that contains an alert message, where initial focus goes to an element within the dialog. See related `alert` and `dialog`.	none	`aria-expanded` (state) `aria-modal`	Flow content	Flow content
`application`	A structure containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by a widget role.	none	`aria-activedescendant` `aria-expanded` (state)	Flow content	Flow content
`article`	A section of a page that consists of a composition that forms an independent part of a document, page, or site.	none	`aria-expanded` (state)	Flow content	No main element descendants.
`banner`	A region that contains mostly site-oriented content, rather than page-specific content.	none	`aria-expanded` (state)	Document region	no main element descendants, or header, footer elements that are not descendants of sectioning content which is a descendant of the header.
`button`	An input that allows for user-triggered actions when clicked or pressed. See related `link`.	none	`aria-expanded` (state) `aria-pressed` (state)	Interactive content	Phrasing content, but there must be no interactive content descendant.
`checkbox`	A checkable input that has three possible values: true, false, or mixed.	`aria-checked` (state)	`aria-readonly`	Interactive content	Phrasing content, but there must be no interactive content descendant.
`cell`	A cell in a tabular container.	none	`aria-colspan` `aria-colindex` `aria-rowindex` `aria-rowspan`	Flow content	Flow content
`columnheader`	A cell containing header information for a column.	none	`aria-sort` `aria-readonly` `aria-required` `aria-selected` (state) `aria-expanded` (state) `aria-colspan` `aria-colindex` `aria-rowindex` `aria-rowspan`	Flow content	Flow content
`combobox`	A presentation of a select; usually similar to a textbox where users can type ahead to select an option, or type to enter arbitrary text as a new item in the list. See related `listbox`.	`aria-controls` `aria-expanded` (state)	`aria-autocomplete` `aria-required` `aria-activedescendant` `aria-orientation`	Interactive content	Flow content
`complementary`	A supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.	none	`aria-expanded` (state)	Flow content	Flow content, but with no main element descendants.
`contentinfo`	A large perceivable region that contains information about the parent document.	none	`aria-expanded` (state)	Flow content	Flow content, but with no main element descendants, or header, footer elements that are not descendants of sectioning content which is a descendant of the header.
`definition`	A definition of a term or concept.	none	`aria-expanded` (state)	Phrasing content	Phrasing content
`dialog`	A dialog is an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. See related `alertdialog`.	none	`aria-expanded` (state) `aria-modal`	Flow content	Flow content
`directory`	A list of references to members of a group, such as a static table of contents.	none	`aria-expanded` (state)	Flow content	Flow content
`document`	A region containing related information that is declared as document content, as opposed to a web application.	none	`aria-expanded` (state)	Flow content	Flow content
`feed`	A scrollable list of articles where scrolling may cause articles to be added to or removed from either end of the list.	none	`aria-expanded` (state)	Flow content	Flow content
`figure`	A perceivable section of content that typically contains a graphical document, images, code snippets, or example text.	none	`aria-expanded` (state)	Flow content	Flow content
`form`	A landmark region that contains a collection of items and objects that, as a whole, combine to create a form. See related `search`.	none	`aria-expanded` (state)	Flow content	Flow content
`grid`	A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table.	none	`aria-level` `aria-multiselectable` `aria-readonly` `aria-activedescendant` `aria-expanded` (state) `aria-colcount` `aria-rowcount`	Flow content Interactive content	Flow content
`gridcell`	A cell in a `grid` or `treegrid`.	none	`aria-readonly` `aria-required` `aria-selected` (state) `aria-expanded` (state) `aria-colindex` `aria-colspan` `aria-rowindex` `aria-rowspan`	Flow content Interactive content	Flow content
`group`	A set of user interface objects which are not intended to be included in a page summary or table of contents by assistive technologies.	none	`aria-activedescendant` `aria-expanded` (state)	Flow content	Flow content
`heading`	A heading for a section of the page.	none	`aria-level` `aria-expanded` (state)	Heading content	Flow content, but with no Heading content, Sectioning content, Sectioning roots.
`img`	A container for a collection of elements that form an image.	none	`aria-expanded` (state)	Flow content	Phrasing content
`link`	An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See related `button`.	none	`aria-expanded` (state)	Flow content	Flow content, but with no interactive content or a element descendants.
`list`	A group of non-interactive list items. See related `listbox`.	none	`aria-expanded` (state)	Flow content	Flow content
`listbox`	A widget that allows the user to select one or more items from a list of choices. See related `combobox` and `list`.	none	`aria-required` `aria-multiselectable` `aria-expanded` (state) `aria-activedescendant` `aria-orientation`	Flow content Interactive content	Flow content
`listitem`	A single item in a `list` or `directory`.	none	`aria-level` `aria-posinset` `aria-setsize` `aria-expanded` (state)	Flow content	Flow content
`log`	A type of live region where new information is added in meaningful order and old information may disappear. See related `marquee`.	none	`aria-expanded` (state)	Flow content	Flow content
`main`	The main content of a document.	none	`aria-expanded` (state)	Flow content	Flow content, but with no main element descendants
`marquee`	A type of live region where non-essential information changes frequently. See related `log`.	none	`aria-expanded` (state)	Flow content	Flow content
`math`	Content that represents a mathematical expression.	none	`aria-expanded` (state)	Flow content	Flow content
`menu`	A type of widget that offers a list of choices to the user.	none	`aria-expanded` (state) `aria-activedescendant` `aria-orientation`	Flow content Interactive content	Flow content
`menubar`	A presentation of menu that usually remains visible and is usually presented horizontally.	none	`aria-expanded` (state) `aria-activedescendant` `aria-orientation`	Flow content Interactive content	Flow content
`menuitem`	An option in a group of choices contained by a `menu` or `menubar`.	none	`aria-posinset` `aria-setsize`	Interactive content	Flow content, but with no interactive content descendants.
`menuitemcheckbox`	A checkable menuitem that has three possible values: true, false, or mixed.	`aria-checked` (state)	`aria-posinset` `aria-setsize`	Interactive content	Phrasing content, but with no interactive content descendants.
`menuitemradio`	A checkable `menuitem` in a group of `menuitemradio` roles, only one of which can be checked at a time.	`aria-checked` (state)	`aria-posinset` `aria-setsize`	Interactive content	Phrasing content, but with no interactive content descendants.
`navigation`	A collection of navigational elements (usually links) for navigating the document or related documents.	none	`aria-expanded` (state)	Flow content	Flow content, but with no main element descendants
`none`	An element whose implicit native role semantics will not be mapped to the accessibility API. See synonym `presentation`	none		Flow content	Flow content
`note`	A section whose content is parenthetic or ancillary to the main content of the resource.	none	`aria-expanded` (state)	Flow content	Flow content
`option`	A selectable item in a select list.	none	`aria-checked` (state) `aria-posinset` `aria-selected` (state) `aria-setsize`	Interactive content	Phrasing content, but with no interactive content descendants.
`presentation`	An element whose implicit native role semantics will not be mapped to the accessibility API.	none		Flow content	Flow content
`progressbar`	An element that displays the progress status for tasks that take a long time.	none	`aria-valuemax` `aria-valuemin` `aria-valuenow` `aria-valuetext`	Flow content	Phrasing content
`radio`	A checkable input in a group of radio roles, only one of which can be checked at a time.	`aria-checked` (state)	`aria-posinset` `aria-selected` (state) `aria-setsize`	Interactive content	Phrasing content, but with no interactive content descendants.
`radiogroup`	A group of radio buttons.	none	`aria-required` `aria-activedescendant` `aria-expanded` (state) `aria-orientation`	Flow content	Flow content
`region`	A large perceivable section of a web page or document, that the author feels is important enough to be included in a page summary or table of contents, for example, an area of the page containing live sporting event statistics.	none	`aria-expanded` (state)	Flow content	Flow content
`row`	A row of cells in a tabular container.	none	If child of `role=grid`, `rowgroup`, `table` or `treegrid`: `aria-colindex` `aria-rowindex` `aria-selected` (state) `aria-activedescendant` Also, if child of `role=treegrid`: `aria-expanded` (state) `aria-level` `aria-posinset` `aria-setsize`	none	Flow content
`rowgroup`	A group containing one or more row elements in a grid.	none		none	Flow content
`rowheader`	A cell containing header information for a row in a grid.	none	`aria-readonly` `aria-required` `aria-selected` (state) `aria-expanded` (state) `aria-colspan` `aria-colindex` `aria-rowindex` `aria-rowspan`	none	Flow content
`scrollbar`	A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.	`aria-controls` `aria-orientation` `aria-valuemax` `aria-valuemin` `aria-valuenow`	`aria-expanded` (state) `aria-valuetext`	Flow content Interactive content	Phrasing content
`search`	A landmark region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related `form`.	none	`aria-expanded` (state)	Flow content	Flow content
`searchbox`	A type of textbox intended for specifying search criteria.	none	`aria-activedescendant` `aria-autocomplete` `aria-multiline` `aria-placeholder` `aria-readonly` `aria-required`	Interactive content	Flow content, but with no interactive content descendants.
`separator`	A divider that separates and distinguishes sections of content or groups of menuitems.	`aria-valuemax` (if focusable) `aria-valuemin` (if focusable) `aria-valuenow` (if focusable)	`aria-valuetext` (if focusable) `aria-orientation`	Interactive content (if focusable)	Phrasing content
`slider`	A user input where the user selects a value from within a given range.	`aria-valuemax` `aria-valuemin` `aria-valuenow`	`aria-orientation` `aria-valuetext`	Interactive content	Phrasing content
`spinbutton`	A form of range that expects the user to select from among discrete choices.	`aria-valuemax` `aria-valuemin` `aria-valuenow`	`aria-required` `aria-readonly` `aria-valuetext`	Flow content Interactive content	Flow content
`status`	A container whose content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar. See related `alert`.	none	`aria-expanded` (state)	Flow content	Flow content
`switch`	A type of checkbox that represents on/off values, as opposed to checked/unchecked values.	`aria-checked` (state)	`aria-readonly`	Interactive content	Phrasing content, but with no interactive content descendants.
`tab`	A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.	none	`aria-selected` (state) `aria-posinset` `aria-setsize` `aria-expanded` (state)	interactive content	Phrasing content, but with no interactive content descendants.
`table`	A section containing data arranged in rows and columns. The table role is intended for tabular containers which are not interactive.	none	`aria-colcount` `aria-rowcount`	Flow content	Flow content
`tablist`	A list of `tab` elements, which are references to `tabpanel` elements.	none	`aria-level` `aria-activedescendant` `aria-orientation` `aria-multiselectable`	Flow content	Flow content
`tabpanel`	A container for the resources associated with a `tab`, where each `tab` is contained in a `tablist`.	none	`aria-expanded` (state)	Flow content	Flow content
`term`	A word or phrase with a corresponding definition. See related `definition`.	none	`aria-expanded` (state)	Phrasing content	Phrasing content
`textbox`	Input that allows free-form text as its value.	none	`aria-activedescendant` `aria-autocomplete` `aria-multiline` `aria-placeholder` `aria-readonly` `aria-required`	Interactive content	Flow content, but with no interactive content descendants.
`timer`	A type of live region containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.	none	`aria-expanded` (state)	Flow content	Flow content
`toolbar`	A collection of commonly used function buttons represented in compact visual form.	none	`aria-activedescendant` `aria-expanded` (state) `aria-orientation`	Flow content	Flow content
`tooltip`	A contextual pop-up that displays a description for an element.	none	`aria-expanded` (state)	Flow content	Flow content
`tree`	A type of list that may contain sub-level nested groups that can be collapsed and expanded.	none	`aria-multiselectable` `aria-required` `aria-activedescendant` `aria-expanded` (state) `aria-orientation`	Flow content	Flow content
`treegrid`	A grid whose rows can be expanded and collapsed in the same manner as for a tree.	none	`aria-level` `aria-multiselectable` `aria-readonly` `aria-activedescendant` `aria-expanded` (state) `aria-required` `aria-orientation` `aria-colcount` `aria-rowcount`	Flow content	Flow content
`treeitem`	An option item of a tree. This is an element within a tree that may be expanded or collapsed if it contains a sub-level group of treeitems.	none	`aria-level` `aria-posinset` `aria-setsize` `aria-expanded` (state) `aria-checked` (state) `aria-selected` (state)	Interactive content	Flow content

ARIA in HTML

W3C Working Draft 07 March 2021

Abstract

Status of This Document

1. Developer requirements for use of ARIA in HTML

2. Document conformance requirements for use of ARIA attributes in HTML

Document conformance requirements for use of ARIA attributes with HTML attributes

3. Case requirements for ARIA role, state and property attributes

4. Allowed ARIA roles, states and properties

5. Conformance

A. References

A.1 Normative references

A.2 Informative references