Abstract

This specification defines the web developer rules (author conformance requirements) for the use of [wai-aria-1.1] attributes on [HTML51] elements. It also defines requirements for Conformance Checking tools.

Status of This Document

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

ARIA in HTML is a [HTML51] 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 [HTML51] specification.

Note

Feedback and bug reports are welcome. File a bug.

This is a draft document and its contents are subject to change without notice.

This document was published by the Web Platform Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-html@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

1. Web developer requirements for use of ARIA in HTML

Web developers MAY use the ARIA role and aria-* attributes on HTML elements, in accordance with the requirements described in [wai-aria-1.1], except where these conflict with the strong native semantics or are equal to the default implicit ARIA semantics of a given HTML element. These constraints, are intended to prevent developers from making assistive technology products report nonsensical user interface information (UI) that does not represent the actual UI of the document.

Web developers MUST NOT use the ARIA role and aria-* attributes in a manner that conflicts with the semantics described in the Document conformance requirements for use of ARIA attributes in HTML table. Web developers SHOULD NOT set the ARIA role and aria-* attributes to values that match the default implicit ARIA semantics defined in the table.

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>
      

If you check this file using a HTML5 conformance checker an error will be displayed.

non conforming ARIA use example:

2. Default Implicit ARIA Semantics

The following table describes the default implicit ARIA semantics that apply to HTML elements as defined in the HTML Accessibility API Mappings specification. Each language feature (element or attribute) in a cell in the first column implies the ARIA semantics (any role, states, and properties) given in the cell in the second column of the same row.

Note

Setting an ARIA role and/or aria-* attribute that matches the default implicit ARIA semantics is unnecessary and is NOT RECOMMENDED as these properties are already set by the browser.

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

The following table provides normative per-element document-conformance requirements for the use of ARIA markup in HTML documents.

Rules of ARIA attributes usage by HTML language feature
HTML language feature Default Implicit ARIA semantics - SHOULD NOT be used ARIA roles, states and properties which MAY be used
a element with a href role=link

Roles: button, checkbox, menuitem, menuitemcheckbox, menuitemradio, radio, tab, switch or treeitem

global aria-* attributes and any aria-* attributes applicable to the allowed roles and the link role

a element without a href No corresponding role

Any role

global aria-* attributes and any aria-* attributes applicable allowed roles

address No corresponding role

Role: contentinfo
global aria-* attributes

area with a href role=link

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

article role=article

Roles: presentation, document, application, main or region.
global aria-* attributes and any aria-* attributes applicable to the allowed roles

aside role=complementary

Roles: note, region or search.

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.

base No corresponding role No role or aria* attributes
body role=document global aria-* attributes
button role=button

Roles: checkbox, link, menuitem, menuitemcheckbox, menuitemradio, radio, or switch
global aria-* attributes and any aria-* attributes applicable to the allowed roles

button type="menu" role=button

Roles: link, menuitem, menuitemcheckbox, menuitemradio, radio.
global aria-* attributes and any aria-* attributes applicable to the allowed roles

caption No corresponding role global aria-* attributes

col, colgroup

No corresponding role No role or aria* attributes
datalist role=listbox

global aria-* attributes and any aria-* attributes applicable to thelistbox role.

dd, dt No corresponding role global aria-* attributes
details role=group 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 role

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

dl role=list

global aria-* attributes

embed No corresponding role

Role: application, document, presentation or img

global aria-* attributes and any aria-* attributes applicable to the allowed roles

fieldset No corresponding role

Roles: group or presentation

global aria-* attributes and any aria-* attributes applicable to the allowed roles

figure No corresponding role

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

form role=form

Role: search or presentation

global aria-* attributes and any aria-* attributes applicable to the allowed roles

grouping content elements not listed elsewhere:

p, pre, blockquote

No corresponding role

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

h1 to h6 element role=heading, with the aria-level = positive integer Role: tab or presentation

global aria-* attributes and any aria-* attributes applicable to the allowed roles

hr role=separator global aria-* attributes and any aria-* attributes applicable to the separator role.
html No corresponding role No role or aria* attributes
iframe No corresponding role

Role: application, document, or img

globalaria-* attributes and any aria-* attributes applicable to the allowed roles

iframe (seamless) No corresponding role

Role: application, document, or img

global aria-* attributes and any aria-* attributes applicable to the allowed roles

img with alt="" No corresponding role

Role: presentation

No aria* attributes

img role=img

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

input type= button role=button

Role: link, menuitem, menuitemcheckbox, menuitemradio, radio or switch

global aria-* attributes and any aria-* attributes applicable to the allowed roles

input type= checkbox

role=checkbox

Role: button (when used in conjunction with aria-pressed), menuitemcheckbox or switch

global aria-* attributes and any aria-* attributes applicable to the allowed roles

input type = color No corresponding role No role

global aria-* attributes

