HTML Accessibility API Mappings 1.0

W3C Working Draft

This version:
https://www.w3.org/TR/2019/WD-html-aam-1.0-20191210/
Latest published version:
https://www.w3.org/TR/html-aam-1.0/
Latest editor's draft:
https://w3c.github.io/html-aam/
Previous version:
https://www.w3.org/TR/2019/WD-html-aam-1.0-20191112/
Editors:
Steve Faulkner (The Paciello Group)
Alexander Surkov (Mozilla Foundation)
Scott O'Hara (The Paciello Group)
Former editors:
Bogdan Brinza (Microsoft) (until July 2018)
Jason Kiss (Invited Expert) (until June 2018)
Cynthia Shelly (Microsoft) (until September 2013)
Participate:
GitHub w3c/html-aam
File a bug
Commit history
Pull requests

Abstract

HTML Accessibility API Mappings (HTML-AAM) defines how user agents map HTML [HTML] elements and attributes to platform accessibility application programming interfaces (APIs). It leverages and extends the Core Accessibility API Mappings 1.2 and the Accessible Name and Description Computation 1.1 for use with the HTML host language. Documenting these mappings promotes interoperable exposure of roles, states, properties, and events implemented by accessibility APIs and helps to ensure that this information appears in a manner consistent with author intent.

The HTML-AAM is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

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/.

Note

This document is subject to change without notice.

This document was initially developed by and with the approval of the HTML Accessibility Taskforce, a joint task force of the Protocols and Formats Working Group and the HTML Working Group. Work continued with the successor groups Accessible Rich Internet Applications Working Group and the Web Applications Working Group. The document is now maintained solely by the Web Applications WG, formerly the Web Platform WG.

This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-webapps@w3.org (archives).

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 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 March 2019 W3C Process Document.

1. Introduction

This section is non-normative.

This specification defines how HTML user agents respond to and expose role, state and property information provided for Web content. Unless indicated otherwise, an HTML element or attribute with default Accessible Rich Internet Applications (WAI-ARIA) 1.0 semantics must be exposed to the platform accessibility APIs according to the relevant WAI-ARIA mappings defined in the Core Accessibility API Mappings 1.2 ([core-aam-1.2]) specification.

In some cases, often due to features of the HTML host language or the accessibility API in question, an element or attribute's mapping differs from the corresponding ARIA mappings specified in the [core-aam-1.2]. Where an HTML element or attribute does not have any default WAI-ARIA semantics, the applicable mapping for each platform accessibility API is defined by this specification.

This document also adapts the Accessible Name and Description Computation 1.1 ([accname-1.1]) for deriving the accessible names and accessible descriptions of [HTML] elements, and provides accessible implementation examples for specific HTML elements and features.

Users often access HTML content using assistive technologies that rely on platform accessibility API to obtain and interact with information from the page. This document is part of the following suite of accessibility API mapping specifications for content rendered by user agents:

1.1 Accessibility APIs

Accessibility APIs covered by this document are:

If user agent developers need to expose information using other accessibility APIs, it is recommended that they work closely with the developer of the platform where the API runs, and assistive technology developers on that platform.

For more information regarding accessibility APIs, refer to section 1.1 Accessibility APIs of the Core Accessibility API Mappings 1.2.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The classification of a section as normative or non-normative applies to the entire section and all sub-sections of that section.

Normative sections provide requirements that authors, user agents, and assistive technologies MUST follow for an implementation to conform to this specification.

Non-normative sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.

2.1 Deprecated

There are currently no deprecated requirements.

3. Important Terms

While some terms are defined in place, the following definitions are used throughout this document.

Accessibility API

Operating systems and other platforms provide a set of interfaces that expose information about objects and events to assistive technologies. Assistive technologies use these interfaces to get information about and interact with those widgets. Examples of accessibility APIs are Microsoft Active Accessibility [MSAA], Microsoft User Interface Automation [UI-AUTOMATION], MSAA with UIA Express [UIA-EXPRESS], the Mac OS X Accessibility Protocol [AXAPI], the Linux/Unix Accessibility Toolkit [ATK] and Assistive Technology Service Provider Interface [AT-SPI], and IAccessible2 [IAccessible2].

Accessibility Subtree

