Updated 30th November 2010.

3.2.6 Use of WAI-ARIA Roles, States and Properties in HTML

Introduction

The Web Accessibility Initiative Accessible Rich Internet Applications (WAI-ARIA) Suite, defines a way to make Web content and Web applications more accessible to people with disabilities. It especially helps with dynamic content and advanced user interface controls developed with Ajax, Dynamic HTML, JavaScript, Cascading Style Sheets, and related technologies. Currently, certain functionality used in Web sites inaccessible to some users with disabilities, especially people who rely on screen readers and people who cannot use a mouse. WAI-ARIA addresses these accessibility challenges by defining new ways for functionality to be provided to assistive technology. Desktop operating systems have long provided APIs to allow assistive technology products to access applications, by exposing the role of a control along with its states, properties, and values. WAI-ARIA allows web application developers to expose the same sorts of information for Web applications. This information is used by user agents to support the same accessibility APIs as used by desktop applications allowing authors to provide accessibility information consistent with their intent. With WAI-ARIA, developers can make advanced Web applications accessible and usable to people with disabilities.

Authors often use a combination of scripting, event handlers, and CSS to create custom widgets. When there are native language features that provide the same semantic meaning and interaction behaviors as a custom widget, authors are strongly encouraged to use the native language features. In these cases, accessible user agents should have done most of the work to ensure these native language features support assistive technologies. If the author chooses to create a custom widget, thus changing the functionality of an existing HTML element, the author may need to add WAI-ARIA role and aria-* attributes to make it accessible. In these instances the author must follow the conformance rules for applying WAI-ARIA to HTML defined in this section as well as the rules for using WAI-ARIA defined in the [WAI-ARIA] specification.

Authors may use the WAI-ARIA role and aria-* attributes on HTML elements, in accordance with the requirements described in the ARIA specifications, except where these conflict with the semantics described in this section. These exceptions are intended to prevent providing conflicting, duplicate, or meanlingless roles, states, and properties to assistive technologies when applied to HTML elements. [WAI-ARIA].

Use of WAI-ARIA in HTML

The following table lists HTML language features ordered alphabetically and the corresponding WAI-ARIA semantics, if any. Each language feature (element or attribute) in a cell in the first column can be mapped to the ARIA semantics (role, states, and/or properties) given in the cell in the second column of the same row. The third column details the allowed ARIA role, states and properties for the language feature in the first column of the same row. Authors must not set the WAI-ARIA role and aria-* attributes in a manner that conflicts with the semantics described in the following table as the resulting conflicts may make it difficult for assistive technology to support the content.