input type = date No corresponding role

No role

global aria-* attributes

input type = datetime No corresponding role

No role

global aria-* attributes

input type = email with no list attribute role=textbox

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

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

input type = number role=spinbutton

No role

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

input type = password role=textbox

No role

global aria-* attributes

input type = radio role=radio

role:menuitemradio

global aria-* attributes and any aria-* attributes applicable to the menuitemradio role.

input type = range role=slider

No role

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

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

input type = text with no list attribute role=textbox

No role

global aria-* attributes

input type = text, search, tel, url, or email with a list attribute role=combobox

No role

global aria-* attributes and any aria-* attributes applicable to the combobox role.

input type= time No corresponding role

No role

global aria-* attributes

input type = url with no list attribute role=textbox

No role

global aria-* attributes

input type = week No corresponding role

No role

global aria-* attributes

ins and del

No corresponding role

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

keygen No corresponding role

No role

global aria-* attributes

label No corresponding role

No role

global aria-* attributes

legend No corresponding role global aria-* attributes
li element whose parent is an ol or ul role=listitem

Role: listitem, menuitem, menuitemcheckbox, menuitemradio, option, separator, tab, or treeitem

main role=main

No role

global aria-* attributes

map No corresponding role No role or aria* attributes
math role=math

No role

global aria-* attributes

meta No corresponding role No role or aria* attributes
meter role=progressbar global aria-* attributes
noscript No corresponding role No role or aria* attributes
object No corresponding role

Role: application, document, or img

global aria-* attributes and any aria-* attributes applicable to the allowed roles

ol role=list

Role: directory, group, listbox, menu, menubar, tablist, toolbar or tree

global aria-* attributes and any aria-* attributes applicable to the allowed roles

optgroup role=group global aria-* attributes
option element that is in a list of options or that represents a suggestion in a datalist role=option

global aria-* attributes

output role=status

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
progress role=progressbar

global aria-* attributes and any aria-* attributes applicable to the progressbar role.

script No corresponding role No role or aria* attributes
section role=region

Role: alert, alertdialog, application, banner, complementary, contentinfo, dialog, document, log, main, marquee, navigation, search, or status

global aria-* attributes and any aria-* attributes applicable to the allowed roles

select role=listbox

global aria-* attributes

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

style No corresponding role No role or aria* attributes
SVG No corresponding role

Role: application, document, or img

global aria-* attributes and any aria-* attributes applicable to the allowed roles

summary role=button

Role: button with aria-expanded="true" if the parent (details) element's open attribute is present, aria-expanded="false" otherwise.

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

table role=table

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

global aria-* attributes

tbody, thead, tfoot

role=rowgroup

Any role

global aria-* attributes

title No corresponding role No role or aria* attributes
td role=cell

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

Text level semantic elements not listed elsewhere:

em, strong, small, s, cite, q, dfn, abbr, time, code, var, samp, kbd, sub and sup, i, b, u, mark , ruby, rt, rp, bdi, bdo, br, wbr

No corresponding role Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

th role=columnheader or rowheader

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

tr

role=row

Any role

global aria-* attributes and any aria-* attributes applicable to the allowed roles

track No corresponding role No role or aria* attributes
ul role=list

Role: directory, group, listbox, menu, menubar, tablist, toolbar, tree, presentation

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.

Element with a disabled attribute aria-disabled="true"

Use the disabled attribute on any element that is allowed the disabled attribute in HTML5.

Only use the aria-disabled attribute for elements that are not allowed to have a disabled attribute in HTML5

Element with a required attribute aria-required="true"

Use the aria-required attribute on any element that is allowed the required attribute in HTML5.

MAY also be used for elements that have an attached ARIA role which allows the aria-required attribute.

Element with a readonly attribute aria-readonly="true"

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

Only use the aria-readonly attribute for elements that are not allowed to have a readonly attribute in HTML5

Element with a hidden attribute aria-hidden="true"

Use the aria-hidden attribute on any HTML element.

Note: If an element has a hidden attribute, an aria-hidden attribute is not required.

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

Only use the aria-invalid attribute for elements that are not submittable elements in HTML5

The elements marked with No corresponding role, in the second column of the table do not have any default 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 web 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 WAI-ARIA in HTML - A practical guide for developers on how to to add accessibility information to HTML elements using the Accessible Rich Internet Applications specification [wai-aria].
  • WAI-ARIA 1.0 Authoring Practices - An author's guide to understanding and implementing Accessible Rich Internet Applications.

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

4. Allowed ARIA roles, states and properties

This section is non-normative.

Note

The following table provides an informative 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] specification. Links to ARIA roles, states and properties in the table reference the normative [!wai-aria-1.1] definitions.