An accessible object in the accessibility tree and its descendants in that tree. It does not include objects which have relationships other than parent-child in that tree. For example, it does not include objects linked via aria-flowto unless those objects are also descendants in the accessibility tree.

Accessibility Tree

Tree of accessible objects that represents the structure of the user interface (UI). Each node in the accessibility tree represents an element in the UI as exposed through the accessibility API; for example, a push button, a check box, or container.

Accessible Description

An accessible description provides additional information, related to an interface element, that complements the accessible name. The accessible description might or might not be visually perceivable.

Accessible Name

The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element. See related accessible description.

A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g., "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.

Accessible object

A node in the accessibility tree of a platform accessibility API. Accessible objects expose various states, properties, and events for use by assistive technologies. In the context of markup languages (e.g., HTML and SVG) in general, and of WAI-ARIA in particular, markup elements and their attributes are represented as accessible objects.

Activation behavior

The action taken when an event, typically initiated by users through an input device, causes an element to fulfill a defined role. The role may be defined for that element by the host language, or by author-defined variables, or both. The role for any given element may be a generic action, or may be unique to that element. For example, the activation behavior of an HTML or SVG <a> element shall be to cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of specifying the browsing context for the traversal (such as the current window or tab, a named window, or a new window); the activation behavior of an HTML <input> element with the type attribute value submit shall be to send the values of the form elements to an author-defined IRI by the author-defined HTTP method.

Assistive Technologies

Hardware and/or software that:

  • relies on services provided by a user agent to retrieve and render Web content
  • works with a user agent or web content itself through the use of APIs, and
  • provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities

This definition may differ from that used in other documents.

Examples of assistive technologies that are important in the context of this document include the following:

  • screen magnifiers, which are used to enlarge and improve the visual readability of rendered text and images;
  • screen readers, which are most-often used to convey information through synthesized speech or a refreshable Braille display;
  • text-to-speech software, which is used to convert text into synthetic speech;
  • speech recognition software, which is used to allow spoken control and dictation;
  • alternate input technologies (including head pointers, on-screen keyboards, single switches, and sip/puff devices), which are used to simulate the keyboard;
  • alternate pointing devices, which are used to simulate mouse pointing and clicking.
Attribute

In this specification, attribute is used as it is in markup languages. Attributes are structural features added to elements to provide information about the states and properties of the object represented by the element.

Class

A set of instance objects that share similar characteristics.

Deprecated

A deprecated role, state, or property is one which has been outdated by newer constructs or changed circumstances, and which may be removed in future versions of the WAI-ARIA specification. User agents are encouraged to continue to support items identified as deprecated for backward compatibility. For more information, see Deprecated Requirements in the Conformance section.

Desktop focus event

Event from/to the host operating system via the accessibility API, notifying of a change of input focus.

Element

In this specification, element is used as it is in markup languages. Elements are the structural elements in markup language that contains the data profile for objects.

Event

A programmatic message used to communicate discrete changes in the state of an object to other objects in a computational system. User input to a web page is commonly mediated through abstract events that describe the interaction and can provide notice of changes to the state of a document object. In some programming languages, events are more commonly known as notifications.

Expose

Translated to platform-specific accessibility APIs as defined in the Core Accessibility API Mappings. [CORE-AAM-1.1]

Graphical Document

A document containing graphic representations with user-navigable parts. Charts, maps, diagrams, blueprints, and dashboards are examples of graphical documents. A graphical document is composed using any combination of symbols, images, text, and graphic primitives (shapes such as circles, points, lines, paths, rectangles, etc).

Hidden

Indicates that the element is not visible, perceivable, or interactive to any user. An element is considered hidden if it or any one of its ancestor elements is not rendered or is explicitly hidden.

Informative

Content provided for information purposes and not required for conformance. Content required for conformance is referred to as normative.

Keyboard Accessible

Accessible to the user using a keyboard or assistive technologies that mimic keyboard input, such as a sip and puff tube. References in this document relate to WCAG 2.1 Guideline 2.1: Make all functionality available from a keyboard [WCAG21].

Landmark

A type of region on a page to which the user may want quick access. Content in such a region is different from that of other regions on the page and relevant to a specific user purpose, such as navigating, searching, perusing the primary content, etc.

