Abstract

This specification defines the web developer rules (author conformance requirements) for the use of [wai-aria-1.1] and [dpub-aria-1.0] attributes on [HTML52] 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 https://www.w3.org/TR/.

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

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.

1. Web developer requirements for use of ARIA in HTML

Web developers MAY use the ARIArole 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 implicit ARIA semantics of a given HTML element. These constraints, are intended to prevent developers from making assistive technology products report nonsensical user interface (UI) information that does not represent the actual UI of the document.

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 the HTML Accessibility API Mappings 1.0 [html-aam-1.0] 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. The third cell in each row defines which ARIA role values and aria-* attributes which MAY be used. Where a cell in the third column includes the term Anyrole it indicates that any role value apart from the implicit ARIA semanticsrole value, MAY be used.

Note

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

Note

The (new) and (changed) markers in the following table indicate new (in ARIA 1.1) or changed (between ARIA 1.0/1.1) ARIA roles, states and properties

Do not set aria-readonly="true" on an element that has a contenteditable attribute set. - (new)

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 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 ARIA -
A practical guide for developers on how to to add accessibility information to HTML elements using
the Accessible Rich Internet Applications specification (ARIA 1.1).

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:

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 ARIA 1.1 specification. Links to ARIA roles, states and properties in the table reference the normative ARIA 1.1 definitions.

Column 5 of the ARIA Roles, States and Properties table, defines extensions to the Kinds of content (defined in the [HTML52] 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, an element with role=button is interactive content and therefore cannot contain interactive content descendants. A button element has an implicit role=button, so cannot contain any elements with role values that are in the interactive content category (identified in Column 3).

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.

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.

5. Requirements for implementers

5.1 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 ARIArole and aria-* attributes on HTML elements as defined in this specification.

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]]