ARIA to HTML mappings and allowed overrides
Language feature Default ARIA Role and required State and Property mapping Allowed Roles and aria-* attributes
a element that represents a hyperlink link role If specified, role must be one of the following: button, checkbox, link, menuitem, menuitemcheckbox, menuitemradio, presentation, progressbar, radio, slider, scrollbar, tab, or treeitem. Applicable widget attributes and global attributes.
a element (with no href) none any role, any aria-* attributes
abbr element none any role, any aria-* attributes
address element none If specified, role must be contentinfo or presentation. Global attributes.
area element that represents a hyperlink link role If specified, role must be one of the following: button, checkbox, link, menuitem, menuitemcheckbox, menuitemradio, presentation, progressbar, radio, slider, scrollbar, tab, or treeitem. Applicable widget attributes and global attributes.
area element that has no href attribute none any role, any aria-* attributes
article element article role Role must be either article, document, application, presentation or main. Global attributes.
aside element note role If specified, role must be note, complementary, presentationor search.Global attributes.
audio element none If specified, role must be application or presentation. Global attributes.
b element none any role, any aria-* attributes
base element none none
bdo element none any role, any aria-* attributes
blockquote element none any role, any aria-* attributes
body element document role If specified, role must be document, application or presentation. Global attributes.
br element none any role, any aria-* attributes
button element button role If specified, role must be one of the following: button, link, menuitem, menuitemcheckbox, menuitemradio,presentation, radio, slider, scrollbar or progressbar. Applicable widget attributes and global attributes.
canvas element none any role, any aria-* attributes
cite element none any role, any aria-* attributes
code element none any role, any aria-* attributes
col none any role, any aria-* attributes
colgroup element none any role, any aria-* attributes
command element menuitem role If specified, role must be one of the following: button, link, menuitem, menuitemcheckbox, menuitemradio or presentation. Applicable widget attributes and global attributes.
datalist element listbox role, with the aria-multiselectable property set to "false" listbox role, with the aria-multiselectable property set to "false" or presentation. Applicable widget attributes and global attributes.
dd element none any role, any aria-* attributes
del element none any role, any aria-* attributes
details element none any role, any aria-* attributes
dfn element none any role, any aria-* attributes
dl element none any role, any aria-* attributes
dt element none any role, any aria-* attributes
div element none any role, any aria-* attributes
em element none any role, any aria-* attributes
embed element none If specified, role must be img, document, application or presentation.Global attributes.
fieldset element none any role, any aria-* attributes
figcaption element none any role, any aria-* attributes
figure element none any role, any aria-* attributes
footer element none If specified, role must be contentinfo or presentation. Global attributes.
form element form role If specified, role must be application, form, search or presentation.Global attributes.
head element none none
header element none If specified, role must be banner or presentation. Global attributes.
hgroup element none presentation role. Global attributes.
h1 to h6 element that does have an hgroup ancestor The first h1 to h6 element element with the highest ranking (1-6) has a heading role with the aria-level property set to the element's ranking . Any other h1 to h6 element elements have no default role. If specified, role must be one of the following: button, checkbox, link, menuitem, menuitemcheckbox, menuitemradio, option, presentation, radio, slider, spinbutton, scrollbar, tab or treeitem.Applicable widget attributes and global attributes.
h1 to h6 element that does not have an hgroup ancestor heading role, with the aria-level property set to the element's outline depth If specified, role must be one of the following: button, checkbox, link, menuitem, menuitemcheckbox, menuitemradio, option, presentation, radio, slider, spinbutton, scrollbar, tab or treeitem.Applicable widget attributes and global attributes.
hr element separator role separator or presentation. Applicable widget attributes and global attributes.
HTML element none none
i element none any role, any aria-* attributes
iframe element none If specified, role must be application, banner,complimentary, contentinfo, document, form, main, navigation, presentation or search. Global attributes.
img element img role any role, any aria-* attributes
img element whose alt attribute's value is empty presentation role presentation role. Global attributes.
input element with a type attribute in the Button state button role If specified, role must be one of the following: button, link, menuitem, menuitemcheckbox, menuitemradio, presentation, radio, slider, scrollbar or progressbar.Applicable widget attributes and global attributes.
input element with a type attribute in the Checkbox state checkbox role, with the aria-checked state set to "mixed" if the element's indeterminate IDL attribute is true, or "true" if the element's checkedness is true, or "false" otherwise If specified, role must be one of the following: checkbox or menuitemcheckbox with thearia-checkedstate set to "mixed" if the element's indeterminate IDL attribute is true, or "true" if the element's checkedness is true, or "false" otherwise, presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the color state none presentation role. Global attributes.
input element with a type attribute in the Date state none presentation role. Global attributes.
input element with a type attribute in the Date and Time state none presentation role. Global attributes.
input element with a type attribute in the Local Date and Time state none presentation role. Global attributes.
input element with a type attribute in the E-mail state with no suggestions source element textbox role textbox or presentation. Applicable widget attributes, any live region, drag & drop and relationship attributes.
input element with a type attribute in the File Upload state none presentation role. Global attributes.
input element with a type attribute in the Hidden state none presentation role. Global attributes.
input element with a type attribute in the Image Button state button role If specified, role must be one of the following: button, link, menuitem, menuitemcheckbox, menuitemradio, presentation, radio, slider, scrollbar or progressbar. Applicable widget attributes and global attributes.
input element with a type attribute in the Month state none presentation role. Global attributes.
input element with a type attribute in the Number state spinbutton role, with the aria-valuemax property set to the element's maximum, the aria-valuemin property set to the element's minimum, and, if the result of applying the rules for parsing floating point number values to the element's value is a number, with the aria-valuenow property set to that number spinbutton role, with the aria-valuemax property set to the element's maximum, the aria-valuemin property set to the element's minimum, and, if the result of applying the rules for parsing floating point number values to the element's value is a number, with the aria-valuenow property set to that number. presentationrole. Applicable widget attributes and global attributes.
input element with a type attribute in the Password state textbox role textbox or presentation. Applicable widget attributes and global attributes.
input element with a type attribute in the Radio Button state radio role, with the aria-checked state set to "true" if the element's checkedness is true, or "false" otherwise If specified, role must be either radio, menuitemradio or presentation. Applicable widget attributes and global attributes.
input element with a type attribute in the Range state slider role, with the aria-valuemax property set to the element's maximum, the aria-valuemin property set to the element's minimum, and the aria-valuenow property set to the result of applying the rules for parsing floating point number values to the element's value, if that that results in a number, or the default value otherwise slider role, with the aria-valuemax property set to the element's maximum, the aria-valuemin property set to the element's minimum, and the aria-valuenow property set to the result of applying the rules for parsing floating point number values to the element's value, if that that results in a number, or the default value otherwise. presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Reset Button state button role button or presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Search state with no suggestions source element textbox role textbox or presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Submit Button state button role button or presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Telephone state with no suggestions source element textbox role textbox or presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Text state with no suggestions source element textbox role textbox or presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Text, Search, Telephone, URL, or E-mail states with a suggestions source element combobox role, with the aria-owns property set to the same value as the list attribute combobox role, with the aria-owns property set to the same value as the list attribute. presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Time state none presentation role. Global attributes.
input element with a type attribute in the URL state with no suggestions source element textbox role textbox role, with the aria-readonly state set to "true" if the element has a readonly attribute. presentation role. Applicable widget attributes and global attributes.
input element with a type attribute in the Week state none presentation role. Global attributes.
ins element none any role, any aria-* attributes
kbd element none any role, any aria-* attributes
keygen element none presentation role. Global attributes.
label element * CS to report back on restrictions. none If specified, role must be alert, log, marquee, presentation, status or timer. Applicable widget attributes and global attributes.
li element whose parent is an ol or ul element listitem role If specified, role must be one of the following: menuitem, menuitemcheckbox, menuitemradio, option, tab,treeitem or presentation. Applicable widget attributes and global attributes.
li element whose parent is a menu element listitem role If specified, role must be one of the following: menuitem, menuitemcheckbox, menuitemradio, option, tab, treeitem or presentation. Applicable widget attributes and global attributes.
link element link role If specified, role must be link or presentation. Applicable widget attributes and global attributes.
map element none any role, any aria-* attributes
mark none any role, any aria-* attributes
menu element with a type attribute in the context menu state no role aria-haspopup="true", presentation role. Global attributes.
menu element with a type attribute in the list state menu role If specified, role must be menu or presentation role. Applicable widget attributes and global attributes.
menu element with a type attribute in the toolbar state toolbar role If specified, role must be toolbar role or presentation. Applicable widget attributes and global attributes.
An element that defines a command, whose Type facet is "checkbox", and that is a descendant of a menu element whose type attribute in the list state menuitemcheckbox role, with the aria-checked state set to "true" if the command's Checked State facet is true, and "false" otherwise menuitemcheckbox role, with the aria-checked state set to "true" if the command's Checked State facet is true, and "false" otherwise. presentation role. Applicable widget attributes and global attributes.
An element that defines a command, whose Type facet is "command", and that is a descendant of a menu element whose type attribute in the list state menuitem role If specified, role must be menuitem or presentation. Applicable widget attributes and global attributes.
An element that defines a command, whose Type facet is "radio", and that is a descendant of a menu element whose type attribute in the list state menuitemradio role, with the aria-checked state set to "true" if the command's Checked State facet is true, and "false" otherwise menuitemradio role, with the aria-checked state set to "true" if the command's Checked State facet is true, and "false" otherwise. presentation role. Applicable widget attributes and global attributes.
meta element none none
meter element none presentation role. Global attributes.
nav element navigation role navigation or presentation role. Applicable widget attributes and global attributes.
noscript element none none
object element no role If specified, role must be img, document, presentation or application.Global attributes.
ol element list role If specified, role must be one of the following: group, list, listbox, menu, menubar, tablist, toolbar, tree, directory or presentation. Applicable widget attributes and global attributes.
optgroup element group role group or presentation. Global attributes.
option element that is in a list of options or that represents a suggestion in a datalist element option role, with the aria-selected state set to "true" if the element's selectedness is true, or "false" otherwise. option role, with the aria-selected state set to "true" if the element's selectedness is true, or "false" otherwise. presentation role. Applicable widget attributes and global attributes.
output element status role status or presentation role. Applicable widget attributes and global attributes.
p element none any role, any aria-* attributes
param element none none
pre element none any role, any aria-* attributes
progress element progressbar role, with, if the progress bar is determinate, the aria-valuemax property set to the maximum value of the progress bar, the aria-valuemin property set to zero, and the aria-valuenow property set to the current value of the progress bar progressbar role, with, if the progress bar is determinate, the aria-valuemax property set to the maximum value of the progress bar, the aria-valuemin property set to zero, and the aria-valuenow property set to the current value of the progress bar. presentation role. Applicable widget attributes and global attributes.
ruby element none any role, any aria-* attributes
q none any role, any aria-* attributes
samp element none any role, any aria-* attributes
script element none none
section element region role If specified, role must be region, document, application, contentinfo, main , search, alert, dialog, alertdialog, status, presentation or log. Applicable widget attributes and global attributes.
select element with a multiple attribute listbox role, with the aria-multiselectable property set to "true" listbox role, with the aria-multiselectable property set to "true". presentation role. Applicable widget attributes and global attributes.
select element with no multiple attribute listbox role, with the aria-multiselectable property set to "false" listbox role, with the aria-multiselectable property set to "false". presentation role. Applicable widget attributes and global attributes.
small element none any role, any aria-* attributes
source element none none
span element none any role, any aria-* attributes
strong element none any role, any aria-* attributes
style element none none
sub element none any role, any aria-* attributes
summary element none any role, any aria-* attributes
sup element none any role, any aria-* attributes
table element none any role, any aria-* attributes
tbody none any role, any aria-* attributes
td element none any role, any aria-* attributes
textarea element textbox role, with the aria-multiline property set to "true" textbox role, with the aria-multiline property set to "true". presentation role. Applicable widget attributes and global attributes.
tfoot element none any role, any aria-* attributes
th element that is neither a column header nor a row header none any role, any aria-* attributes
th element that is a column header none any role, any aria-* attributes
th element that is a row header none any role, any aria-* attributes
thead element none any role, any aria-* attributes
time element none any role, any aria-* attributes
title element none none
tr element none any role, any aria-* attributes
ul element list role If specified, role must be one of the following: group, list, listbox, menu, menubar, tablist, toolbar, tree, directory or presentation. Applicable widget attributes and global attributes.
var element none any role, any aria-* attributes
video element none If specified, role must be application. Global attributes.
wbr element none any role, any aria-* attributes