Live Region

Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere. These regions are not always updated as a result of a user interaction. This practice has become commonplace with the growing use of Ajax. Examples of live regions include a chat log, stock ticker, or a sport scoring section that updates periodically to reflect game statistics. Since these asynchronous areas are expected to update outside the user's area of focus, assistive technologies such as screen readers have either been unaware of their existence or unable to process them for the user. WAI-ARIA has provided a collection of properties that allow the author to identify these live regions and process them: aria-live, aria-relevant, aria-atomic, and aria-busy.

Primary Content Element

An implementing host language's primary content element, such as the body element in HTML.

Managed State

Accessibility API state that is controlled by the user agent, such as focus and selection. These are contrasted with "unmanaged states" that are typically controlled by the author. Nevertheless, authors can override some managed states, such as aria-posinset and aria-setsize. Many managed states have corresponding CSS pseudo-classes, such as :focus, and pseudo-elements, such as ::selection, that are also updated by the user agent.

Nemeth Braille

The Nemeth Braille Code for Mathematics is a braille code for encoding mathematical and scientific notation. See Nemeth Braille on Wikipedia.

Node

Basic type of object in the DOM tree or accessibility tree. DOM nodes are further specified as Element or Text nodes, among other types. The nodes of an accessibility tree are accessible objects.

Normative

Required for conformance. By contrast, content identified as informative or "non-normative" is not required for conformance.

Object

In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or more elements, and rendered by user agents.

In the context of programming, the instantiation of one or more classes and interfaces which define the general characteristics of similar objects. An object in an accessibility API may represent one or more DOM objects. Accessibility APIs have defined interfaces that are distinct from DOM interfaces.
Ontology

A description of the characteristics of classes and how they relate to each other.

Operable

Usable by users in ways they can control. References in this document relate to WCAG 2.1 Principle 2: Content must be operable [WCAG21]. See Keyboard Accessible.

Owned Element

An 'owned element' is any DOM descendant of the element, any element specified as a child via aria-owns, or any DOM descendant of the owned child.

Owning Element

An 'owning element' is any DOM ancestor of the element, or any element with an aria-owns attribute which references the ID of the element.

Perceivable

Presentable to users in ways they can sense. References in this document relate to WCAG 2.1 Principle 1: Content must be perceivable [WCAG21].

Property

Attributes that are essential to the nature of a given object, or that represent a data value associated with the object. A change of a property may significantly impact the meaning or presentation of an object. Certain properties (for example, aria-multiline) are less likely to change than states, but note that the frequency of change difference is not a rule. A few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often. See clarification of states versus properties.

Relationship

A connection between two distinct things. Relationships may be of various types to indicate which object labels another, controls another, etc.

Role

Main indicator of type. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.

Root WAI-ARIA node

The primary element containing non-metadata content. In many languages, this is the document element but in HTML, it is the <body>.

Semantics

The meaning of something as understood by a human, defined in a way that computers can process a representation of an object, such as elements and attributes, and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.

State

A state is a dynamic property expressing characteristics of an object that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities. See clarification of states versus properties.

Sub-document

Any document created from a <frame>, <iframe> or similar mechanism. A sub-document may contain a document, an application or any widget such as a calendar pulled in from another server. In the accessibility tree there are two accessible objects for this situation—one represents the <frame>/<iframe> element in the parent document, which parents a single accessible object child representing the spawned document contents.

Target Element

An element specified in a WAI-ARIA relation. For example, in <div aria-controls=”elem1”>, where “elem1” is the ID for the target element.

Taxonomy

A hierarchical definition of how the characteristics of various classes relate to each other, in which classes inherit the properties of superclasses in the hierarchy. A taxonomy can comprise part of the formal definition of an ontology.

Text node

Type of DOM node that represents the textual content of an attribute or an element. A Text node has no child nodes.

Tooltip attribute

Any host language attribute that would result in a user agent generating a tooltip such as in response to a mouse hover in desktop user agents.

Understandable

Presentable to users in ways they can construct an appropriate meaning. References in this document relate to WCAG 2.1 Principle 3: Information and the operation of user interface must be understandable [WCAG21].

User Agent

Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.

Valid IDREF

A reference to a target element in the same document that has a matching ID

Widget

