ARIA in HTML

bugs ⋔ me CC0 2014-12-17 ( commit log )

Abstract

This specification defines the web developer (author) rules (conformance requirements) for the use of [wai-aria] attributes on [HTML5] elements. It also defines requirements for Conformance Checking tools and a subset of requirements for UA implementers.

Table of Contents

1. Requirements of ARIA use in HTML for web developers

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

Web developers MAY use the ARIA role and aria-* attributes on HTML elements , in accordance with the requirements described in [wai-aria] , 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, detailed in the 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>
Example document for conformance checking

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

non conforming ARIA use example :

1.1. ARIA Role Attribute

Any HTML element, other than elements indicated Document conformance requirements for use of ARIA attributes in HTML as allowing No role , may have an ARIA role attribute specified. This is an ARIA Role attribute as defined by [wai-aria] Section 5.4 Definition of Roles .

The attribute, if specified, MUST have a value that is a set of space-separated tokens; each token MUST be a non-abstract role defined in the WAI-ARIA specification [wai-aria] .

1.2. State and Property Attributes

Every HTML element may have ARIA state and property attributes specified. These attributes are defined by [wai-aria] .

A subset of the ARIA State and Property attributes are defined as " Global States and Properties " in Section 6.4. Global States and Properties of the [wai-aria] Specification.

These attributes, if specified, MUST have a value that is the ARIA value type in the "Value" field of the definition for the state or property, mapped to the appropriate HTML value type according to [wai-aria] Section 10.2 Mapping WAI-ARIA Value types to languages using the HTML5 mapping.

ARIA State and Property attributes can be used on any element. They are not always meaningful, however, and in such cases user agents might not perform any processing aside from including them in the DOM.

1.3. Default Implicit Semantics

The following table defines the default implicit ARIA semantics that apply to HTML elements . 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.

Documents MUST NOT use any role values with elements in the following table other than the corresponding role value (if any) as listed for that element in the third column, or the role value " presentation ", if the third column indicates that element’s semantics can be removed by using the " presentation " role value.

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.

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

Rules use of ARIA attributes usage by HTML language feature
HTML language feature Default ARIA semantics - SHOULD NOT be used ARIA roles, states and properties which MAY be used
All elements varies Role: presentation , except focusable elements or those with the warning ' Not role=presentation ' or those indicated: NONE
a element with a href role= link

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

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

Not role=presentation

a element without a href NONE

Role: Any

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

address NONE

Role: contentinfo
global aria-* attributes

area with a href role= link

Any aria-* attributes applicable to the link role. Any global aria-* attributes

Not role=presentation

article role= article

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

aside role= complementary

Roles: note or search .

global aria-* attributes

audio NONE

Role: application
Any aria-* attributes applicable to the application role. Any global aria-* attributes

base NONE NONE
body role= document global aria-* attributes
button role= button

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

Not role=presentation

button type="menu" role=button with aria-haspopup=true

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

Not role=presentation

caption NONE global aria-* attributes

col , colgroup

NONE NONE
datalist role=listbox , with aria-multiselectable=false

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

dd , dt NONE global aria-* attributes
details role=group global aria-* attributes and any aria-* attributes applicable to the group role.
dialog element with no open attribute role=dialog , with aria-hidden = true

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

Not role=presentation

div NONE

Role: Any

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

Note: It is recommended that any scripted widgets use the semantically neutral div or span elements unless HTML elements with native semantics are being used as fallback.

dl role=list

global aria-* attributes

embed NONE

Role: application, document, or img

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

figure NONE

Role: Any, recommend role=group

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

footer NONE

Use contentinfo role for the main footer on a page.

global aria-* attributes

form role=form

global aria-* attributes

grouping content elements not listed elsewhere:

p , pre , blockquote

NONE

Role: any

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

h1 to h6 element role=heading , with the aria-level = element’s outline depth global aria-* attributes
head NONE NONE
header NONE

global aria-* attributes

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

Role: application, document, or img

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