WAI-ARIA state and property attributes use in HTML5

Unless indicated otherwise, any aria-* state and property attributes may be used on any HTML element in conformance with the rules defined in the [WAI-ARIA] specification .

In a context where a WAI-ARIA attribute and a HTML5 attribute have the same mapping to Accessibility APIs and the use of the HTML5 attribute is conforming on an element, the WAI-ARIA attribute if present must reflect the same state or value as the HTML5 attribute.

WAI-ARIA to HTML attribute mapping
ARIA attribute HTML5 attribute HTML5 attribute applicable on Notes
aria-autocomplete autocomplete form; input If aria-autocomplete="list", aria-autocomplete="inline"or aria-autocomplete="both" is set on an element that allows autocomplete, then autocomplete="on" must be set on that element. If aria-autocomplete="none" is set on an element that allows autocomplete, then autocomplete="off" must be set on that element.
aria-checked checked command; input If aria-checked attribute is set on an element that allows checked and the checked attribute is set on that element, the state of aria-checked must match the state of checked.
aria-disabled disabled button; command; fieldset; input; keygen; optgroup; option; select; textarea If aria-disabled attribute is set on an element that allows disabled the disabled attribute must be set on that element and the state of aria-disabled must match the state of disabled.
aria-expanded open details If aria-expanded attribute is set on an element that allows open, the open attribute must be set on that element, the state of aria-expanded must match the state of open.
aria-haspopup contextmenu all elements If aria-haspopup attribute is set on an element that allows contextmenu and the contextmenu attribute is set on that element, the state of aria-haspopup must match the state of contextmenu.
aria-grabbed draggable all elements If aria-grabbed attribute is set to on an element, the draggable element must also be set on that element.
aria-hidden hidden all elements If aria-hidden attribute is set on an element that allows hidden and the hidden attribute is set on that element, the state of aria-hidden must match the state of hidden.
aria-multiselectable multiple input, select If aria-multiselectable attribute is set on an element that allows multiple, the multiple attribute must be set on that element and the state of aria-multiselectable must be set to true .
aria-readonly readonly input; textarea If aria-readonly attribute is set on an element that allows readonly, the readonly attribute must be set on that element, the state of aria-readonly must match the state of readonly.
aria-required required input; select; textarea If aria-required attribute is set on an element that allows required, the required attribute must be set on that element, the state of aria-required must match the state of required.
aria-valuemax max progress, input type="range" If aria-valuemax attribute is set on an element that allows max,the max attribute must be set on that element and the value of aria-valuemax must match the value of max.
aria-valuemin min input type="range" If aria-valuemin attribute is set on an element that allows min, the min attribute must be set on that element, the value of aria-valuemin must match the value of min.
aria-valuenow value progress, input type="range" If aria-valuenow attribute is set on an element that allows value, the value attribute must be set on that element, the value of aria-valuenow must match the value of value.