Discrete user interface object with which the user can interact. Widgets range from simple objects that have one value or operation (e.g., check boxes and menu items), to complex objects that contain many managed sub-objects (e.g., trees and grids).

4. Mapping HTML to Accessibility APIs

4.1 General Rules for Exposing WAI-ARIA Semantics

Note

WAI-ARIA support was first introduced to HTML in [HTML5].

Where an HTML element or attribute has default WAI-ARIA semantics, it MUST be exposed to the platform accessibility APIs in a way that conforms to General rules for exposing WAI-ARIA semantics in the Core Accessibility API Mappings 1.2.

4.2 Conflicts Between Native Markup Semantics and WAI-ARIA

Where the host language is [HTML], user agents MUST conform to Conflicts between native markup semantics and WAI-ARIA in the Core Accessibility API Mappings 1.2.

4.3 Exposing HTML Features That Do Not Directly Map to Accessibility APIs

HTML may have features that are not supported by accessibility APIs at the time of publication. There is not a one to one relationship between all features and platform accessibility APIs. When HTML roles, states and properties do not directly map to an accessibility API, and there is a method in the API to expose a text string, user agents MUST expose the undefined role, states and properties via that method.

For HTML elements or attributes with default WAI-ARIA semantics, user agents MUST conform to Exposing attributes that do not directly map to accessibility API properties in the [core-aam-1.2].

4.3.1 Other Accessibility Implementations

Use of MSAA VARIANT by Some User Agents

In MSAA, the value of an accessible object's Role property is retrieved with the IAccessible::get_accRole method. This method returns a VARIANT that is limited to a finite number of integer role constants insufficient for describing the role of every HTML element, especially new elements introduced by HTML. To address this limitation, some user agents, e.g., Firefox and Chrome in cooperation with some screen readers, have elected to expose certain roles by returning a string value (BSTR) in that VARIANT in a way that is not described by the MSAA specification.

For example, Firefox returns the element's tag name as a BSTR for the following: abbr, address, aside, blockquote, canvas, caption, dd, div, figcaption, footer, form, h1h6, header, iframe, input type="file", main, menu, nav, output, p, pre, q, section, time.

Similarly, Chrome returns the element's tag name for: blockquote, div, dl, figcaption, form, h1h6, menu, meter, p, pre.

Use of the DOM by Some Assistive Technologies
Editor's note

to do

4.4 HTML Element Role Mappings

Notes:

4.5 HTML Attribute State and Property Mappings

Notes:

5. Accessible Name and Description Computation

The terms accessible name and accessible description are properties provided in all accessibility APIs. The name of the properties may differ across APIs but they serve the same function: as a container for a short (name) or longer (description) string of text.

The text alternative computation is used to generate both the accessible name and accessible description. There are different rules provided for several different types of elements, nodes, and combinations of markup.

5.1 input type="text", input type="password", input type="search", input type="tel", input type="url" and textarea Element

5.1.1 input type="text", input type="password", input type="search", input type="tel", input type="email", input type="url" and textarea Element Accessible Name Computation

  1. If the control has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
  3. If the accessible name is still empty, then: use the control's title attribute.
  4. Otherwise use the control's placeholder attribute.
  5. If none of the above yield a usable text string there is no accessible name.

5.1.2 input type="text", input type="password", input type="search", input type="tel", input type="email", input type="url" and textarea Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.2 input type="button", input type="submit" and input type="reset"

5.2.1 input type="button" , input type="submit" and input type="reset" Accessible Name Computation

  1. If the control has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the value attribute.
  3. For input type=submit: If steps 1 to 2 do not yield a usable text string, the accessible name is a localized string of the word "submit".
  4. For input type=reset: If steps 1 to 2 do not yield a usable text string, the accessible name is a localized string of the word "reset".
  5. Otherwise use title attribute.
  6. If none of the above yield a usable text string there is no accessible name.

5.2.2 input type="button" , input type="submit" and input type="reset" Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the value attribute if it wasn't used as the accessible name.
  3. Otherwise use the title attribute if it wasn't used as the accessible name.
  4. If none of the above yield a usable text string there is no accessible description.

5.3 input type="image"

