Publication as an Editor's Draft does not imply endorsement byW3C 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 a work in progress.
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 wordsMAY,MUST,MUST NOT, andSHOULD in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Normative sections provide requirements that user agents and assistive technologiesMUST follow for an implementation to conform to this specification.
Non-normative (informative) 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.
When these conditions are met, user agentsMUST expose an object using the mappings defined in CORE-AAM for the specified minimum role. If the element has multiple attributes specified which require a minimum role be returned as the computed role for the element, prioritize the more specific role in the ARIA taxonomy.
"Not mapped" means the element does not need to be exposed via anaccessibilityAPI. 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 todisplay: none. In these cases, the user agentSHOULD map such elements to the role ofgeneric, unless otherHTML features have been specified which would require a more specificminimum role to be exposed.
All elements with accessible objectsSHOULD implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.
UIA:
When alabelable element is referenced by alabel element'sfor attribute, or a descendant of alabel element, the labelable element's UIALabeledBy property points to the UIA element for thelabel element.
User agentsMAY still expose ana element lacking thehref attribute with alink role in the event an author specifies interactive behavior for the element. For example, if using anevent handler attribute.
Note: If thecontrols attribute is present, UI controls (e.g., play, volume) are exposed as children of theaudio element in theaccessibility tree, and mapped as appropriate for the type of control (e.g.,button orslider).
User agentsMAY include the following in theaccessibility tree and mark them as hidden or off-screen:
Note: If thecontrols attribute is present, UI controls (e.g., play, volume) are exposed as descendants of anaccessible object with a role oftoolbar, and mapped as appropriate for the type of control (e.g.,button orslider).
listbox role, with thearia-multiselectable property set to "true" if thedatalist's selection model allows multipleoption elements to be selected at a time, and "false" otherwise
If anhgroup contains multiple heading elements, then the user agentMAY treat the heading element with the highest priority level as the sole heading of thehgroup. The user agentMAY expose all other heading elements as if they werep elements. Seeparagraph role on Core AAM.
If animg has an emptyalt, but has been provided anaccessible name via another valid naming mechanism per thenaming steps of this specification, user agents will expose the element with its implicitimage role.
If implemented as a color picker, any UI controls presented for selecting a color are exposed in theaccessibility tree, associated with theinput element, and mapped as appropriate for the type of control (e.g., button or slider).
Role:ROLE_SYSTEM_SPINBUTTON if implemented as a simplewidget;ROLE_SYSTEM_GROUPING with child controls mapped as appropriate if implemented as a complexwidget
Role:ATK_ROLE_SPINBUTTON if implemented as a simplewidget. If implemented as a complexwidget use: Role:ROLE_PANEL and map child controls as appropriate.
No accessible object. Styles used are exposed by UIA text attribute identifiers of theTextRange Control Pattern implemented on a parent accessible object.
Relations:IA2_RELATION_LABEL_FOR with alabelable element that is child to thelabel or referred to by thelabel element'sfor attribute. The associated labelable element hasIA2_RELATION_LABELLED_BY pointing to thelabel.
When thelabel element contains alabelable element, theLabeledBy property for the element points to the UIA element for thelabel element.
When thelabel element has afor attribute referencing alabelable element, theLabeledBy property for the referenced element points to the UIA element for thelabel element.
Relations:ATK_RELATION_LABEL_FOR for a childlabelable element or labelable element referred byfor attribute. Note, related labelable element providesATK_RELATION_LABELLED_BY pointing to thelabel.
listitem role witharia-setsize value reflecting number ofli elements within the parentol,menu orul andaria-posinset value reflecting theli elements position within the set.
Ifli element is not a child ofol ,menu orul, or if the containing list element is no longer exposed with alist role, then expose theli element with ageneric role.
Role:AXImageMap if used as an image map. Otherwise, Role:AXGroup if associated with animg with noalt. Otherwise, not mapped if not associated with animg.
Themenu element is a semantic alternative to theul element. It has no implemented mappings or behavior that reflect the semantics of the ARIAmenu role.
progressbar role, with, if the progress bar is determinate, thearia-valuemax property set to the maximum value of the progress bar, thearia-valuemin property set to zero, and thearia-valuenow property set to the current value of the progress bar
If asummary element is not a child of adetails element, or it is not the firstsummary element of a parentdetails, then user agentsMUST expose thesummary element with ageneric role.
No accessible object. Styles used are exposed by UIA text attribute identifiers of theTextRange Control Pattern implemented on a parent accessible object.
Note: If thecontrols attribute is present, UI controls (e.g., play, volume) are exposed as children of thevideo element in theaccessibility tree, and mapped as appropriate for the type of control (e.g.,button orslider).
User agentsMAY include the following in theaccessibility tree and mark them as hidden or off-screen:
Note: If thecontrols attribute is present, UI controls (e.g., play, volume) are exposed as descendants of anaccessible object with a role oftoolbar, and mapped as appropriate for the type of control (e.g.,button orslider).
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 anaccessibilityAPI. This is usually because the attribute is not displayed as part of the user interface.
When used on aform element, theautocomplete attribute identifies whether form controls owned by the form will have theirautofill field name set to "on" or "off" by default. Seeautocomplete forinput,select,textarea for control mappings.
If the form control has been specified as bothautocomplete=off (whether due to explicit use of the attribute, or from inheriting theoff state from a parentform element withautocomplete=off) and with anaria-autocomplete attribute with a valid value, user agentsMUST expose only thearia-autocomplete attribute value.
Otherwise, if the form control has anautocomplete attribute specified with a valid token value, and anaria-autocomplete attribute, then user agentsMUST expose only theautocomplete attribute value.
If aninput element in thecheckbox orradio state includes both thechecked attribute and thearia-checked attribute with a valid value, User AgentsMUST expose only thechecked attribute value.
Aninput element in thecheckbox orradio state without achecked attribute has an implicit "false" state. User AgentsMUST ignore anaria-checked attribute which conflicts with the native element's implicit checked state.
User AgentsMUST expose anaria-details relationship with the associated element (identified via the specifiedcommandfor attribute)except under the following conditions:
The associated popover element is the next immediate accessibility sibling to the invoking element,
The element is a descendant of thepopover it is associated with.
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 thefalse state.
States:IA2_STATE_EDITABLE andIA2_STATE_MULTI_LINE
Interfaces:IAccessibleEditableText
If the element is in thefalse state: not mapped.
If the element is in theinherit 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 thefalse state.
Control Pattern:TextEdit
Property:AriaProperties.multiline:true
If the element is in thefalse state: not mapped.
If the element is in theinherit 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 thefalse state.
States:ATK_STATE_EDITABLE andATK_STATE_MULTI_LINE
Interfaces:AtkEditableText
If the element is in thefalse state: not mapped.
If the element is in theinherit state: match the editable state of its parent element.
If the element has both thedisabled attribute and thearia-disabled attribute with a valid value, User AgentsMUST expose only thedisabled attribute value.
Form controls within a validlegend child element of afieldset with adisabled attribute do not become disabled.
If the element has both thedisabled attribute and thearia-disabled attribute with a valid value, User AgentsMUST expose only thedisabled attribute value.
When thelabel element has afor attribute referencing anotherlabelable element, theLabeledBy property for the referenced element points to the UIA element for thelabel element.
aria-hidden="true" if the element retains its user agent default styling ofdisplay: 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 toa andarea element mappings. The value of thehref attribute is stored in theValue.Value UIA property.
Theopen attribute's value is irrelevant. When theopen attribute is not specified the default user agent styling for adialog isdisplay: none.
Authors can reveal adialog through the style layer by modifying itsdisplay property. If revealed this way then thedialog isaria-modal="false" andaria-hidden="false".
When theplaceholder andaria-placeholder attributes are both present, and theplaceholder attribute's value is non-empty, user agentsMUST expose the value of theplaceholder attribute, and ignorearia-placeholder. If theplaceholder attribute's value is empty, then user agentsMUST expose the value of thearia-placeholder attribute.
A details relation is made with the invoking element, if an invoking element exists which meets the conditions for necessitating a details relationship.See Comments.
If the element includes both thereadonly attribute and thearia-readonly attribute with a valid value, User AgentsMUST expose only thereadonly attribute value.
If the element includes both therequired attribute and thearia-required attribute with a valid value, User AgentsMUST expose only therequired attribute value.
If an element isrequired, user agentsMUST NOT expose the element with an intitial invalid state (aria-invalid="true"). The user agentSHOULD expose the invalid state only after1) a user has purposefully interacted with a required element, or attempted to submit a form and2) the element, or elements, do not meetconstraint validation.
Until these conditions are met, user agentsMUST expose the elements as (aria-invalid="false").
If the element includes both theselected attribute and thearia-selected attribute with a valid value, User AgentsMUST expose only theselected attribute value.
Forinput elements that allow thesize attribute, the attribute will modify their default width. A width provided by CSS will negate the effects of thesize attribute on theseinput elements.
Defines the list item marker, which is exposed as content inAXValue, and rendered as anaccessible object:
AXRole:AXListMarker
AXSubrole:(nil)
AXRoleDescription:"list marker"
Comments
Some platforms (IAccessible2, ATK, UIA) do not expose anaccessible object for the list item marker, whether it was created and then pruned from theaccessibility 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.
User agentsMAY use the exact text value of thevalue attribute, or a localized variation of the specified text to present a human friendly representation of the color value.
If specified, and theinput in theimage state has noalt attribute specified, then the value of the attribute will be thehost language label used in theaccessible name computation, and will render as text if the image source is broken. Otherwise, the attribute is ignored.
Expose the value of thevalue attribute as the first text node in the list item. If the value of thevalue attribute is an integer, set the UIAPositionInSet property to the integer value.
User Agents notify assistive technology when relevant accessibility information changes, sometimes by destroying and recreating the accessibility object, or sometimes by notifying of changes to the object per the specifiedname change event mappings anddescription change event mappings.
If theaccessible name is still empty: use thetext equivalent computation of the associatedlabel element's subtree - if more than onelabel is associated; concatenate their subtrees by DOM order, delimited by spaces.
If the control is encapsulated by itslabel element, exclude the control's author specified or user-entered value from its computedaccessible name.
If theaccessible name is still empty: use the value of the control'stitle attribute.
If theaccessible name is still empty: use thetext equivalent computation of the associatedlabel element's subtree - if more than onelabel is associated; concatenate their subtrees by DOM order, delimited by spaces.
If the control is encapsulated by itslabel element, and the control has an author specifiedvalue or the lack of avalue has produced animplementation defined string to render, then exclude either from the control's computedaccessible name.
If theaccessible name is still empty: use the value of the control'svalue attribute.
Forinput type=submit andtype=reset: if theaccessible name is still empty, and thevalue attribute is unspecified, use theimplementation defined string respective to the input type. For instance, a localized string of the word "submit" or "reset" respective to the type ofinput.
Otherwise: use the value of the control'stitle attribute.
If none of the above yield a usable text string there is noaccessible name.
4.1.3input type="image" Element Accessible Name Computation
If theaccessible name is still empty: use thetext equivalent computation of the associatedlabel element's subtree - if more than onelabel is associated; concatenate their subtrees by DOM order, delimited by spaces.
If the control is encapsulated by itslabel element, and the control has analt attribute, then exclude the attribute's value from the control's computedaccessible name.
If theaccessible name is still empty: use the value of the control'salt attribute if present and its value, when trimmed ofwhitespace, is not the empty string.
If theaccessible name is still empty: use the value of the control'stitle attribute if present and its value is not the empty string.
Otherwise, if the previous steps do not yield a usable text string: use theimplementation defined string respective to the input type (aninput in theimage state represents asubmit 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 noaccessible name.
If theaccessible name is still empty: use thetext equivalent computation of the associatedlabel element's subtree - if more than onelabel is associated; concatenate their subtrees by DOM order, delimited by spaces.
If thebutton element is encapsulated by itslabel element, ignore thebutton element's subtree from its computedaccessible name.
Otherwise use the associatedlabel element or elementsaccessible name(s) - if more than onelabel is associated; concatenate by DOM order, delimited by spaces.
Otherwise usetitle attribute.
If none of the above yield a usable text string there is noaccessible name.
4.1.7Other Form Elements Accessible Name Computation
If there is nosummary element as a direct child of thedetails element, the user agentSHOULD provide one with a subtree containing a localized string of the word "details".
If there is asummary element as a direct child of thedetails element, but none of the above yield a usable text string, there is noaccessible name.
4.1.9figure Element Accessible Name Computation
Afigcaption provides additional information related to its parentfigure element. Afigcaption does not take part in theaccessible name oraccessible description computation, unless explicitly referenced by an author.
If theaccessible name is still empty: usealt attribute, even if its value, when trimmed ofwhitespace, is the empty string.
Note
Animg with analt attribute whose value, when trimmed ofwhitespace, is the empty string is mapped to thepresentation role. It has no accessible name.
If theaccessible name is still empty and there is noalt attribute, use thetitle attribute.
If theaccessible name is still empty and there are noalt ortitle attributes, and theimg is a descendant of afigure element with a childfigcaption but no other non-whitespaceflow content descendants, then use thetext equivalent computation of thefigcaption element's subtree.
If none of the above yield a usable text string there is noaccessible name.
Note
The document referenced by thesrc of theiframe element gets its name from that document'stitle element, like any other document. If there is notitle provided, there is no accessible name.
4.1.16Section and Grouping Element Accessible Name Computation
aninput element whosetype attribute is thebutton,submit orreset state, and it has avalue attribute, then use the flat string of the attribute if it was not used as theaccessible name.
Otherwise, use the flat string of thetitle attribute if it was not used as theaccessible name for the element.
In accordance withWeb 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 performactive fingerprinting of users of Assistive Technologies.
6.Security considerations
This specification introduces no new security considerations.
19-Jul-2022: Updateaddress element to be mapped torole=group. SeeGitHub PR 420.
03-Apr-2022: Updateaside mappings based on its nesting context. SeeGitHub PR 350.
06-Mar-2022: Update the following elements to map to thegeneric role:a no href,footer not scoped tobody,header not scoped tobody,samp,span. SeeGitHub PR 364.
06-Feb-2022: Updatemark to point to Core AAM mapping for the role. SeeGitHub Issue 316.
02-Nov-2021: Updatingblockquote,caption,code,del,em,ins,meter,paragraph,strong,sub,sup andtime to ARIA 1.2 mappings in Core AAM. Fixbody mapping togeneric, andhtml mapping todocument. Fixhgroup mapping togeneric. Updatedetails to map togroup with additional information specific to ATK, UIA. SeeGitHub issue #348
12-May-2021: Add FACES references to attributes table -readonly,name,form,disabled. SeeIssue 257.
12-Dec-2019: Addshgroup,slot, autonomous custom element and form associated custom element. SeeGitHub issue #189.
23-Nov-2017: Removed the accessible name computation requirement to ignore animg element'stitle attribute when the element'salt attribute is empty. SeeGitHub issue #99.
23-Nov-2017: Added note to not exposearia-roledescription unless element also a conformingrole attribute value. SeeGitHub issue #98.
09-Aug-2017: Updated mappings for thetype attribute on theol element. SeeGitHub 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.