ARIA Roles, States and Properties
Role Description Required Properties Supported Properties
any ARIA global states and properties can be used on any HTML element. none
alert A message with important, and usually time-sensitive, information. See related alertdialog and status. none
alertdialog A type of dialog that contains an alert message, where initial focus goes to an element within the dialog. See related alert dialog. none
application A region declared as a web application, as opposed to a web document. none
article A section of a page that consists of a composition that forms an independent part of a document, page, or site. none
banner A region that contains mostly site-oriented content, rather than page-specific content. none
button An input that allows for user-triggered actions when clicked or pressed. See related link. none
cell A cell in a tabular container.    
checkbox A checkable input that has three possible values: true, false, or mixed.
columnheader A cell containing header information for a column. none
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.
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
contentinfo A large perceivable region that contains information about the parent document. none
definition A definition of a term or concept. none
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
directory A list of references to members of a group, such as a static table of contents. none
document A region containing related information that is declared as document content, as opposed to a web application. none
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
grid A grid is an interactive control which contains cells of tabular data arranged in rows and columns, like a table. none
gridcell A cell in a grid or treegrid. none
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
heading A heading for a section of the page. none
img A container for a collection of elements that form an image. none
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
list A group of non-interactive list items. See related listbox. none
listbox A widget that allows the user to select one or more items from a list of choices. See related combobox and list. none
listitem A single item in a list or directory. none
log A type of live region where new information is added in meaningful order and old information may disappear. See related marquee. none
main The main content of a document. none
marquee A type of live region where non-essential information changes frequently. See related log. none
math Content that represents a mathematical expression. none
menu A type of widget that offers a list of choices to the user. none
menubar A presentation of menu that usually remains visible and is usually presented horizontally. none
menuitem An option in a group of choices contained by a menu or menubar. none
menuitemcheckbox A checkable menuitem that has three possible values: true, false, or mixed.
menuitemradio A checkable menuitem in a group of menuitemradio roles, only one of which can be checked at a time.
navigation A collection of navigational elements (usually links) for navigating the document or related documents. none
note A section whose content is parenthetic or ancillary to the main content of the resource. none
option A selectable item in a select list. none
presentation An element whose implicit native role semantics will not be mapped to the accessibility API. none
progressbar An element that displays the progress status for tasks that take a long time. none
radio A checkable input in a group of radio roles, only one of which can be checked at a time.
radiogroup A group of radio buttons. none
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
row

A row of cells in a tabular container.

none
rowgroup A group containing one or more row elements in a grid. none
rowheader A cell containing header information for a row in a grid. none
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.
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
A type of textbox intended for specifying search criteria. none
separator A divider that separates and distinguishes sections of content or groups of menuitems.

none

slider A user input where the user selects a value from within a given range.
spinbutton A form of range that expects the user to select from among discrete choices.
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
switch A type of checkbox that represents on/off values, as opposed to checked/unchecked values.  
tab A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user. none
table A section containing data arranged in rows and columns. The table role is intended for tabular containers which are not interactive. none
tablist A list of tab elements, which are references to tabpanel elements. none
tabpanel A container for the resources associated with a tab, where each tab is contained in a tablist. none
textbox Input that allows free-form text as its value. none
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
toolbar A collection of commonly used function buttons represented in compact visual form. none
tooltip A contextual popup that displays a description for an element. none
tree A type of list that may contain sub-level nested groups that can be collapsed and expanded. none
treegrid A grid whose rows can be expanded and collapsed in the same manner as for a tree. none
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

5. Requirements for implementers

Conformance Checker implementers

Conformance checkers that claim support for checking of ARIA in HTML, MUST implement checks for the document conformance requirements for use of the ARIA role and aria-* attributes on HTML elements as defined in this specification.

Documents MUST NOT use any role values with elements in the Document conformance requirements for use of ARIA attributes in HTML table, other than the corresponding role value (if any) as listed for that element in the third column, other than those indicated in the second column, which SHOULD NOT be used.

6. Conformance Requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. The key word "OPTIONALLY" in the normative parts of this document is to be interpreted with the same normative meaning as "MAY" and "OPTIONAL". For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]]

A. References

A.1 Normative references

[HTML51]
Simon Pieters; Anne van Kesteren; Philip Jägenstedt; Domenic Denicola; Ian Hickson; Steve Faulkner; Arron Eicholz; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Robin Berjon. W3C. HTML 5.1. 10 March 2016. W3C Working Draft. URL: http://www.w3.org/TR/html51/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[wai-aria]
James Craig; Michael Cooper et al. W3C. Accessible Rich Internet Applications (WAI-ARIA) 1.0. 20 March 2014. W3C Recommendation. URL: http://www.w3.org/TR/wai-aria/
[wai-aria-1.1]
Joanmarie Diggs; James Craig; Shane McCarron; Michael Cooper. W3C. Accessible Rich Internet Applications (WAI-ARIA) 1.1. 19 November 2015. W3C Working Draft. URL: http://www.w3.org/TR/wai-aria-1.1/