5.3.1 input type="image" Accessible Name Computation

  1. If the control has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use alt attribute.
  3. Otherwise use title attribute.
  4. Otherwise the user agent may provide an accessible name via a localized string of the phrase "Submit Query".
  5. If none of the above yield a usable text string there is no accessible name.

5.3.2 input type="image" Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.4 button Element

5.4.1 button Element Accessible Name Computation

  1. If the button element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the button element subtree.
  3. Otherwise use title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.4.2 button Element Accessible Description Computation

  1. If the button has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.5 fieldset and legend Elements

5.5.1 fieldset Element Accessible Name Computation

  1. If the fieldset element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. If the accessible name is still empty, then: if the fieldset element has a child that is a legend element, then use the subtree of the first such element.
  3. If the accessible name is still empty, then:, if the fieldset element has a title attribute, then use that attribute.
  4. Otherwise, there is no accessible name.

5.5.2 fieldset Element Accessible Description Computation

  1. If the fieldset element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.6 output Element

5.6.1 output Element Accessible Name Computation

  1. If the output element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the output element subtree.
  3. Otherwise use title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.6.2 output Element Accessible Description Computation

  1. Use aria-describedby.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.7 Other Form Elements

5.7.1 Other Form Elements Accessible Name Computation

  1. If the control has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use label element.
  3. Otherwise use title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.7.2 Other Form Elements Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.8 summary Element

5.8.1 summary Element Accessible Name Computation

  1. If the first summary element, which is a direct child of the details element, has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use summary element subtree.
  3. Otherwise use title attribute.
  4. If there is no summary element as a direct child of the details element, the user agent should provide one with a subtree containing a localized string of the word "details".
  5. If there is a summary element as a direct child of the details element, but none of the above yield a usable text string, there is no accessible name.

5.8.2 summary Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use summary element subtree if not used as the accessible name.
  3. Otherwise use the title attribute if it wasn't used as the accessible name.
  4. If none of the above yield a usable text string there is no accessible description.

5.9 figure and figcaption Elements

5.9.1 figure Element Accessible Name Computation

  1. If the figure element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. If the accessible name is still empty, then: if the figure element has a child that is a figcaption element, then use the subtree of the first such element.
  3. If the accessible name is still empty, then: if the figure element has a title attribute, then use that attribute.
  4. Otherwise, there is no accessible name.

5.9.2 figure Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.10 img Element

5.10.1 img Element Accessible Name Computation

  1. If the img element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use alt attribute.
  3. Otherwise use title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.10.2 img Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.11 table Element

5.11.1 table Element Accessible Name Computation

  1. If the table element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. If the accessible name is still empty, then: if the table element has a child that is a caption element, then use the subtree of the first such element.
  3. If the accessible name is still empty, then: if the table element has a title attribute, then use that attribute.
  4. Otherwise, there is no accessible name.

5.11.2 table Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. If the accessible description is still empty, then:, if the table element has a child that is a caption element and it wasn't used as the accessible name, then use the subtree of the first such element.
  3. If the accessible description is still empty, then: if the table element has a title attribute and it wasn't used as the accessible name, then use that attribute.
  4. Otherwise, there is no accessible description.

5.12 Other Tabular data elements

5.12.1 tr, td, th Elements Accessible Name Computation

  1. If the table element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute.
  3. If none of the above yield a usable text string there is no accessible name.

5.12.2 tr, td, th Elements Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.13 a Element

5.13.1 a Element Accessible Name Computation

  1. If the a element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use a element subtree.
  3. Otherwise use the title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.13.2 a Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.14 area Element

5.14.1 area Element Accessible Name Computation

  1. If the area element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use area element's alt attribute.
  3. Otherwise use the title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.14.2 area Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.15 iframe Element

5.15.1 iframe Element Accessible Name Computation

  1. If the element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute.
  3. If none of the above yield a usable text string there is no accessible name.
Note

The document referenced by the src of the iframe element gets its name from that document's title element, like any other document. If there is no title provided, there is no accessible name.

5.15.2 iframe Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.16 Section Elements and Grouping Content Elements Not listed Elsewhere

5.16.1 Section and Grouping Element Accessible Name Computation

  1. If the element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute.
  3. If none of the above yield a usable text string there is no accessible name.

5.16.2 Section and Grouping Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

5.17 Text Level Elements Not Listed Elsewhere

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