iframe (seamless) EDITOR: okay to override with any general grouping role.

Role: application, document, or img

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

img with alt ="" role=presentation NONE
img with alt =" some text " role=img

Role: Any

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

input type= button role=button

Role: link, menuitem, menuitemcheckbox, menuitemradio, radio

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

Not role=presentation

input type= checkbox aria-checked=mixed if the element’s indeterminate IDL attribute is true, or aria-checked=true if checked attribute is present

global aria-* attributes

Not role=presentation

input type = color NONE

global aria-* attributes

Not role=presentation

input type = date NONE

global aria-* attributes

Not role=presentation

input type = datetime NONE

global aria-* attributes

Not role=presentation

input type = email with no list attribute role=textbox

global aria-* attributes

Not role=presentation

input type = file NONE

global aria-* attributes

Not role=presentation

input type = hidden NONE NONE
input type= image role=button

Role: link, menuitem, menuitemcheckbox, menuitemradio, radio

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

Not role=presentation

input type = month NONE

global aria-* attributes

Not role=presentation

input type = number role=spinbutton , with the aria-readonly property set to "true" if the element has a readonly attribute, 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

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

Not role=presentation

input type = password role=textbox

global aria-* attributes

Not role=presentation

input type = radio role=radio

Role: menuitemradio

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

Not role=presentation

input type = range role=slider with aria-valuemax property set to the element’s maximum , and the aria-valuemin property set to the element’s minimum .

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

Not role=presentation

input type= reset button role

global aria-* attributes

Not role=presentation

input type = search , with no list attribute textbox role

global aria-* attributes

Not role=presentation

input type = submit button role

global aria-* attributes

Not role=presentation

input type = tel with no list attribute textbox role

global aria-* attributes

Not role=presentation

input type = text with no list attribute textbox role

global aria-* attributes

Not role=presentation

input type = text , search , tel , url , or email with a list attribute combobox role, with the aria-owns property set to the same value as the list attribute

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

Not role=presentation

input type= time NONE

global aria-* attributes

Not role=presentation

input type = url with no list attribute textbox role

global aria-* attributes

Not role=presentation

input type = week NONE

global aria-* attributes

Not role=presentation

ins and del

NONE

Role: any

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

keygen NONE

global aria-* attributes

Not role=presentation

label NONE global aria-* attributes
li element whose parent is an ol or ul role=listitem

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

link element with a href role=link NONE
main role=main global aria-* attributes
map NONE NONE
math NONE global aria-* attributes
menu type = toolbar role=toolbar

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

Not role=presentation

menuitem type = command role=menuitem

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

Not role=presentation

menuitem type = checkbox role=menuitemcheckbox

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

Not role=presentation

menuitem type = radio role=menuitemradio

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

Not role=presentation

meta NONE NONE
meter role=progressbar global aria-* attributes
nav role=navigation global aria-* attributes
noscript NONE NONE
object NONE

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 NONE global aria-* attributes
option element that is in a list of options or that represents a suggestion in a datalist role=option , with aria-selected=true if the selected attribute is present, aria-selected=false otherwise.

global aria-* attributes

Not role=presentation

output role=status

Role: Any, use in conjunction with aria-live=polite

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

param NONE NONE
picture NONE NONE
progress 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

.

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

script NONE NONE
section role=region

Role: alert, alertdialog, application, contentinfo, dialog, document, log, marquee, search, or status

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

select element with a multiple attribute role=listbox , with aria-multiselectable=true

global aria-* attributes

Not role=presentation

select element with no multiple attribute role=listbox , with aria-multiselectable=false

global aria-* attributes

Not role=presentation

source NONE NONE
span NONE

Role: Any

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

style NONE NONE
SVG NONE

Role: application, document, or img

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

summary NONE

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 NONE

Role: any

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

template NONE NONE
textarea role=textbox

global aria-* attributes

Not role=presentation

tbody , thead , tfoot

role=rowgroup

Role: any

