Copyright © 2015-2019 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
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/.
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.
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:
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 [core-aam-1.2].
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.
There are currently no deprecated requirements.
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.
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.
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].
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, h1–h6, 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, h1-h6, menu, meter, p, pre.
to do
Notes:
aria-roledescription
property value in the accessibility tree unless the element has an explicit, conforming role
attribute value.label
element's for
attribute, or a descendant of a label
element, the labelable element's UIA LabeledBy
property points to the UIA element for the label
element.Text
Control Type are not generally represented as accessible objects in the accessibility tree, but are just part of the Text
Control Pattern implemented for the whole HTML document. However, if they have any aria-
attributes or an explicit tabindex
specified, elements mapped to the Text
Control Type will be represented as accessible objects in the accessibility tree.Notes:
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.
input type="text"
, input type="password"
, input type="search"
, input type="tel"
, input type="url"
and textarea
Elementinput type="text"
, input type="password"
, input type="search"
, input type="tel"
, input type="email"
, input type="url"
and textarea
Element Accessible Name Computationaria-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.
label
element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
title
attribute.placeholder
attribute.input type="text"
, input type="password"
, input type="search"
, input type="tel"
, input type="email"
, input type="url"
and textarea
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
input type="image"
input type="image"
Accessible Name Computationaria-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.
alt
attribute.title
attribute.input type="image"
Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
fieldset
and legend
Elementsfieldset
Element Accessible Name Computationfieldset
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.
fieldset
element has a child that is a legend
element, then use the subtree of the first such element.
fieldset
element has a title
attribute, then use that attribute.
fieldset
Element Accessible Description Computationfieldset
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.
title
attribute if it wasn't used as the accessible name.
output
Elementoutput
Element Accessible Name Computationoutput
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.
output
element subtree.title
attribute.output
Element Accessible Description Computationaria-describedby
.title
attribute if it wasn't used as the accessible name.
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.
label
element.title
attribute.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.
title
attribute if it wasn't used as the accessible name.
summary
Elementsummary
Element Accessible Name Computationsummary
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.
summary
element subtree.title
attribute.summary
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
summary
element subtree if not used as the accessible name.
title
attribute if it wasn't used as the accessible name.
figure
and figcaption
Elementsfigure
Element Accessible Name Computationfigure
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.
figure
element has a child that is a figcaption
element, then use the subtree of the first such element.
figure
element has a title
attribute, then use that attribute.
figure
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
img
Elementimg
Element Accessible Name Computationimg
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.
alt
attribute.title
attribute.img
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
table
Elementtable
Element Accessible Name Computationaria-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.
table
element has a child that is a caption
element, then use the subtree of the first such element.
table
element has a title
attribute, then use that attribute.
table
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
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.
table
element has a title
attribute and it wasn't used as the accessible name, then use that attribute.
tr
, td
, th
Elements Accessible Name Computationaria-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.
title
attribute.tr
, td
, th
Elements Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
a
Elementa
Element Accessible Name Computationa
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.
a
element subtree.title
attribute.a
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
area
Elementarea
Element Accessible Name Computationarea
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.
area
element's alt
attribute.title
attribute.area
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
iframe
Elementiframe
Element Accessible Name Computationaria-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.
title
attribute.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.
iframe
Element Accessible Description Computationaria-describedby
attribute the accessible description is to be calculated using the algorithm defined in Accessible Name and Description: Computation and API Mappings 1.1.
title
attribute if it wasn't used as the accessible name.
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.
title
attribute.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.
title
attribute if it wasn't used as the accessible name.
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
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.
title
attribute.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.
title
attribute if it wasn't used as the accessible name.
This section is non-normative.
summary
and details
ElementsThe summary
element should be focusable by default.
The details
element should not be focusable by default.
Pressing the spacebar or enter key when the summary
element has focus will show the details
element content if the content is hidden. If the details
element content is showing and the summary
element has focus, pressing the spacebar or enter key will hide the details element content.
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 theAXExpanded
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.
figure
and figcaption
Elementsto do
map
element. Add accessible name and description computation for area
. See GitHub issue #176.sub
and sup
elements. See Pull request #177.sup
and sub
elements. See GitHub issue #174.address
element. See GitHub issue #170.placeholder
attribute to accessible name computation for various input
elements. See GitHub issue #167.rb
and rtc
elements, and updated AXAPI mappings for the rb
, rt
and ruby
elements. See GitHub issue #115.svg
element. See GitHub issue #43.del
and ins
elements, and the datetime
attribute.header
and footer
when scoped to body
, aside
, and output
. See GitHub issue #119.multiple
attribute on input
element. See GitHub issue #96.sub
and sup
elements. See GitHub issue #121.body
element. See GitHub issue #117.meter
element. See GitHub issue #2.address
element. See GitHub issue #33.dt
element. See GitHub issue #78.mark
element.input
element with the type
attribute in the Color state. See GitHub issue #48.pre
, q
, and ruby
elements, and the multiple
attribute for the input
element. See GitHub issue #94.readonly
attribute to use aria-readonly="true"
WAI-ARIA mappings. See GitHub issue #93.canvas
element from AXImage
to AXGroup
.dfn
element. See GitHub issue #6.meter
element. See GitHub issue #2.audio
and video
elements. See GitHub issue #80.figure
element mappings to reflect the WAI-ARIA figure
role mappings.form
element based on presence of accessible name. See GitHub issue #106.img
element's title
attribute when the element's alt
attribute is empty. See GitHub issue #99.aria-roledescription
unless element also a conforming role
attribute value. See GitHub issue #98.type
attribute on the ol
element. See GitHub issue #91.title
attribute on abbr
element, and abbr
attribute on th
element. See GitHub issue #16.hidden
attribute. See GitHub issue #38.selected
attribute. See GitHub issue #92.time
element. See GitHub issue #88.lang
and dir
attributes. See GitHub issue #19.colspan
and rowspan
attributes. See GitHub issue #56 and issue #57.section
element. See GitHub issue #79.datalist
element if not linked with input
element. See GitHub issue #26.list
attribute. See GitHub issue #21.footer
and header
elements. See GitHub issue #59.input@type='date'
attribute. See GitHub issue #61.input@type='file'
element. See GitHub issue #62.summary
element. See GitHub issue #64.header
and footer
elements are or are not ARIA landmarks. See GitHub issue #65.aria-multiselectable
mapping for datalist
to reflect listbox selection model. See GitHub issue #71.multiple
attribute on input
and select
elements. See GitHub issue #72.checked
, contenteditable
, disabled
, and indeterminate
attributes.placeholder
attribute from accessible description computation for various input
elements.This section is non-normative.
The following people contributed to the development of this document.
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.