5.17.1 Text Level Element Accessible Name Computation

  1. If the element has an aria-label or an aria-labelledby attribute the accessible name is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the text element's subtree.
  3. Otherwise use the title attribute.
  4. If none of the above yield a usable text string there is no accessible name.

5.17.2 Text Level Element Accessible Description Computation

  1. If the element has an aria-describedby attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
  2. Otherwise use the title attribute if it wasn't used as the accessible name.
  3. If none of the above yield a usable text string there is no accessible description.

6. Accessible Feature Implementation Examples

This section is non-normative.

6.1 summary and details Elements

6.1.1 Focus and Keyboard Interaction

The summary element should be focusable by default.

The details element should not be focusable by default.

Pressing the spacebar or enter keys when the summary element has focus will show the details element content if the content was hidden. If the details element content was showing and the summary element has focus, pressing the spacebar or enter keys will hide the details element content.

6.1.2 Role, Name, State and Property Mapping

The summary element should be mapped to a disclosure triangle role in accessibility APIs that have such a role. For example the Mac accessibility API includes the AXDisclosureTriangle role. In accessibility APIs that do not have such a fine grained role, the summary element should be mapped to a button role. The role mapping table contains recommended mappings for the summary element.

The default accessible name for the summary element is the text content of the summary element.

When the details element content is hidden, the state of the content should be reflected by an accessible state or property.

Example 1: In the Mac accessibility API on the summary element (AXDisclosureTriangle), set AXExpanded property to NO. When the details element content is shown, on the summary element (AXDisclosureTriangle), set the AXExpanded property to YES. The hidden and shown states of the details element content is reflected by the absence or presence of the open attribute.

Example 2: In the IA2 accessibility API on the summary element (ROLE_SYSTEM_PUSHBUTTON), set STATE_SYSTEM_COLLAPSED. When the details element content is shown, on the summary element (ROLE_SYSTEM_PUSHBUTTON), set STATE_SYSTEM_EXPANDED. The hidden and shown states of the details element content is reflected by the absence or presence of the open attribute.

6.2 The figure and figcaption Elements

Editor's note

to do

A. Appendices

A.1 Change Log