global aria-* attributes

title NONE NONE
td NONE

Role: any

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

NONE

Role: any

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

th NONE

Role: any

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

th element that is a sorting-capable th element whose column key ordinality is 1 role=columnheader , with the aria-sort state set to "ascending" if the element’s column sort direction is normal , and "descending" otherwise.

global aria-* attributes

Not role=presentation

tr

NONE

Role: any

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

track NONE NONE
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 NONE

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 The aria-required="true"

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

Also use the aria-required attribute 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 hidden attribute in conjunction with the CSS display:none property
Element is natively focusable (links, buttons, etc.) NONE

Not role=presentation

Element is not focusable by default (e.g. li, span, div, etc.) is in a visible display state and is made focusable (via tabindex ). DEPENDS Not role=presentation
Element that is a candidate for constraint validation but that does not satisfy its constraints aria-invalid=true

Only use the aria-invalid=true attribute after form has been validated, setting it prior means users think the field is invalid before they even input data or interact with it.

(Editor’s NOTE) Provide link to what HTML defines what constitutes the user has interacted with the control "significantly." ARIA defines aria-invalid="grammar" and aria-invalid="spelling"

The listed elements with default ARIA semantics of NONE do not have any default ARIA semantics, but they do have meaning and this meaning may be represented in roles, states and properties not provided by ARIA, but present in accessibility APIs. It is therefore recommended that authors should add a role attribute to a semantically neutral element such as a div or span , rather than overriding the semantics of the listed elements.

The entry " no role ", when used as a strong native semantic , means that no role can be used and that the user agent has no default mapping to ARIA roles. (However, it could have its own mappings to the accessibility layer.) When used as a default implicit ARIA semantic , it means the user agent has no default mapping to ARIA roles. (However, it could have its own mappings to the accessibility layer.)

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

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 annotations would end up being rendered by screen readers as a very painful reading of lots of punctuation. 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>

2.1. Allowed ARIA roles, states and properties

This section is non-normative.

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] 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
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 grid. 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
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
tab A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user. 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

3. Requirements for implementers

3.1. UA implementers

User agents MUST implement ARIA semantics on all HTML elements, as defined in the ARIA specifications. The default implicit ARIA semantics defined in section 2.3.1 Mapping to Existing WAI-ARIA Role Semantics of the HTML Accessibility API Mappings 1.1 specification, as well as [wai-aria] and [wai-aria-implementation] MUST be recognised by implementations for the purposes of ARIA processing. [wai-aria-implementation]

The WAI-ARIA role that an HTML element has assigned to it is the first non-abstract role found in the list of values generated when the role attribute is split on spaces.

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 required form fields or landmark navigation. User agents are encouraged to maximize their usefulness to users, including users without disabilities.

3.2. Conformance Checker implementers

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 button role, a conformance checker could say "Use a more appropriate element to represent a button, for example a button element or an input element" rather than "The button role cannot be used with a elements".

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. [RFC2119]

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes.

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example" , like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note" , like this:

Note, this is an informative note.

References

Normative References

[html5]
Steve Faulkner; et al. HTML5 . 16 September 2014. PR. URL: http://www.w3.org/TR/html5/
[rfc2119]
???; et al. Key words for use in RFCs to Indicate Requirement Levels . March 1997. Best Current Practice. URL: http://www.ietf.org/rfc/rfc2119.txt
[wai-aria]
Michael Cooper; et al. Accessible Rich Internet Applications (WAI-ARIA) 1.0 . 20 March 2014. REC. 1 URL: http://www.w3.org/TR/wai-aria/
[wai-aria-implementation]
Michael Cooper; et al. WAI-ARIA 1.0 User Agent Implementation Guide . 20 March 2014. REC. URL: http://www.w3.org/TR/wai-aria-implementation/

Index

Copyright

The contributors to this specification have waived all copyright and related or neighbouring rights to this work worldwide under copyright law, including all related and neighbouring rights, to the extent allowed by law.