Conformance checkers are encouraged to phrase errors such that authors are encouraged to use more appropriate elements rather than remove accessibility annotations. For example, if an a element is marked as having the heading role, a conformance checker could say "Use a more appropriate element to represent a heading, for example a h1 element or an hgroup element" rather than "The heading role cannot be used with a elements".

Guidance for User Agents

User agents are required to implement WAI-ARIA semantics on all HTML elements, as defined in the WAI-ARIA specifications. User agents are required to expose ARIA to desktop accessibility API as defined in the ARIA specifications. The implicit ARIA semantics defined in the table ARIA to HTML mappings and allowed overrides must be recognized by implementations. [ARIAIMPL]

This section is for the use of conformance checkers and authors. While violations of this section in authored documents constitute authoring errors, User Agents must still map ARIA values to platform APIs according to the ARIA specification and ARIA Implementation Guide.

HTML5 elements and attributes should be mapped to Accessibility APIs as detailed in the HTML to Platform Accessibility APIs Implementation Guide.

Note:

The WAI-ARIA specification neither requires or forbids user agents from enhancing native presentation and interaction behaviors on the basis of WAI-ARIA markup. Even mainstream user agents might choose to expose metadata or navigational features directly or via user-installed extensions; for example, exposing indicating live region updates or landmark navigation. User agents are encouraged to maximize their usefulness to users, including users without disabilities.

References: