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. 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.
Publication as a Working Draft does not
imply endorsement by W3C and its Members.
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.
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.
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:
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.
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, MUST NOT, and SHOULD 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. Mapping HTML to Accessibility APIs
3.1 General Rules for Exposing WAI-ARIA Semantics
Note
WAI-ARIA support was first introduced to HTML in [HTML5].
3.3 Exposing HTML Features That Do Not Directly Map to Accessibility APIs
HTML can include 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.
HTML elements with implicit WAI-ARIA role semantics MUST be mapped to platform accessibility APIs according to the identified WAI-ARIA role mapping as defined in the [core-aam-1.2] specification.
"Not mapped" means the element does not need to be exposed via an accessibility API. This is usually because the element is not displayed as part of the user interface. However, authors can force some of these elements to be rendered. For instance, by overriding user agent styles to render elements that would have been otherwise set to display: none. In these cases, the user agent SHOULD map such elements to the role of generic.
Where an element is indicated as having "No corresponding (WAI-ARIA) role", or is mapped to the generic role, user agents MUST NOT expose the aria-roledescription property value in the accessibility tree unless the element has an explicit, conforming role attribute value which [WAI-ARIA-1.2] does not prohibit the use of aria-roledescription.
IAccessible2:
All elements with accessible objects should implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.
UIA:
When a labelable element is referenced by a 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.
Elements mapped to the 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.
AXAPI:
User agents should return a user-presentable, localized string value for the Mac Accessibility AXRoleDescription.
Note: If the controls attribute is present, UI controls (e.g., play, volume) are exposed as children of the audio element in the accessibility tree, and mapped as appropriate for the type of control (e.g., button or slider).
Text objects associated with loading or error messages, and any UI control not currently displayed, MAY be present in the accessibility tree and marked as hidden or off-screen.
Note: If the controls attribute is present, UI controls (e.g., play, volume) are exposed as descendants of an accessible object with a role of toolbar, and mapped as appropriate for the type of control (e.g., button or slider).
listbox role, with the aria-multiselectable property set to "true" if the datalist's selection model allows multiple option elements to be selected at a time, and "false" otherwise
If an hgroup contains multiple heading elements, then the heading element with the highest priority level
MAY be treated as the sole heading of the hgroup. All other heading elements MAY instead be exposed as if they
were p elements. See paragraph role on Core AAM.
If implemented as a color picker, any UI controls presented for selecting a color are exposed in the accessibility tree, associated with the input element, and mapped as appropriate for the type of control (e.g. button or slider).
Role:ROLE_SYSTEM_SPINBUTTON if implemented as a simple widget; ROLE_SYSTEM_GROUPING with child controls mapped as appropriate if implemented as a complex widget
Role:ATK_ROLE_SPINBUTTON
if implemented as a simple widget.
If implemented as a complex widget use: Role:ROLE_PANEL and map child controls as appropriate.
No accessible object. Styles used are exposed by UIA text attribute identifiers of the TextRange Control Pattern implemented on a parent accessible object.
Relations:IA2_RELATION_LABEL_FOR with a labelable element
that is child to the label or referred to by the label element's for attribute.
The associated labelable element has IA2_RELATION_LABELLED_BY pointing to the label.
When the label element contains a labelable element, the LabeledBy property for
the element points to the UIA element for the label element.
When the label element has a for attribute referencing a
labelable element, the LabeledBy property for the referenced element points to
the UIA element for the label element.
Relations:ATK_RELATION_LABEL_FOR for a child labelable element or
labelable element referred by for attribute.
Note, related labelable element provides ATK_RELATION_LABELLED_BY pointing to the label.
listitem role with
aria-setsize value reflecting number of
li elements within the parent ol, menu or ul
and aria-posinset
value reflecting the li elements position within the set.
If li element is not a child of ol , menu or ul, or if the containing
list element is no longer exposed with a list role, then expose the li element with a generic role.
Role:AXImageMap if used as an image map. Otherwise, Role:AXGroup if associated with an img with no alt. Otherwise,
not mapped if not associated with an img.
The menu element is a semantic alternative to the ul element.
It has no implemented mappings or behavior that reflect the semantics of the ARIA
menu role.
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
Note: There are instances where CSS properties can affect what is exposed by accessibility APIs.
For instance, display: none or visibility: hidden will remove an element from the accessibility tree
and hide its presence from assistive technologies.
If a summary element is not a child of a details element, or it is not the first summary element of a parent details,
then the summary element MUST be exposed with a generic role.
No accessible object. Styles used are exposed by UIA text attribute identifiers of the TextRange Control Pattern implemented on a parent accessible object.
Note: If the controls attribute is present, UI controls (e.g., play, volume) are exposed as children of the video element in the accessibility tree, and mapped as appropriate for the type of control (e.g., button or slider).
Text objects associated with loading or error messages, and any UI control not currently displayed, MAY be present in the accessibility tree and marked as hidden or off-screen.
Note: If the controls attribute is present, UI controls (e.g., play, volume) are exposed as descendants of an accessible object with a role of toolbar, and mapped as appropriate for the type of control (e.g., button or slider).
HTML attributes with default WAI-ARIA state and property semantics MUST be mapped to platform accessibility APIs according to those WAI-ARIA state and property mappings as defined in the [core-aam-1.2] specification.
A '?' in a cell indicates the data has yet to be provided.
"Not mapped" (Not Applicable) means the attribute does not need to be exposed via an accessibility API. This is usually because the attribute is not displayed as part of the user interface.
Note
In some cases, while not directly exposed to accessibility APIs, an attribute can still impact the accessibility of an element. e.g., autoplay will automatically start playing video or audio elements.
All elements having an accessible object in IAccessible2 mapping are supposed to implement IAccessible, IAccessible2 and IAccessible2_2 interfaces.
If the element includes both autocomplete and aria-autocomplete attributes with valid values,
User Agents MUST expose only the autocomplete attribute value. The aria-autocomplete attribute is
not valid on a form element.
If the element includes both autocomplete and aria-autocomplete attributes with valid values,
User Agents MUST expose only the autocomplete attribute value.
If an input element in the checkbox or radio state includes both the checked attribute and the aria-checked attribute with a
valid value, User Agents MUST expose only the checked attribute value.
An input element in the checkbox or radio state without a checked attribute has an implicit "false" state.
User Agents MUST ignore an aria-checked attribute which conflicts with the native element's implicit checked state.
If the element is in the editable state, the following mappings apply to the element and every nested accessible object with the
exception of those which have been specified in the false state.
States:IA2_STATE_EDITABLE and IA2_STATE_MULTI_LINE
Interfaces:IAccessibleEditableText
If the element is in the false state: not mapped.
If the element is in the inherit state: match the editable state of its parent element.
If the element is in the editable state, the following mappings apply to the element and every nested accessible object with the
exception of those which have been specified in the false state.
Control Pattern:TextEdit
Property:AriaProperties.multiline:true
If the element is in the false state: not mapped.
If the element is in the inherit state: match the editable state of its parent element.
If the element is in the editable state, the following mappings apply to the element and every nested accessible object with the
exception of those which have been specified in the false state.
States:ATK_STATE_EDITABLE and ATK_STATE_MULTI_LINE
Interfaces:AtkEditableText
If the element is in the false state: not mapped.
If the element is in the inherit state: match the editable state of its parent element.
If the element has both the disabled attribute and the aria-disabled attribute with a valid value,
User Agents MUST expose only the disabled attribute value.
Form controls within a valid legend child element of a fieldset with a disabled attribute
do not become disabled.
If the element has both the disabled attribute and the aria-disabled attribute with a valid value,
User Agents MUST expose only the disabled attribute value.
When the label element has a for attribute referencing another labelable element,
the LabeledBy property for the referenced element points to the UIA element for the label element.
Links the cell to its row and column header cells
(note, only one row and one column header cells can be exposed because of API restrictions).
See atk_table_get_row_header and atk_table_get_column_header.
aria-hidden="true" if the element retains its user agent default styling of display: none. Otherwise, if no other method for hiding the content is used (e.g., visibility: hidden) then it is not mapped.
Creates a link accessible object. For details, refer to
a and area element mappings. The value of the href attribute is stored in the Value.Value UIA property.
The value of the lang attribute is exposed as a locale identifier by Culture property of the UIA element representing the HTML element, and by Culture attribute of the TextRange Control Pattern implemented on a parent accessible object.
The open attribute's value is irrelevant. When the open attribute is not specified the default user agent styling for a dialog is display: none.
Authors can reveal a dialog through the style layer by modifying its display property. If revealed this way then the dialog is aria-modal="false" and aria-hidden="false".
When the placeholder and aria-placeholder attributes are both present, and the placeholder attribute's value is non-empty, user agents MUST expose the value of the placeholder attribute, and ignore aria-placeholder. If the placeholder attribute's value is empty, then user agents MUST expose the value of the aria-placeholder attribute.
If the element includes both the readonly attribute and the aria-readonly attribute with a valid value, User Agents MUST expose only the readonly attribute value.
If the element includes both the required attribute and the aria-required attribute with a valid value, User Agents MUST expose only the required attribute value.
If an element is required, user agents MUST NOT expose the
element with an intitial invalid state (aria-invalid="true").
The user agent SHOULD expose the invalid state only after 1) a user has purposefully interacted with a required element,
or attempted to submit a form and 2) the element, or elements, do not meet
constraint validation.
Until these conditions are met, user agents MUST expose the elements as
(aria-invalid="false").
If the element includes both the selected attribute and the aria-selected attribute with a valid value, User Agents MUST expose only the selected attribute value.
For input elements that allow the size attribute, the attribute will modify their default width. A width provided by CSS will negate the effects of the size attribute on these input elements.
Defines the list item marker, which is exposed as content in AXValue, and rendered as an accessible object:
AXRole:AXListMarker
AXSubrole:(nil)
AXRoleDescription:"list marker"
Comments
Some platforms (IAccessible2, ATK, UIA) do not expose an accessible object for the list item marker, whether it was created and then pruned from the accessibility tree, or never created in the first place. Instead, they expose the list item marker as part of the associated list item's accessible text. In these cases, implementors need to consider such things as adjusting the offsets (e.g., for caret-moved events, text-selection events, etc.) for the updated list item text that now also contains the list item marker as content, rather than just taking the offsets unmodified from the list item renderer.
Expose the value of the value attribute as the first text node in the list item.
If the value of the value attribute is an integer, set the UIA PositionInSet property to the integer value.
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.
Otherwise use the associated label element or elements accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
If the accessible name is still empty, then: use the control's title attribute.
Otherwise use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Otherwise use the value attribute.
For input type=submit and type=reset: if the prior steps do not yield a usable text string, and the value attribute is unspecified use the
implementation defined string respective to the input type.
Otherwise, if the control still has no accessible name use title attribute.
If none of the above yield a usable text string there is no accessible name.
4.1.3 input type="image" Accessible Name Computation
Otherwise use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Otherwise use alt attribute if present and its value is not the empty string.
Otherwise use title attribute if present and its value is not the empty string.
Otherwise if the previous steps do not yield a usable text string, use the
implementation defined string respective to the input type (an input in the image state
represents a submit button). For instance, a localized string of the word "submit" or the words "Submit Query".
If none of the above yield a usable text string there is no accessible name.
Otherwise use the associated label element(s) accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Otherwise use the button element subtree.
Otherwise use title attribute.
If none of the above yield a usable text string there is no accessible name.
4.1.5 fieldset Element Accessible Name Computation
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.
If the accessible name is still empty, then:, if the fieldset element has a title attribute, then use that attribute.
Otherwise use the associated label element or elements accessible name(s) - if more than one label is associated; concatenate by DOM order, delimited by spaces.
Otherwise use title attribute.
If none of the above yield a usable text string there is no accessible name.
4.1.7 Other Form Elements Accessible Name Computation
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".
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.
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.
If the accessible name is still empty, then: if the figure element has a title attribute, then use that attribute.
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.
If the accessible name is still empty, then: if the table element has a title attribute, then use that attribute.
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.
4.1.16 Section and Grouping Element Accessible Name Computation
an input element whose type attribute is the button, submit or reset state, and it has a value attribute, then use the flat string
of the attribute if it was not used as the accessible name.
Otherwise, use the flat string of the title attribute if it was not used as the accessible name for the element.
In accordance with Web Platform Design Principles, this specification provides no programmatic
interface to determine if information is being used by Assistive Technologies. However, this specification does allow an author to present different information to users of Assistive
Technologies from the information available to users who do not use Assistive Technologies. This is possible using many features of the ARIA and CORE-AAM specifications, just as this is
possible using many other parts of the web technology stack. This content disparity could be abused to perform
active fingerprinting of users of Assistive Technologies.
6. Security considerations
This specification introduces no new security considerations.
09-Oct-2023: Acknowledge use of hr element within select element. See GitHub PR 504.
03-Oct-2023: Update image mappings to reference the primary synonym roles (image and none). See GitHub PR 498.
03-Oct-2023: Clarify when to expose required field as invalid. See GitHub PR 429.
06-Jun-2023: Add computed roles for all HTML elements. See GitHub PR 465.
28-Mar-2023: Add inert attribute mapping. See GitHub PR 410.
24-Mar-2023: Add search element and its mappings. See GitHub PR 355.
08-Mar-2023: Update hgroup element to be mapped to role=group. See GitHub PR 398.
08-Mar-2023: Clarify naming algorithm for output element. See GitHub PR 402.
12-Dec-2022: Revise mapping for s element to be role=deletion. See GitHub PR 442.
28-Nov-2022: Simplify accessible description computation section. See GitHub PR 444.
19-Jul-2022: Update address element to be mapped to role=group. See GitHub PR 420.
03-Apr-2022: Update aside mappings based on its nesting context. See GitHub PR 350.
06-Mar-2022: Update the following elements to map to the generic role: a no href, footer not scoped to body, header not scoped to body, samp, span. See GitHub PR 364.
06-Feb-2022: Update mark to point to Core AAM mapping for the role. See GitHub Issue 316.
02-Nov-2021: Updating blockquote, caption, code, del, em, ins, meter, paragraph, strong, sub, sup and time to ARIA 1.2 mappings in Core AAM. Fix body mapping to generic, and html mapping to document. Fix hgroup mapping to generic. Update details to map to group with additional information specific to ATK, UIA. See GitHub issue #348
12-May-2021: Add FACES references to attributes table - readonly, name, form, disabled. See Issue 257.
12-Dec-2019: Adds hgroup, slot, autonomous custom element and form associated custom element. See GitHub issue #189.
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.
Substantive changes since moving to the Web Application Working Group (formerly Web Platform WG) (01-Oct-2016)
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.
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.
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: 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.
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, then under contract number HHSP23301500054C, and now under HHS75P00120P00168. 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.