A.1.1 Substantive changes since moving entirely to the Web Application Working Group (formerly Web Platform WG) (01-Oct-2016)

  • 26-Nov-2019: Updates mappings for disabled, scope, spellcheck, tabindex to point to WAI-ARIA. Adds AX pattern, reversed, rows, size, span, src, start, step, type attribute mappings. Adds min-length, ping, playsinline, referrerpolicy, sizes, srcset, data[value] attribute mappings. See GitHub pull request #245.
  • 30-Sept-2019: Remove mappings for rb and rtc elements as they are marked as obsolete in HTML. See GitHub issue #115 and pull request #253.
  • 23-Sept-2019: Update attribute mappings for high, low, max, min, and meter and progress's value attribute. See GitHub pull request #244.
  • 18-Sept-2019: Update mark element's UIA LocalizedControlType and AX AXRoleDescription. See GitHub issue #236.
  • 18-Sept-2019: Update ATK mappings for summary and details elements. See GitHub issue #142 and GitHub issue #147.
  • 18-Sept-2019: Update MSAA mappings for sub and sup. See GitHub pull request #252.
  • 11-Sept-2019: Update mapping for menu to match HTML Living Standard. Remove element and attribute mappings that are not applicable to menu and menuitem. Update mapping of menu to role="list". See GitHub issue #188.
  • 10-July-2019: Further updated mappings for ins and del elements. See GitHub pull request #219.
  • 13-June-2019: Update mappings for ins and del elements. See GitHub issue #141.
  • 10-June-2019: Update ATK mappings for header and footer when not scoped to the body. See GitHub issue #129.
  • 21-May-2019: Update AXAPI mappings for map element. Add accessible name and description computation for area. See GitHub issue #176.
  • 11-Apr-2019: Update UIA mappings for sub and sup elements. See Pull request #177.
  • 20-Mar-2019: Updated IA2 mappings for sup and sub elements. See GitHub issue #174.
  • 26-Feb-2019: Updated mappings for the address element. See GitHub issue #170.
  • 19-Feb-2019: Added placeholder attribute to accessible name computation for various input elements. See GitHub issue #167.
  • 07-Feb-2018: Added entries for the rb and rtc elements, and updated AXAPI mappings for the rb, rt and ruby elements. See GitHub issue #115.
  • 07-Feb-2018: Updated mappings for the svg element. See GitHub issue #43.
  • 07-Feb-2018: Updated AXAPI mappings for the del and ins elements, and the datetime attribute.
  • 07-Feb-2018: Aligned mappings with CORE-AAM as appropriate for header and footer when scoped to body, aside, and output. See GitHub issue #119.
  • 07-Feb-2018: Updated ATK and AX mappings for the multiple attribute on input element. See GitHub issue #96.
  • 07-Feb-2018: Updated ATK mappings for the sub and sup elements. See GitHub issue #121.
  • 07-Feb-2018: Updated mappings for the body element. See GitHub issue #117.
  • 01-Feb-2018: Updated IA2 mapping for the meter element. See GitHub issue #2.
  • 29-Jan-2018: Updated heading mapping to reflect implementations. See GitHub issue #116.
  • 23-Jan-2018: Added note regarding effect of some CSS properties. See GitHub issue #234.
  • 23-Jan-2018: Updated mappings for the address element. See GitHub issue #33.
  • 23-Jan-2018: Updated mappings for the dt element. See GitHub issue #78.
  • 23-Jan-2018: Updated AXAPI mappings for the mark element.
  • 08-Jan-2018: Updated mappings for the input element with the type attribute in the Color state. See GitHub issue #48.
  • 06-Jan-2018: Updated IA2 mappings for the pre, q, and ruby elements, and the multiple attribute for the input element. See GitHub issue #94.
  • 18-Dec-2017: Rewrote first paragraph in Introduction to better reflect the relationship between the HTML-AAM and CORE-AAM specifications. See GitHub issue #66.
  • 18-Dec-2017: Updated readonly attribute to use aria-readonly="true" WAI-ARIA mappings. See GitHub issue #93.
  • 08-Dec-2017: Changed AXAPI mapping for the canvas element from AXImage to AXGroup.
  • 01-Dec-2017: Updated mappings for the dfn element. See GitHub issue #6.
  • 30-Nov-2017: Updated mappings for the meter element. See GitHub issue #2.
  • 24-Nov-2017: Updated mappings for the audio and video elements. See GitHub issue #80.
  • 23-Nov-2017: Updated figure element mappings to reflect the WAI-ARIA figure role mappings.
  • 23-Nov-2017: Updated mappings for the form element based on presence of accessible name. See GitHub issue #106.
  • 23-Nov-2017: Removed the accessible name computation requirement to ignore an img element's title attribute when the element's alt attribute is empty. See GitHub issue #99.
  • 23-Nov-2017: Added note to not expose aria-roledescription unless element also a conforming role attribute value. See GitHub issue #98.
  • 09-Aug-2017: Updated mappings for the type attribute on the ol element. See GitHub issue #91.
  • 25-July-2017: Updated UIA mappings for multiple elements and attributes. See GitHub issue #95 and GitHub pull request #101.
  • 02-June-2017: Updated AXAPI mappings for title attribute on abbr element, and abbr attribute on th element. See GitHub issue #16.
  • 31-May-2017: Updated mappings for hidden attribute. See GitHub issue #38.
  • 24-May-2017: Updated mappings for selected attribute. See GitHub issue #92.
  • 01-May-2017: Updated AXAPI mapping for time element. See GitHub issue #88.
  • 27-Apr-2017: Updated UIA mappings for lang and dir attributes. See GitHub issue #19.
  • 19-Apr-2017: Updated mapping for colspan and rowspan attributes. See GitHub issue #56 and issue #57.
  • 03-Apr-2017: Updated mapping for section element. See GitHub issue #79.
  • 23-Dec-2016: No mapping for datalist element if not linked with input element. See GitHub issue #26.
  • 23-Dec-2016: Updated IA2 mapping for list attribute. See GitHub issue #21.
  • 22-Dec-2016: Sync mappings for footer and header elements. See GitHub issue #59.
  • 22-Dec-2016: Updated IA2 mapping for input@type='date' attribute. See GitHub issue #61.
  • 22-Dec-2016: Updated IA2 mapping for input@type='file' element. See GitHub issue #62.
  • 22-Dec-2016: Updated IA2 mapping for summary element. See GitHub issue #64.
  • 14-Dec-2016: Updated wording distinguishing when header and footer elements are or are not ARIA landmarks. See GitHub issue #65.
  • 07-Dec-2016: Modified aria-multiselectable mapping for datalist to reflect listbox selection model. See GitHub issue #71.
  • 07-Dec-2016: Mappings for the multiple attribute on input and select elements. See GitHub issue #72.
  • 27-Nov-2016: Added implementation rules for the checked, contenteditable, disabled, and indeterminate attributes.
  • 21-Nov-2016: Removed placeholder attribute from accessible description computation for various input elements.

A.2 Acknowledgments

This section is non-normative.

The following people contributed to the development of this document.

A.2.1 Participants active in the HTML Accessibility Task Force active at the time of publication

A.2.2 Enabling funders

This publication has been funded in part with U.S. Federal funds from the Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR), initially under contract number ED-OSE-10-C-0067 and currently under contract number HHSP23301500054C. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

B. References

B.1 Normative references

[AT-SPI]
Assistive Technology Service Provider Interface. The GNOME Project. URL: https://developer.gnome.org/libatspi/stable/
[ATK]
ATK - Accessibility Toolkit. The GNOME Project. URL: https://developer.gnome.org/atk/stable/
[AXAPI]
The Mac OS X Accessibility Protocol Mac OS 10.10. Apple Corporation. URL: https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Protocols/NSAccessibility_Protocol/index.html
[CORE-AAM-1.1]
Core Accessibility API Mappings 1.1. Joanmarie Diggs; Joseph Scheuhammer; Richard Schwerdtfeger; Michael Cooper; Andi Snow-Weaver; Aaron Leventhal. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/core-aam-1.1/
[core-aam-1.2]
Core Accessibility API Mappings 1.2. Joanmarie Diggs; Michael Cooper; Richard Schwerdtfeger; Joseph Scheuhammer; Andi Snow-Weaver; Aaron Leventhal; Melanie Richards; James Craig; Alexander Surkov. W3C. 18 December 2018. W3C Working Draft. URL: https://www.w3.org/TR/core-aam-1.2/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[IAccessible2]
IAccessible2. Linux Foundation. URL: https://www.linuxfoundation.org/collaborate/workgroups/accessibility/iaccessible2
[MSAA]
Microsoft Active Accessibility (MSAA) 2.0. Microsoft Corporation. URL: https://msdn.microsoft.com/en-us/library/ms697707.aspx
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[UI-AUTOMATION]
UI Automation. Microsoft Corporation. URL: https://msdn.microsoft.com/en-us/library/ee684009%28v=vs.85%29.aspx
[UIA-EXPRESS]
The IAccessibleEx Interface. Microsoft Corporation. URL: https://msdn.microsoft.com/en-us/library/windows/desktop/dd561898%28v=vs.85%29.aspx
[WAI-ARIA]
Accessible Rich Internet Applications (WAI-ARIA) 1.0. James Craig; Michael Cooper et al. W3C. 20 March 2014. W3C Recommendation. URL: https://www.w3.org/TR/wai-aria/
[wai-aria-1.1]
Accessible Rich Internet Applications (WAI-ARIA) 1.1. Joanmarie Diggs; Shane McCarron; Michael Cooper; Richard Schwerdtfeger; James Craig. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/wai-aria-1.1/
[WCAG21]
Web Content Accessibility Guidelines (WCAG) 2.1. Andrew Kirkpatrick; Joshue O Connor; Alastair Campbell; Michael Cooper. W3C. 5 June 2018. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/

B.2 Informative references

[accname-1.1]
Accessible Name and Description Computation 1.1. Joanmarie Diggs; Bryan Garaventa; Michael Cooper. W3C. 18 December 2018. W3C Recommendation. URL: https://www.w3.org/TR/accname-1.1/
[HTML5]
HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[svg-aam-1.0]
SVG Accessibility API Mappings. Amelia Bellamy-Royds; Ian Pouncey. W3C. 10 May 2018. W3C Working Draft. URL: https://www.w3.org/TR/svg-aam-1.0/