Please check theerrata for any errors or issues reported since publication.
See alsotranslations.
Copyright © 2013-2017W3C® (MIT,ERCIM,Keio,Beihang).W3Cliability,trademark anddocument use rules apply.
Accessibility of web content requires semantic information about widgets, structures, and behaviors, in order to allow assistive technologies to convey appropriate information to persons with disabilities. This specification provides an ontology of roles, states, and properties that define accessible user interface elements and can be used to improve the accessibility and interoperability of web content and applications. These semantics are designed to allow an author to properly convey user interface behaviors and structural information to assistive technologies in document-level markup. This version adds features new sinceWAI-ARIA 1.0 [wai-aria-1.0] to improve interoperability with assistive technologies to form a more consistent accessibility model for [html5] and [SVG2]. This specification complements both [html5] and [SVG2].
This document is part of theWAI-ARIA suite described in theWAI-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 currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.
This is theWAI-ARIA 1.1W3C Recommendation by theAccessible Rich Internet Applications Working Group. The Working Group created aWAI-ARIA 1.1 Implementation Report to demonstrate that the specification is implementable. Ahistory of changes toWAI-ARIA 1.1 is available in the appendix.
To comment on this document,file an issue in theW3C aria GitHub repository. If this is not feasible, send email topublic-aria@w3.org (comment archive). Comments received on theWAI-ARIA 1.1 Recommendation cannot result in changes to this version of the specification, but may be addressed in errata or future versions ofWAI-ARIA. The Working Group may not make formal responses to comments but future work undertaken by the Working Group may address comments received on this document. In-progress updates to the technology may be viewed in thepublicly visible editors' draft.
This document was published by theAccessible Rich Internet Applications Working Group as a Recommendation.
Please see the Working Group'simplementation report.
This document has been reviewed byW3C Members, by software developers, and by otherW3C groups and interested parties, and is endorsed by the Director as aW3C Recommendation. It is a stable document and may be used as reference material or cited from another document.W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document was produced by a group operating under theW3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.
This document is governed by the1 March 2017W3C Process Document.
This section is non-normative.
The goals of this specification include:
WAI-ARIA is a technical specification that provides a framework to improve the accessibility and interoperability of web content and applications. This document is primarily for developers creating custom widgets and other web application components. Please see theWAI-ARIA Overview for links to related documents for other audiences, such asWAI-ARIA Authoring Practices [wai-aria-practices-1.1] that introduces developers to the accessibility problems thatWAI-ARIA is intended to solve, the fundamental concepts, and the technical approach ofWAI-ARIA.
This draft currently handles two aspects ofroles: user interface functionality and structuralrelationships. For more information and use cases, see [wai-aria-practices-1.1] for the use of roles in making interactive content accessible.
The roletaxonomy is designed in part to support the common roles found in platformaccessibilityAPIs. Reference to roles found in this taxonomy by dynamic web content may be used to support interoperability with assistive technologies.
The schema to support this standard has been designed to be extensible so that custom roles can be created by extending base roles. This allowsuser agents to support at least the base role, and user agents that support the custom role can provide enhanced access. Note that much of this could be formalized in [xmlschema-2]. However, being able to define similarities between roles, such asbaseConcepts and more descriptive definitions, would not be available inXSD.
WAI-ARIA 1.1 is a member of theWAI-ARIA 1.1 suite that defines how to expose semantics ofWAI-ARIA and other web content languages toaccessibilityAPIs.
The domain of web accessibility defines how to make web content usable by persons with disabilities. Persons with certain types of disabilities useassistive technologies (AT) to interact with content. Assistive technologies can transform the presentation of content into a format more suitable to the user, and can allow the user to interact in different ways. For example, the user may need to, or choose to, interact with a slider widget via arrow keys, instead of dragging and dropping with a mouse. In order to accomplish this effectively, the software needs to understand thesemantics of the content. Semantics is the science of meaning; in this case, used to assign roles, states, and properties that apply to user interface and content elements as a human would understand. For instance, if a paragraph is semantically identified as such, assistive technologies can interact with it as a unit separable from the rest of the content, knowing the exact boundaries of that paragraph. An adjustable range slider or collapsible list (a.k.a. a treewidget) are more complex examples, in which various parts of the widget have semantics that need to be properly identified for assistive technologies to support effective interaction.
New technologies often overlook semantics required for accessibility, and new authoring practices often misuse the intended semantics of those technologies.Elements that have one defined meaning in the language are used with a different meaning intended to be understood by the user.
For example, web application developers create collapsible tree widgets inHTML usingCSS and JavaScript even thoughHTML has no semantictree
element. To a non-disabled user, it may look and act like a collapsible tree widget, but without appropriate semantics, the tree widget may not beperceivable to, oroperable by, a person with a disability because assistive technologies may not recognize the role. Similarly, web application developers create interactive button widgets inSVG using JavaScript even thoughSVG has no semanticbutton
element. To a non-disabled user, it may look and act like a button widget, but without appropriate semantics, the button widget may not beperceivable to, oroperable by, a person with a disability because assistive technologies may not recognize the role.
The incorporation ofWAI-ARIA is a way for an author to provide proper semantics for custom widgets to make these widgets accessible, usable, and interoperable with assistive technologies. This specification identifies the types of widgets and structures that are commonly recognized by accessibility products, by providing anontology of correspondingroles that can be attached to content. This allows elements with a given role to be understood as a particular widget or structural type regardless of any semantics inherited from the implementing host language. Roles are a common property of platformaccessibilityAPIs which assistive technologies use to provide the user with effective presentation and interaction.
This roletaxonomy includes interactionwidgets and elements denoting document structure. The role taxonomy describes inheritance and details theattributes each role supports. Information about mapping of roles to accessibilityAPIs is provided by theCore AccessibilityAPI Mappings 1.1 [core-aam-1.1].
Roles are element types and will not change with time or user actions. Role information is used by assistive technologies, through interaction with the user agent, to provide normal processing of the specified element type.
States and properties are used to declare important attributes of an element that affect and describe interaction. They enable theuser agent and operating system to properly handle the element even when the attributes are dynamically changed by client-side scripts. For example, alternative input and output technology, such as screen readers and speech dictation software, need to be able to recognize and effectively manipulate and communicate various interaction states (e.g., disabled, checked) to the user.
While it is possible for assistive technologies to access these properties directly through theDocument Object Model [dom], the preferred mechanism is for the user agent to map the states and properties to the accessibilityAPI of the operating system. See theCore AccessibilityAPI Mappings 1.1 [core-aam-1.1] and theAccessible Name and Description: Computation andAPI Mappings 1.1 [accname-aam-1.1] for details.
Figure 1.0 illustrates the relationship between user agents (e.g., browsers), accessibilityAPIs, and assistive technologies. It describes the "contract" provided by the user agent to assistive technologies, which includes typical accessibility information found in the accessibilityAPI for many of our accessible platforms for GUIs (role, state, selection,event notification,relationship information, and descriptions). TheDOM, usuallyHTML, acts as the data model and view in a typical model-view-controller relationship, and JavaScript acts as the controller by manipulating the style and content of the displayed data. The user agent conveys relevant information to the operating system's accessibilityAPI, which can be used by any assistive technologies, such as screen readers.
Figure 1: The contract model with accessibilityAPIs
For more information seeWAI-ARIA Authoring Practices [wai-aria-practices-1.1] for the use of roles in making interactive content accessible.
In addition to the prose documentation, the role taxonomy is provided inWeb Ontology Language (OWL) [owl-features], which is expressed inResource Description Framework (RDF) [rdf-concepts]. Tools can use these to validate the implementation of roles in a given content document. For example, instances of some roles are expected to be children of a specific parent role. Also, some roles may support a specificstate orproperty that another role does not support.
The use ofRDF/OWL as a formal representation of roles may be used to support future extensibility. StandardRDF/OWL mechanisms can be used to define new roles that inherit from the roles defined in this specification. The mechanism to define and use role extensions in an interoperable manner, however, is not defined by this specification, andRDF/OWL processing is not essential to interoperable implementation of this specification. A future version ofWAI-ARIA is expected to define how to extend roles.
Users of alternate input devices needkeyboard accessible content. The new semantics, when combined with the recommended keyboard interactions provided inWAI-ARIA Authoring Practices [wai-aria-practices-1.1], will allow alternate input solutions to facilitate command and control via an alternate input solution.
WAI-ARIA introduces navigationallandmarks through its taxonomy and theXHTML role landmarks, which can help persons with dexterity and vision impairments by providing for improved keyboard navigation.WAI-ARIA may also be used to assist persons with cognitive learning disabilities. The additional semantics allow authors to restructure and substitute alternative content as needed.
Assistive technologies need the ability to support alternative inputs by getting and setting the current value ofwidget states and properties. Assistive technologies also need to determine whatobjects are selected and manage widgets that allow multiple selections, such as list boxes and grids.
Speech-based command and control systems can benefit fromWAI-ARIA semantics like therole
attribute to assist in conveying audio information to the user. For example, upon encountering an element with a role ofmenu
with child elements of rolemenuitem
each containing text content representing a different flavor, a speech system might state to the user, "Select one of three choices: chocolate, strawberry, or vanilla."
WAI-ARIA is intended to be used as a supplement for native language semantics, not a replacement. When the host language provides a feature that provides equivalent accessibility to theWAI-ARIA feature, use the host language feature.WAI-ARIA should only be used in cases where the host language lacks the neededrole,state, andproperty indicators. Use a host language feature that is as similar as possible to theWAI-ARIA feature, then refine the meaning by addingWAI-ARIA. For instance, a multi-selectable grid could be implemented as a table, and thenWAI-ARIA used to clarify that it is an interactive grid, not just a static data table. This allows for the best possible fallback for user agents that do not supportWAI-ARIA and preserves the integrity of the host language semantics.
This specification defines the basic model forWAI-ARIA, including roles, states, properties, and values. It impacts several audiences:
Each conformance requirement indicates the audience to which it applies.
Although this specification is applicable to the above audiences, it is not specifically targeted to, nor is it intended to be the sole source of information for, any of these audiences. The following documents provide important supporting information:
WAI-ARIA relies on user agent support for its features in two ways:
Aside from usingWAI-ARIA markup to improve what is exposed to accessibilityAPIs, user agents behave as they would natively. Assistive technologies react to the extra information in the accessibilityAPI as they already do for the same information on non-web content. User agents that are not assistive technologies, however, need do nothing beyond providing appropriate updates to the accessibilityAPI.
TheWAI-ARIA specification neither requires nor forbids user agents from enhancing native presentation and interaction behaviors on the basis ofWAI-ARIA markup. Mainstream user agents might exposeWAI-ARIA navigational landmarks (for example, as a dialog box or through a keyboard command) with the intention to facilitate navigation for all users. User agents are encouraged to maximize their usefulness to users, including users without disabilities.
WAI-ARIA is intended to provide missing semantics so that the intent of the author may be conveyed to assistive technologies. Generally, authors usingWAI-ARIA will provide the appropriate presentation and interaction features. Over time, host languages may addWAI-ARIA equivalents, such as new form controls, that are implemented as standard accessible user interface controls by the user agent. This allows authors to use them instead of customWAI-ARIA enabled user interface components. In this case the user agent would support the native host language feature. Developers of host languages that implementWAI-ARIA are advised to continue supportingWAI-ARIA semantics when they do not adversely conflict with implicit host language semantics, asWAI-ARIA semantics more clearly reflect the intent of the author if the host language features are inadequate to meet the author's needs.
WAI-ARIA is intended to augment semantics in supporting languages like [html5] and [SVG2], or to be used as an accessibility enhancement technology in other markup-based languages that do not explicitly include support for ARIA. It clarifies semantics to assistive technologies when authors create new types of objects, via style and script, that are not yet directly supported by the language of the page, because the invention of new types of objects is faster than standardized support for them appears in web languages.
It is not appropriate to create objects with style and script when the host language provides a semantic element for that type of object. WhileWAI-ARIA can improve the accessibility of these objects, accessibility is best provided by allowing the user agent to handle the object natively. For example, it's better to use anh1
element inHTML than to use theheading
role on adiv
element.
It is expected that, over time, host languages will evolve to provide semantics for objects that currently can only be declared withWAI-ARIA. This is natural and desirable, as one goal ofWAI-ARIA is to help stimulate the emergence of more semantic and accessible markup. When native semantics for a given feature become available, it is appropriate for authors to use the native feature and stop usingWAI-ARIA for that feature. Legacy content may continue to useWAI-ARIA, however, so the need for user agents to supportWAI-ARIA remains.
While specific features ofWAI-ARIA may lose importance over time, the general possibility ofWAI-ARIA to add semantics to web pages is expected to be a persistent need. Host languages may not implement all the semanticsWAI-ARIA provides, and various host languages may implement different subsets of the features. New types of objects are continually being developed, and one goal ofWAI-ARIA is to provide a way to make such objects accessible, because web authoring practices often advance faster than host language standards. In this way,WAI-ARIA and host languages both evolve together but at different rates.
Some host languages exist to create semantics for features other than the user interface. For example,SVG expresses the semantics behind production of graphical objects, not of user interface components that those objects may represent; XForms provides semantics for form controls and does not provide wider user interface features. Host languages such as these might, by design, not provide native semantics that map toWAI-ARIA features. In these cases,WAI-ARIA could be adopted as a long-term approach to add semantic information to user interface components.
Many of the requirements in the definitions ofWAI-ARIAroles,states, andproperties can be checked automatically during the development process, similar to other quality control processes used for validating code. To assist authors who are creating custom widgets, authoring tools may compare widget roles, states, and properties to those supported inWAI-ARIA as well as those supported in related and cross-referenced roles, states, and properties. Authoring tools may notify authors of errors in widget design patterns, and may also prompt developers for information that cannot be determined from context alone. For example, a scripting library can determine the labels for the tree items in a tree view, but would need to prompt the author to label the entire tree. To help authors visualize a logical accessibility structure, an authoring environment might provide an outline view of a web resource based on theWAI-ARIA markup.
In bothHTML andSVG,tabindex
is an important way browsers support keyboardfocus navigation for implementations ofWAI-ARIA; authoring and debugging tools may check to make suretabindex
values are properly set. For example, error conditions may include cases where more than one treeitem in a tree has atabindex
value greater than or equal to 0, wheretabindex
is not set on any treeitem, or wherearia-activedescendant
is not defined when the element with the role tree has atabindex
value of greater than or equal to 0.
The accessibility of interactive content cannot be confirmed by static checks alone. Developers of interactive content should test for device-independent access towidgets and applications, and should verify accessibilityAPI access to all content and changes during user interaction.
Programmatic access to accessibility semantics is essential for assistive technologies. Most assistive technologies interact with user agents, like other applications, through a recognized accessibilityAPI. Perceivable objects in the user interface are exposed to assistive technologies as accessible objects, defined by the accessibilityAPI interfaces. To do this properly, accessibility information – role, states, properties as well as contextual information – needs to be accurately conveyed to the assistive technologies through the accessibilityAPI. When a state change occurs, the user agent provides the appropriate event notification to the accessibilityAPI. Contextual information, in many host languages likeHTML, can be determined from theDOM itself as it provides a contextual tree hierarchy.
While some assistive technologies interact with these accessibilityAPIs, others may access the content directly from theDOM. These technologies can restructure, simplify, style, or reflow the content to help a different set of users. Common use cases for these types of adaptations may be the aging population, persons with cognitive impairments, or persons in environments that interfere with use of their tools. For example, the availability of regional navigational landmarks may allow for a mobile device adaptation that shows only portions of the content at any one time based on its semantics. This could reduce the amount of information the user needs to process at any one time. In other situations it may be appropriate to replace a custom user interface control with something that is easier to navigate with a keyboard, or touch screen device.
This section is non-normative.
Complex web applications become inaccessible whenassistive technologies cannot determine thesemantics behind portions of a document or when the user is unable to effectively navigate to all parts of it in a usable way (seeWAI-ARIA Authoring Practices [wai-aria-practices-1.1]).WAI-ARIA divides the semantics intoroles (the type defining a user interface element) andstates andproperties supported by the roles.
Authors need to associateelements in the document to aWAI-ARIA role and the appropriate states and properties (aria-*attributes) during its life-cycle, unless the elements already have the appropriateimplicitWAI-ARIA semantics for states and properties. In these instances the equivalent host language states and properties take precedence to avoid a conflict while the role attribute will take precedence over the implicit role of the host language element.
AWAI-ARIArole is set on anelement using arole
attribute, similar to therole
attribute defined inRole Attribute [role-attribute].
<lirole="menuitem">Open file…</li>
The roles defined in this specification include a collection ofdocument landmarks and theWAI-ARIA role taxonomy.
The roles in thistaxonomy and their expected behaviors are modeled usingRDF/OWL [owl-features]. Features of the role taxonomy provide the following information for each role:
directory
is a type oflist
);listitem
is contained inside alist
);checkbox
supports being checked viaaria-checked
).Attaching a role givesassistive technologies information about how to handle each element.
WAI-ARIA provides a collection of accessibilitystates andproperties which are used to support platformaccessibilityAPIs on various operating system platforms.Assistive technologies may access this information through an exposeduser agentDOM or through a mapping to the platform accessibilityAPI. When combined withroles, the user agent can supply the assistive technologies with user interface information to convey to the user at any time. Changes in states or properties will result in a notification to assistive technologies, which could alert the user that a change has occurred.
In the following example, a list item (html:li
) has been used to create a checkable menu item, and JavaScriptevents will capture mouse and keyboard events to toggle the value ofaria-checked
. A role is used to make the behavior of this simplewidget known to the user agent.Attributes that change with user actions (such asaria-checked
) are defined in thestates and properties section.
<lirole="menuitemcheckbox"aria-checked="true">Sort by Last Modified</li>
Some accessibility states, calledmanaged states, are controlled by the user agent. Examples of managed state include keyboard focus and selection. Managed states often have correspondingCSS pseudo-classes (such as:focus
and::selection
) to define style changes. In contrast, the states in this specification are typically controlled by the author and are calledunmanaged states. Some states are managed by the user agent, such asaria-posinset
andaria-setsize
, but the author can override them if theDOM is incomplete and would cause the user agent calculation to be incorrect. User agents map both managed and unmanaged states to the platform accessibilityAPIs.
Most modern user agents supportCSS attribute selectors ([css3-selectors]), and can allow the author to createUI changes based onWAI-ARIA attribute information, reducing the amount of scripts necessary to achieve equivalent functionality. In the following example, aCSS selector is used to determine whether or not the text is bold and an image of a check mark is shown, based on the value of thearia-checked
attribute.
[aria-checked="true"] { font-weight: bold; }[aria-checked="true"]::before { background-image: url(checked.gif); }
IfCSS is not used to toggle the visual representation of the check mark, the author could include additional markup and scripts to manage an image that represents whether or not themenuitemcheckbox
is checked.
<li role="menuitemcheckbox" aria-checked="true"><imgsrc="checked.gif"role="presentation"alt=""><!--note: additional scripts required to toggle image source --> Sort by Last Modified</li>
Anapplication
should always have anelement with focus when in use, as applications require users to have a place to provide user input. Authors are advised tonot destroy the element with focus or scroll it off-screen unless through user intervention. All interactiveobjects should be focusable. All parts of composite interactive controls need to be focusable or have a documented alternative method to achieve their function, such as a keyboard shortcut. Authors are advised to maintain an obvious, discoverable way, either through tabbing or other standard navigation techniques, for keyboard users to move the focus to any interactive element. SeeUser Agent Accessibility Guidelines, Guideline 9 ([UAAG10], Guideline 9).
When using standardHTML and basicWAI-ARIAwidgets, application developers can simply manipulate the tab order or use a script to create keyboard shortcuts to elements in the document. Use of more complex widgets requires the author to manage focus within them.SVG Tiny provides a similar navigation "ring" mechanism that by default follows document order and which should be implemented using system dependent input facilities (the TAB key on most desktop computers).SVG authors may place elements in the navigation order by manipulating thefocusable attribute and they may dynamicallyspecify the navigation order by modifying elements'navigation attributes.
When the container or its active descendant has focus, the user may navigate through the container by pressing additional keys, such as the arrow keys, to change the currently active descendant. Any additional press of the main navigation key (generally theTAB key) will move out of the container to the next widget.
For example, agrid
may be used as a spreadsheet with thousands ofgridcell
elements, all of which may not be present in the document at one time. This requires focus to be managed by the container using thearia-activedescendant
attribute on the managing container element, or by the container managing thetabindex
of its child elements and setting focus on the appropriate child.
Content authors are required to manage focus on the following container roles:
More information on managing focus can be found in theDeveloping a Keyboard Interface section of theWAI-ARIA Authoring Practices [wai-aria-practices-1.1].
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,SHOULD, andSHOULD NOT are to be interpreted as described in [RFC2119].
This specification indicates whether a section isnormative orinformative. Classifying a section as normative or informative applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.
Normative sections provide requirements that authors, user agents, and assistive technologiesMUST follow for an implementation to conform to this specification.
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.
WAI-ARIA processing by theuser agentMUST NOT interfere with the normal operation of the built-in features of the host language.
If aCSS selector includes aWAI-ARIA attribute (e.g.,input[aria-invalid="true"]
), user agentsMUST update the visual display of any elements matching (or no longer matching) the selector any time the attribute is added/changed/removed in theDOM. The user agentMAY alter the mapping of the host language features into anaccessibilityAPI, but the user agentMUST NOT alter theDOM in order to remapWAI-ARIA markup into host language features.
A conforminguser agent which implements a document object model that does not conform to theW3CDOM specificationMUST include the content attribute for role and itsWAI-ARIA role values, as well as theWAI-ARIA States and Properties in theDOM as specified by the author, even though processing may affect how the elements are exposed to accessibilityAPIs. Doing so ensures that each role attribute and allWAI-ARIA states and properties, including their values, are in the document in an unmodified form so other tools, such as assistive technologies, can access them. A conformingW3CDOM meets this criterion.
Assistive technologies, such as speech recognition systems and alternate input devices for users with mobility impairments, require the ability to control a web application in a device-independent way.WAI-ARIAstates andproperties reflect the current state of rich internet application components. The ability for assistive technologies to notify web applications of necessary changes is essential because it allows these alternative input solutions to control an application without being dependent on the standard input device which the user is unable to effectively control directly.
User agentsMUST provide a method to notify the web application when a change occurs to states or properties in the system accessibilityAPI. Likewise, web application authorsSHOULD update the web application accordingly when notified of a change request from the user agent or assistive technology.
Many state and properties can be changed by assistive technologies through existing accessibilityAPIs by responding to a default action event. For example, thearia-selected
state of atab
in atabpanel
can be changed by triggering the default action on the element.
Any application or script verifying document conformance or validitySHOULD include a test for all of thenormative author requirements in this specification. If testing for a given requirement, conformance checkersMUST issue an error if an author "MUST" requirement isn't met, andMUST issue a warning if an author "SHOULD" requirement isn't met.
As the technology evolves, sometimes new ways to meet a use case become available, that work better than a feature that was previously defined. But because of existing implementation of the older feature, that feature cannot be removed from the conformance model without rendering formerly conforming content non-conforming. In this case, the older feature is marked as "deprecated". This indicates that the feature is allowed in the conformance model and expected to be supported by user agents, but it is recommended that authors do not use it for new content. In future versions of the specification, if the feature is no longer widely used, the feature could be removed and no longer expected to be supported by user agents.
This section is non-normative.
While some terms are defined in place, the following definitions are used throughout this document.
Operating systems and other platforms provide a set of interfaces that expose information aboutobjects andevents toassistive technologies. Assistive technologies use these interfaces to get information about and interact with thosewidgets. Examples of accessibilityAPIs areMicrosoft Active Accessibility [MSAA],Microsoft User Interface Automation [UI-AUTOMATION],MSAA withUIA Express [UIA-EXPRESS], theMacOS X Accessibility Protocol [AXAPI], theLinux/Unix Accessibility Toolkit [ATK] andAssistive Technology Service Provider Interface [AT-SPI], andIAccessible2 [IAccessible2].
An accessible description provides additional information, related to an interface element, that complements theaccessible name. The accessible description might or might not be visually perceivable.
The accessible name is the name of a user interface element. Each platformaccessibilityAPI 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 relatedaccessible 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 platformaccessibilityAPIs orassistive technologies.
Hardware and/or software that:
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:
In this specification, attribute is used as it is in markup languages. Attributes are structural features added toelements to provide information about thestates andproperties of theobject represented by the element.
A set of instanceobjects that share similar characteristics.
A deprecatedrole,state, orproperty is one which has been outdated by newer constructs or changed circumstances, and which may be removed in future versions of theWAI-ARIA specification.User agents are encouraged to continue to support items identified as deprecated for backward compatibility. For more information, seeDeprecated Requirements in the Conformance section.
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 forobjects.
A programmatic message used to communicate discrete changes in thestate of anobject 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.
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).
Indicates that theelement is not visible,perceivable, or interactive toany user. An element is consideredhidden if it or any one of its ancestor elements is not rendered or is explicitly hidden.
Content provided for information purposes and not required for conformance. Content required for conformance is referred to asnormative.
Accessible to the user using a keyboard orassistive technologies that mimic keyboard input, such as a sip and puff tube. References in this document relate toWCAG 2.0 Guideline 2.1: Make all functionality available from a keyboard [WCAG20].
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 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.
AccessibilityAPIstate 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 correspondingCSS pseudo-classes, such as :focus, and pseudo-elements, such as ::selection, that are also updated by the user agent.
The Nemeth Braille Code for Mathematics is a braille code for encoding mathematical and scientific notation. SeeNemeth Braille on Wikipedia.
Required for conformance. By contrast, content identified asinformative or "non-normative" is not required for conformance.
In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or moreelements, and rendered byuser agents.
In the context of programming, the instantiation of one or moreclasses and interfaces which define the general characteristics of similar objects. An object in anaccessibilityAPI may represent one or moreDOM objects.AccessibilityAPIs have defined interfaces that are distinct fromDOM interfaces.A description of the characteristics ofclasses and how they relate to each other.
Usable by users in ways they can control. References in this document relate toWCAG 2.0 Principle 2: Content must be operable [WCAG20]. SeeKeyboard Accessible.
An 'owned element' is anyDOM descendant of theelement, any element specified as a child viaaria-owns
, or anyDOM descendant of the owned child.
Presentable to users in ways they can sense. References in this document relate toWCAG 2.0 Principle 1: Content must be perceivable [WCAG20].
Attributes that are essential to the nature of a givenobject, 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 thanstates, but note that the frequency of change difference is not a rule. A few properties, such asaria-activedescendant
,aria-valuenow
, andaria-valuetext
are expected to change often. Seeclarification of states versus properties.
A connection between two distinct things. Relationships may be of various types to indicate whichobject labels another, controls another, etc.
Main indicator of type. Thissemantic 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.
The meaning of something as understood by a human, defined in a way that computers can process a representation of anobject, such aselements andattributes, and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.
A state is a dynamicproperty expressing characteristics of anobject 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. Seeclarification of states versus properties.
A hierarchical definition of how the characteristics of variousclasses 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 anontology.
Presentable to users in ways they can construct an appropriate meaning. References in this document relate toWCAG 2.0 Principle 3: Information and the operation of user interface must be understandable [WCAG20].
Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.
Discrete user interfaceobject 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).
This section defines theWAI-ARIAroletaxonomy and describes the characteristics and properties of allroles. A formalRDF/OWL representation of all the information presented here is available inSchemata Appendix.
The roles, their characteristics, the states and properties they support, and specification of how they may be used in markup, shall be considered normative. TheRDF/OWL representation used to model the taxonomy shall be considered informative. TheRDF/OWL taxonomy may be used as a vehicle to extendWAI-ARIA in the future or by tool manufacturers to validate states and properties applicable to roles per this specification.
Roles are element types and authorsMUST NOT change role values over time or with user actions. Authors wishing to change a roleMUST do so by deleting the associated element and its children and replacing it with a new element with the appropriate role. Typically, platform accessibilityAPIs do not provide a vehicle to notify assistive technologies of a role value change, and consequently, assistive technologies may not update their cache with the new role attribute value.
In order to reflect the content in theDOM, user agentsSHOULD map the role attribute to the appropriate value in the implemented accessibilityAPI, and user agentsSHOULD update the mapping when the role attribute changes.
Theroletaxonomy uses the following relationships to relateWAI-ARIA roles to each other and to concepts from other specifications, such asHTML and XForms.
Inheritance is expressed inRDF using theRDF Schema 1.1subClassOf ([rdf-schema]) property.
Therole that the current subclassed role extends in thetaxonomy. This extension causes all the properties and constraints of the superclass role to propagate to the subclass role. Other than well known stable specifications, inheritance may be restricted to items defined inside this specification, so that external items cannot be changed and affect inheritedclasses.
Informative list ofroles for which this role is the superclass. This is provided to facilitate reading of the specification but adds no new information.
Informative data about a similar or related idea from other specifications. Concepts that are related are not necessarily identical. Related concepts do not inherit properties from each other. Hence if the definition of one concept changes, the properties, behavior, and definition of its related concept is not affected.
For example, a progress bar is like a status indicator. Therefore, theprogressbar
widget has arelatedConcept
value which includesstatus
. However, if the definition ofstatus
is modified, the definition of aprogressbar
is not affected.
Informative data aboutobjects that are considered prototypes for therole. Base concept is similar to type, but without inheritance of limitations and properties. Base concepts are designed as a substitute for inheritance for external concepts. A base concept is like arelated concept except that the base concept is almost identical to the role definition.
For example, thecheckbox
defined in this document has similar functionality and anticipated behavior to acheckbox defined inHTML. Therefore, acheckbox
has anHTMLcheckbox
as abaseConcept
. However, if the originalHTML checkbox baseConcept definition is modified, the definition of acheckbox
in this document will not be affected, because there is no actual inheritance of the respective type.
Roles are defined and described by their characteristics. Characteristics define the structural function of a role, such as what a role is, concepts behind it, and what instances the role can or must contain. In the case ofwidgets this also includes how it interacts with theuser agent based on mapping toHTML forms and XForms. States and properties fromWAI-ARIA that are supported by the role are also indicated.
The rolestaxonomy defines the following characteristics. These characteristics are implemented inRDF as properties of theOWLclasses that describe the roles.
Abstractroles are the foundation upon which all otherWAI-ARIA roles are built. Content authorsMUST NOT use abstract roles because they are not implemented in theAPI binding. User agentsMUST NOT map abstract roles to the standard role mechanism of the accessibilityAPI. Abstract roles are provided to help with the following:
States andproperties specifically required for therole and subclass roles. Content authorsMUST provide a non-emptyvalue for required states and properties. Content authorsMUST NOT use the valueundefined
for required states and properties, unlessundefined
is an explicitly-supported value of that state or property.
When anobject inherits from multiple ancestors and one ancestor indicates that property is supported while another ancestor indicates that it is required, the property is required in the inheriting object.
A host language attribute with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.
States andproperties specifically applicable to therole and child roles.User agentsMUST map all supported states and properties for the role to an accessibilityAPI. Content authorsMAY providevalues for supported states and properties, but need not in some cases where default values are sufficient.
A host language attribute with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.
Informative list of properties that are inherited onto arole from superclass roles.States andproperties are inherited from superclass roles in the roletaxonomy, not from ancestorelements in theDOM tree. These properties are not explicitly defined on the role, as the inheritance of properties is automatic. This information is provided to facilitate reading of the specification. The set of supported states and properties combined with inherited states and properties forms the full set of states and properties supported by the role.
Anyelement that will beowned by the element with thisrole. For example, an element with the rolelist
will own at least one element with the rolegroup
orlistitem
.
When multiple roles are specified asrequired owned elements for a role, at least one instance of one required owned element is expected. This specification doesnot require an instance of each of the listed owned roles. For example, amenu
should have at least one instance of amenuitem
,menuitemcheckbox
,ormenuitemradio
. Themenu
role does not require one instance of each.
There may be times that required owned elements are missing, for example, while editing or while loading a data set. When a widget is missingrequired owned elements due to script execution or loading, authorsMUST mark a containing element witharia-busy
equal totrue
. For example, until a page is fully initialized and complete, an author could mark the document element as busy.
A role that has 'required owned elements' does not imply the reverse relationship. While processing of a role may be incomplete without elements of given roles present as descendants, elements with roles in this list do not always have to be found within elements of the given role. Seerequired context role for requirements about the context where elements of a given role will be contained.
An element with asubclass role of the 'required owned element' does not fulfill this requirement. For example, thelist
role requires ownership of an element using either thelistitem
orgroup
role. Although thegroup
role is the superclass ofrow
, adding a owned element with a role ofrow
will not fulfill the requirement thatlist
must own alistitem
or agroup
.
An element with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.
The required context role defines the owning container where thisrole is allowed. If a role has a required context, authorsMUST ensure that an element with the role is contained inside (orowned by) an element with the required context role. For example, an element with rolelistitem
is only meaningful when contained inside (or owned by) an element with rolelist
.
A role that has 'required context role' does not imply the reverse relationship. While an element with the given role needs to appear within an element of the listed role(s) in order to be meaningful, elements of the listed roles do not always need descendant elements of the given role in order to be meaningful. Seerequired owned elements for requirements about elements that require presence of a given descendant to be processed properly.
An element with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.
aria-label
attribute, thearia-labelledby
attribute, or the host language labeling mechanism, such as thealt
ortitle
attributes inHTML, withHTMLtitle
attribute having the lowest precedence for specifying a text alternative.Name Computation is defined in the Accessible Name and Description specification [accname-aam-1.1].
Description Computation is defined in the Accessible Name and Description specification [accname-aam-1.1].
Text Alternative Computation is defined in the Accessible Name and Description specification [accname-aam-1.1].
All roles support name from author with two exceptions. The roles that do not support name from author arepresentation
andnone
.
Boolean (true
|false
)
TheDOM descendants are presentational.User agentsSHOULD NOT expose descendants of thiselement through the platformaccessibilityAPI. Ifuser agents do not hide the descendant nodes, some information may be read twice.
Many states and properties have default values. Occasionally, the default value when used on a given role should be different from the usual default. Roles that require a state or property to have a non-standard default value indicate this in the "Implicit Value for Role". This is expressed in the form "state or property name
isnew default value
". Roles that define this have the new default value for the state or property if the author does not provide an explicit value.
To support the current user scenario, this specification categorizesroles that define user interfacewidgets (sliders, tree controls, etc.) and those that define page structure (sections, navigation, etc.). Note that some assistive technologies provide special modes of interaction for regions marked with roleapplication
ordocument
.
Class diagram of the relationships described in the role data model.
SVG class diagram |PNG class diagram |Class diagram description
Roles are categorized as follows:
The followingroles are used to support theWAI-ARIA roletaxonomy for the purpose of defining general role concepts.
Abstract roles are used for the ontology. AuthorsMUST NOT use abstract roles in content.
The following roles act as standalone user interface widgets or as part of larger, composite widgets.
button
checkbox
gridcell
link
menuitem
menuitemcheckbox
menuitemradio
option
progressbar
radio
scrollbar
searchbox
separator
(when focusable)slider
spinbutton
switch
tab
tabpanel
textbox
treeitem
The following roles act as composite user interface widgets. These roles typically act as containers that manage other, contained widgets.
The followingroles describe structures that organize content in a page. Document structures are not usually interactive.
The followingroles are regions of the page intended as navigationallandmarks. All of these roles inherit from thelandmark
base type and all are imported from theRole Attribute [role-attribute]. The roles are included here in order to make them clearly part of theWAI-ARIA Roletaxonomy.
The followingroles arelive regions and may be modified bylive region attributes.
The followingroles act as windows within the browser or application.
Below is an alphabetical list ofWAI-ARIAroles to be used by rich internet application authors.
Abstract roles are used for the ontology. AuthorsMUST NOT use abstract roles in content.
alert
alertdialog
andstatus
.alertdialog
alert
anddialog
.application
structure
containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by awidget
role.article
banner
button
link
.cell
gridcell
.checkbox
true
,false
, ormixed
.columnheader
combobox
widget
containing a single-linetextbox
and another element, such as alistbox
orgrid
, that can dynamically pop up to help the user set the value of thetextbox
.command
(abstract role)complementary
composite
(abstract role)contentinfo
definition
term
.dialog
body
element.directory
document
feed
list
ofarticles
where scrolling may causearticles
to be added to or removed from either end of the list.figure
section
of content that typically contains agraphical document, images, code snippets, or example text. The parts of afigure
MAY be user-navigable.form
landmark
region that contains a collection of items and objects that, as a whole, combine to create a form. See relatedsearch
.grid
widget
containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.gridcell
cell
in agrid
ortreegrid
.group
heading
img
input
(abstract role)landmark
(abstract role)section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.link
button
.list
section
containinglistitem
elements. See relatedlistbox
.listbox
combobox
andlist
.listitem
log
marquee
.main
marquee
log
.math
menu
menubar
menu
that usually remains visible and is usually presented horizontally.menuitem
menu
ormenubar
.menuitemcheckbox
menuitem
with a checkable state whose possiblevalues aretrue
,false
, ormixed
.menuitemradio
menuitem
in a set of elements with the same role, only one of which can be checked at a time.navigation
none
presentation
.note
option
select
list.presentation
none
.progressbar
radio
radiogroup
radio
buttons.range
(abstract role)region
section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.roletype
(abstract role)row
rowgroup
rowheader
scrollbar
search
landmark
region that contains a collection of items and objects that, as a whole, combine to create a search facility. See relatedform
andsearchbox
.searchbox
textbox
andsearch
.section
(abstract role)sectionhead
(abstract role)select
(abstract role)separator
slider
spinbutton
range
that expects the user to select from among discrete choices.status
alert
, often but not necessarily presented as a status bar.structure
(abstract role)switch
checkbox
.tab
table
section
containing data arranged in rows and columns. See relatedgrid
.tablist
tab
elements, which are references totabpanel
elements.tabpanel
tab
, where eachtab
is contained in atablist
.term
definition
.textbox
timer
toolbar
tooltip
tree
list
that may contain sub-level nested groups that can be collapsed and expanded.treegrid
grid
whose rows can be expanded and collapsed in the same manner as for atree
.treeitem
tree
. This is anelement within a tree that may be expanded or collapsed if it contains a sub-level group of tree item elements.widget
(abstract role)window
(abstract role)alert
(role)§A type oflive region with important, and usually time-sensitive, information. See relatedalertdialog
andstatus
.
Alerts are used to convey messages to alert the user. In the case of audio warnings this is an accessible alternative for a hearing-impaired user. Thealert
role goes on the node containing the alert message. Alerts are specialized forms of thestatus
role, which will be processed as an atomiclive region.
Alerts are assertive live regions and will be processed as such by assistive technologies. Neither authors nor user agents are required to set or manage focus to them in order for them to be processed. Since alerts are not required to receive focus, content authorsSHOULD NOT require users to close an alert. If the operating system allows, theuser agentSHOULD fire a system alertevent through the accessibilityAPI when theWAI-ARIA alert is created. If an alert requires focus to close the alert, then content authorsSHOULD usealertdialog
instead.
Elements with the rolealert
have an implicitaria-live
value ofassertive
, and an implicitaria-atomic
value oftrue
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Related Concepts: | XForms alert |
Inherited States and Properties: |
|
Name From: | author |
Implicit Value for Role: | Default foraria-live isassertive .Default for aria-atomic istrue . |
alertdialog
(role)§A type of dialog that contains an alert message, where initial focus goes to anelement within the dialog. See relatedalert
anddialog
.
Alert dialogs are used to convey messages to alert the user. Thealertdialog
role goes on the node containing both the alert message and the rest of the dialog. Content authorsSHOULD make alert dialogs modal by ensuring that, while thealertdialog
is shown, keyboard and mouse interactions only operate within the dialog. Seearia-modal
.
Unlikealert
,alertdialog
can receive a response from the user. For example, to confirm that the user understands the alert being generated. When the alert dialog is displayed, authorsSHOULD set focus to an active element within the alert dialog, such as a form edit field or an OK button. Theuser agentSHOULD fire a system alertevent through the accessibilityAPI when the alert is created, provided one is specified by the intendedaccessibilityAPI.
AuthorsSHOULD usearia-describedby
on analertdialog
to reference the alert message element in the dialog. If they do not, anassistive technology can resort to its internal recovery mechanism to determine the contents of the alert message.
Characteristic | Value |
---|---|
Superclass Role: | |
Related Concepts: | XForms alert |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
application
(role)§Astructure
containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by awidget
role.
Someuser agents andassistive technologies have a browse mode where standard input events, such as up and down arrow key events, are intercepted and used to control a reading cursor. This browse mode behavior prevents elements that do not have awidget
role from receiving and using such keyboard and gesture events to provide interactive functionality.
When there is a need to create an element with an interaction model that is not supported by any of theWAI-ARIAwidget
roles, authorsMAY give that element roleapplication
. And, when a user navigates into an element with roleapplication
,assistive technologies that intercept standard input eventsSHOULD switch to a mode that passes most or all standard input events through to the web application.
For example, a presentation slide editor uses arrow keys to change the positions of textbox and image elements on the slide. There are not anyWAI-ARIAwidget
roles that correspond to such an interaction model so an author could give the slide container roleapplication
, anaria-roledescription
of "Slide Editor", and usearia-describedby
to provide instructions.
Because only the focusable elements contained in anapplication
element are accessible to users of some assistive technologies, authorsMUST use one of the following techniques to ensure all non-decorative static text or image content inside an application is accessible:
aria-labelledby
oraria-describedby
.document
orarticle
.aria-activedescendant
to reference theelement containing the focused content.Characteristic | Value |
---|---|
Superclass Role: | structure |
Related Concepts: | Device Independence Delivery Unit |
Supported States and Properties: | aria-activedescendant |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
article
(role)§A section of a page that consists of a composition that forms an independent part of a document, page, or site.
An article is not a navigationallandmark, but may be nested to form a discussion where assistive technologies could pay attention to article nesting to assist the user in following the discussion. An article could be a forum post, a magazine or newspaper article, a web log entry, a user-submitted comment, or any other independent item of content. It isindependent in that its contents could stand alone, for example in syndication. However, theelement is still associated with its ancestors; for instance, contact information that applies to a parent body element still covers the article as well. When nesting articles, the child articles represent content that is related to the content of the parent article. For instance, a web log entry on a site that accepts user-submitted comments could represent the comments as articles nested within the article for the web log entry. Author, heading, date, or other information associated with an article does not apply to nested articles.
When the user navigates to an element assigned the role ofarticle
,assistive technologies that typically intercept standard keyboard eventsSHOULD switch to document browsing mode, as opposed to passing keyboard events through to the web application. Assistive technologiesMAY provide a feature allowing the user to navigate the hierarchy of any nestedarticle
elements.
When anarticle
is in the context of afeed
, the authorMAY specify values foraria-posinset
andaria-setsize
.
Characteristic | Value |
---|---|
Superclass Role: | document |
Related Concepts: | HTMLarticle |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
banner
(role)§A region that contains mostly site-oriented content, rather than page-specific content.
Site-oriented content typically includes things such as the logo or identity of the site sponsor, and a site-specific search tool. A banner usually appears at the top of the page and typically spans the full width.
User agentsSHOULD treat elements with the role ofbanner
as navigationallandmarks.
Within anydocument
orapplication
, the authorSHOULD mark no more than oneelement with thebanner
role.
Becausedocument
andapplication
elements can be nested in theDOM, they may have multiplebanner
elements asDOM descendants, assuming each of those is associated with different document nodes, either by aDOM nesting (e.g.,document
withindocument
) or by use of thearia-owns
attribute.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Inherited States and Properties: |
|
Name From: | author |
button
(role)§An input that allows for user-triggered actions when clicked or pressed. See relatedlink
.
Buttons are mostly used for discrete actions. Standardizing the appearance of buttons enhances the user's recognition of thewidgets as buttons and allows for a more compact display in toolbars.
Buttons support the optionalattributearia-pressed
. Buttons with a non-emptyaria-pressed
attribute are toggle buttons. Whenaria-pressed
istrue
the button is in a "pressed"state, whenaria-pressed
isfalse
it is not pressed. If the attribute is not present, the button is a simple command button.
Characteristic | Value |
---|---|
Superclass Role: | command |
Base Concept: | HTMLbutton |
Related Concepts: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
cell
(role)§A cell in a tabular container. See relatedgridcell
.
AuthorsMUST ensureelements withrole cell are contained in, or owned by, an element with therolerow
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Base Concept: | HTMLtd |
Required Context Role: | row |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
checkbox
(role)§A checkable input that has three possiblevalues:true
,false
, ormixed
.
Thearia-checked
attribute of acheckbox
indicates whether the input is checked (true
), unchecked (false
), or represents a group ofelements that have a mixture of checked and unchecked values (mixed
). Many checkboxes do not use themixed
value, and thus are effectively boolean checkboxes.
Characteristic | Value |
---|---|
Superclass Role: | input |
Subclass Roles: | |
Related Concepts: | |
Required States and Properties: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-checked isfalse . |
columnheader
(role)§A cell containing header information for a column.
columnheader
can be used as a column header in a table or grid. It could also be used in a pie chart to show a similarrelationship in the data.
Thecolumnheader
establishes a relationship between it and all cells in the corresponding column. It is the structural equivalent to anHTMLth
element with a column scope.
AuthorsMUST ensureelements withrolecolumnheader
are contained in, or owned by, an element with the rolerow
.
Applying thearia-selected
state on a columnheaderMUST not cause the user agent to automatically propagate thearia-selected
state to all the cells in the corresponding column. An authorMAY choose to propagate selection in this manner depending on the specific application.
While thecolumnheader
role can be used in both interactive grids and non-interactive tables, the use ofaria-readonly
andaria-required
is only applicable to interactive elements. Therefore, authorsSHOULD NOT usearia-required
oraria-readonly
in acolumnheader
that descends from atable
, and user agentsSHOULD NOT expose either property toassistive technologies unless thecolumnheader
descends from agrid
.
Because cells are organized into rows, there is not a single container element for the column. The column is the set ofgridcell
elements in a particular position within their respectiverow
containers.
Characteristic | Value |
---|---|
Superclass Role: | |
Base Concept: | HTMLth[scope="col"] |
Required Context Role: | row |
Supported States and Properties: | aria-sort |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
combobox
(role)§A compositewidget
containing a single-linetextbox
and another element, such as alistbox
orgrid
, that can dynamically pop up to help the user set the value of thetextbox
.
AuthorsMUST ensure an element with rolecombobox
contains or owns a text input element with roletextbox
orsearchbox
and that the text input hasaria-multiline
set tofalse
. If thecombobox
provides autocompletion behavior for the text input as described inaria-autocomplete
, authorsMUST setaria-autocomplete
on thetextbox
element to the value that corresponds to the provided behavior.
Typically, the default state of acombobox
is collapsed. In the collapsed state, only thetextbox
element of acombobox
is visible. Acombobox
is said to be expanded when both thetextbox
and a secondary element that serves as its popup are visible. AuthorsMUST setaria-expanded
totrue
on an element with rolecombobox
when it is expanded andfalse
when it is collapsed. Elements with the rolecombobox
have an implicitaria-expanded
value offalse
.
When acombobox
is expanded, authorsMUST ensure it contains or owns an element that has a role oflistbox
,tree
,grid
, ordialog
. This element is thecombobox
popup. When thecombobox
is expanded, authorsMUST setaria-controls
on thetextbox
element to a value that refers to thecombobox
popup element.
Elements with the rolecombobox
have an implicitaria-haspopup
value oflistbox
. If thecombobox
popup element has a role other thanlistbox
, authorsMUST specify a value foraria-haspopup
that corresponds to the type of its popup.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus. When acombobox
receives focus, authorsSHOULD ensure focus is placed on thetextbox
element.
AuthorsSHOULD provide keyboard mechanisms for moving focus between thetextbox
element and the elements contained in the popup. For example, one common convention is thatDown Arrow moves focus from the text input to the first focusable descendant of the popup element. If the popup element supportsaria-activedescendant
, in lieu of moving focus, such keyboard mechanisms can control the value ofaria-activedescendant
on thetextbox
element. When a descendant of the popup element is active, authorsMAY setaria-activedescendant
on thetextbox
to a value that refers to the active element within the popup while focus remains on thetextbox
element.
<divaria-label="Tag"role="combobox"aria-expanded="true"aria-owns="owned_listbox"aria-haspopup="listbox"><inputtype="text"aria-autocomplete="list"aria-controls="owned_listbox"aria-activedescendant="selected_option"></div><ulrole="listbox"id="owned_listbox"><lirole="option">Zebra</li><lirole="option"id="selected_option">Zoom</li></ul>
The ARIA 1.0 specification describes acombobox
pattern where a text input element has thecombobox
role and owns alistbox
element.User agents,assistive technologies, and conformance checkersSHOULD continue to support the ARIA 1.0 pattern so that existing implementations of the ARIA 1.0 pattern remain functional.
The features and behaviors of combobox implementations vary widely. Consequently, there are many important authoring considerations. See theWAI-ARIA Authoring Practices Guide [wai-aria-practices-1.1] for additional details on implementing combobox design patterns.
Characteristic | Value |
---|---|
Superclass Role: | select |
Related Concepts: | |
Required Owned Elements: | textbox and, when expanded, one of: |
Required States and Properties: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default foraria-expanded isfalse .Default for aria-haspopup islistbox . |
command
(abstract role)§A form of widget that performs an action but does not receive input data.
command
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | widget |
Subclass Roles: | |
Related Concepts: | menuitem in [html51] |
Inherited States and Properties: |
|
Name From: | author |
complementary
(role)§A supporting section of the document, designed to be complementary to the main content at a similar level in theDOM hierarchy, but remains meaningful when separated from the main content.
There are various types of content that would appropriately have thisrole. For example, in the case of a portal, this may include but not be limited to show times, current weather, related articles, or stocks to watch. The complementary role indicates that contained content is relevant to the main content. If the complementary content is completely separable from the main content, it may be appropriate to use a more general role.
User agentsSHOULD treat elements with the role ofcomplementary
as navigationallandmarks.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Inherited States and Properties: |
|
Name From: | author |
composite
(abstract role)§Awidget that may contain navigable descendants or owned children.
AuthorsSHOULD ensure that a composite widget exists as a single navigation stop within the larger navigation system of the web page. Once the composite widget has focus, authorsSHOULD provide a separate navigation mechanism for users to navigate toelements that are descendants or owned children of the composite element.
composite
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | widget |
Subclass Roles: | |
Supported States and Properties: | aria-activedescendant |
Inherited States and Properties: |
|
Name From: | author |
contentinfo
(role)§A large perceivable region that contains information about the parent document.
Examples of information included in this region of the page are copyrights and links to privacy statements.
User agentsSHOULD treat elements with the role ofcontentinfo
as navigationallandmarks.
Within anydocument
orapplication
, the authorSHOULD mark no more than oneelement with thecontentinfo
role.
Becausedocument
andapplication
elements can be nested in theDOM, they may have multiplecontentinfo
elements asDOM descendants, assuming each of those is associated with different document nodes, either by aDOM nesting (e.g.,document
withindocument
) or by use of thearia-owns
attribute.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Inherited States and Properties: |
|
Name From: | author |
definition
(role)§A definition of a term or concept. See relatedterm
.
AuthorsSHOULD identify theelement being defined by giving that element a role ofterm
and referencing it with thearia-labelledby
attribute.
Characteristic | Value |
---|---|
Superclass Role: | section |
Related Concepts: | |
Inherited States and Properties: |
|
Name From: | author |
dialog
(role)§A dialog is a descendant window of the primary window of a web application. ForHTML pages, the primary application window is the entire web document, i.e., thebody
element.
Dialogs are most often used to prompt the user to enter or respond to information. A dialog that is designed to interrupt workflow is usually modal. See relatedalertdialog
.
AuthorsSHOULD provide a dialog label, which can be done with thearia-label
oraria-labelledby
attribute.
AuthorsSHOULD ensure that all dialogs (both modal and non-modal) have at least one focusable descendant element. AuthorsSHOULD focus an element in the modal dialog when it is displayed, and authorsSHOULD manage focus of modal dialogs.
In the description of this role, the term "web application" does not refer to theapplication
role, which specifies specific assistive technology behaviors.
Characteristic | Value |
---|---|
Superclass Role: | window |
Subclass Roles: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
directory
(role)§A list of references to members of a group, such as a static table of contents.
AuthorsSHOULD use thisrole for a static table of contents, whether linked or unlinked. This includes tables of contents built with lists, including nested lists. Dynamic tables of contents, however, might use atree
role instead.
Characteristic | Value |
---|---|
Superclass Role: | list |
Related Concepts: | DAISY Guide |
Inherited States and Properties: |
|
Name From: | author |
document
(role)§Anelement containing content thatassistive technology users may want to browse in a reading mode.
Whenuser agent focus moves to an element assigned the role ofdocument
,assistive technologies having a reading mode for browsing static contentMAY switch to that reading mode and intercept standard input events, such as Up or Down arrow keyboard events, to control the reading cursor.
Becauseassistive technologies that have a reading mode default to that mode for all elements except for those with either awidget
orapplication
role, the only circumstance where thedocument
role is useful for changing assistive technology behavior is when the element with roledocument
is a focusable child element of awidget
orapplication
. For example, given anapplication
element which contains some static rich text, the author can apply roledocument
to the element containing the text and give it atabindex
of0
. When a screen reader user presses the Tab key and places focus on thedocument
element, the user will be able to read the text with the screen reader's reading cursor.
Characteristic | Value |
---|---|
Superclass Role: | structure |
Subclass Roles: | |
Related Concepts: | Device Independence Delivery Unit |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | False |
feed
(role)§A scrollablelist
ofarticles
where scrolling may causearticles to be added to or removed from either end of the list.
Afeed
enables users ofassistive technologies that have a document browse mode, such as screen readers, to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. In afeed
,assistive technologies provide a web application with signals of the user's reading cursor movement by movinguser agent focus, enabling the application to both add new content and visually position content as the user browses the page. Thefeed
also lets authors inform assistive technologies when additions and removals are occurring so assistive technologies can more reliably update their reading view without disrupting reading or degrading performance.
For example, afeed
could be used to present a stream of news stories where eacharticle
contains a story with text, links, images, and comments as well as widgets for sharing and commenting. As a screen reader user reads and interacts with each story and moves the screen reader reading cursor from story to story, each story scrolls into view and, as needed, new stories are loaded.
Afeed
is a container element whose children have rolearticle
. Whenarticles are added or removed from either or both ends of afeed
, authorsSHOULD setaria-busy
totrue
on thefeed
element before the changes are made and set it tofalse
after the changes are complete. AuthorsSHOULD avoid inserting or removingarticles in the middle of afeed
. These requirements helpassistive technologies gracefully respond to changes in thefeed
content that occur simultaneously with user commands to move the reading cursor within thefeed
.
AuthorsSHOULD make eacharticle
in afeed
focusable and ensure that the application scrolls anarticle
into view whenuser agent focus is set on thearticle
or one of its descendant elements. For example, inHTML, eacharticle
element should have atabindex
value of either-1
or0
.
When anassistive technology reading cursor moves from onearticle
to another,assistive technologiesSHOULD set user agent focus on thearticle
that contains the reading cursor. If the reading cursor lands on a focusable element inside thearticle
, the assistive technologyMAY set focus on that element in lieu of setting focus on the containingarticle
.
Because the ability to scroll to anotherarticle
with anassistive technology reading cursor depends on the presence of anotherarticle
in the page, authorsSHOULD attempt to load additionalarticles beforeuser agent focus reaches anarticle
at either end of the set ofarticles that has been loaded. Alternatively, authorsMAY include anarticle
at either or both ends of the loaded set ofarticles that includes an element, such as abutton
, that lets the user request morearticles to be loaded.
In addition to providing a brief label, authorsMAY applyaria-describedby
toarticle
elements in afeed
to suggest to screen readers which elements to speak after the label when users navigate byarticle
. Screen readersMAY provide users with a way to quickly scanfeed
content by speaking both the label and accessible description when navigating byarticle
, enabling the user to ignore repetitive or less important elements, such as embedded interaction widgets, that the author has left out of the description.
AuthorsSHOULD provide keyboard commands for moving focus amongarticles in afeed
so users who do not utilize an assistive technology that providesarticle
navigation features can use the keyboard to navigate thefeed
.
If the number of articles available in afeed
supply is static, authorsMAY specifyaria-setsize
onarticle
elements in thatfeed
. However, if the total number is extremely large, indefinite, or changes often, authorsMAY setaria-setsize
to-1
to communicate the unknown size of the set.
See theWAI-ARIA Authoring Practices [wai-aria-practices-1.1] for additional details on implementing a feed design pattern.
Characteristic | Value |
---|---|
Superclass Role: | list |
Required Owned Elements: | article |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | False |
figure
(role)§A perceivablesection
of content that typically contains agraphical document, images, code snippets, or example text. The parts of afigure
MAY be user-navigable.
AuthorsSHOULD provide a reference to thefigure
from the main text, but thefigure
need not be displayed at the same location as the referencing element. AuthorsMAY reference text serving as a caption usingaria-describedby
. AuthorsMAY provide a label usingaria-label
orMAY reference text serving as a label usingaria-labelledby
.
Assistive technologiesSHOULD enable users to quickly navigate to figures. Mainstreamuser agentsMAY enable users to quickly navigate to figures.
Characteristic | Value |
---|---|
Superclass Role: | section |
Related Concepts: | HTMLfigure |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | False |
form
(role)§Alandmark
region that contains a collection of items and objects that, as a whole, combine to create a form. See relatedsearch
.
A form may be a mix of host language form controls, scripted controls, and hyperlinks. Authors are reminded to use native host language semantics to create form controls, whenever possible. For search facilities, authorsSHOULD use thesearch
role and not the genericform
role. AuthorsSHOULD provide a visible label for the form referenced witharia-labelledby
. If an author uses a script to submit a form based on a user action that would otherwise not trigger anonsubmit
event (for example, a form submission triggered by the user changing a form element's value), the authorSHOULD provide the user with advance notification of the behavior.
User agentsSHOULD treat elements with the role ofform
as navigationallandmarks.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Base Concept: | HTMLform |
Inherited States and Properties: |
|
Name From: | author |
grid
(role)§A compositewidget
containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.
Thegrid
role does not imply a specific visual, e.g., tabular, presentation. It describesrelationships amongelements. It may be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.
The cell elements of agrid
have rolegridcell
. AuthorsMAY designate a cell as a row or column header by using either therowheader
orcolumnheader
role in lieu of thegridcell
role. AuthorsMUST ensure elements with rolegridcell
,columnheader
, orrowheader
areowned by elements with rolerow
, which are in turn owned by an element with rolerowgroup
, orgrid
.
To bekeyboard accessible, authorsSHOULD manage focus of descendants of agrid
as described inManaging Focus. When a user is navigating thegrid
content with a keyboard, authorsSHOULD set focus as follows:
gridcell
contains a single interactivewidget
that will not consume arrow key presses when it receives focus, such as acheckbox
,button
, orlink
, authorsMAY set focus on the interactive element contained in that cell. This allows the contained widget to be directly operable.gridcell
,rowheader
, orcolumnheader
element.AuthorsSHOULD provide a mechanism for changing to an interaction or edit mode that allows users to navigate and interact with content contained inside a focusable cell if that focusable cell contains any of the following:
combobox
orradiogroup
For example, if a cell in a spreadsheet contains acombobox
or editable text, theEnter key might be used to activate a cell interaction or editing mode when that cell has focus so the directional arrow keys can be used to operate the containedcombobox
ortextbox
. Depending on the implementation, pressingEnter again,Tab,Escape, or another key may switch the application back to the grid navigation mode.
AuthorsMAY use agridcell
to display the result of a formula, which could be editable by the user. In a spreadsheet application, for example, agridcell
may show a value calculated from a formula until the user activates thegridcell
for editing when atextbox
appears in thegridcell
containing the formula in an editable state.
Ifaria-readonly
is set on an element with rolegrid
,user agentsMUST propagate the value to allgridcell
elements owned by thegrid
and expose the value in the accessibilityAPI. An authorMAY override the propagated value ofaria-readonly
for an individualgridcell
element.
In agrid
that provides cell content editing functions, if the content of a focusablegridcell
element is not editable, authorsMAY setaria-readonly
totrue
on thegridcell
element. However, the value ofaria-readonly
, whether specified for agrid
or individual cells, only indicates whether the content contained in cells is editable. It does not represent availability of functions for navigating or manipulating thegrid
itself.
An unspecified value foraria-readonly
does not imply that agrid
or agridcell
contains editable content. For example, if agrid
presents a collection of elements that are not editable, such as a collection oflink
elements representing dates in a datepicker, it is not necessary for the author to specify a value foraria-readonly
.
AuthorsMAY indicate that a focusablegridcell
is selectable as the object of an action with thearia-selected
attribute. If thegrid
allows multiplegridcell
s to be selected, the authorSHOULD setaria-multiselectable
totrue
on the element with rolegrid
.
SinceWAI-ARIA can augment an element of the host language, agrid
can reuse the elements and attributes of a native table, such as anHTMLtable
element. For example, if an author applies thegrid
role to anHTMLtable
element, the author does not need to apply therow
andgridcell
roles to the descendantHTMLtr
andtd
elements because theuser agent will automatically make the appropriate translations. When the author is reusing a native host language table element and needs agridcell
element to span multiple rows or columns, the authorSHOULD apply the appropriate host language attributes instead ofWAI-ARIAaria-rowspan
oraria-colspan
properties.
See theWAI-ARIA Authoring Practices Guide [wai-aria-practices-1.1] for additional details on implementing grid design patterns.
Characteristic | Value |
---|---|
Superclass Role: | |
Subclass Roles: | |
Base Concept: | HTMLtable |
Required Owned Elements: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
gridcell
(role)§Agridcell
may be focusable, editable, and selectable. Agridcell
may haverelationships such asaria-controls
to address the application of functional relationships.
If an author intends agridcell
to have a row header, column header, or both, and if the relevant headers cannot be determined from theDOM structure, authorsSHOULD explicitly indicate which header cells are relevant to thegridcell
by applyingaria-describedby
on thegridcell
and referencingelements withrolerowheader
orcolumnheader
.
In atreegrid
, authorsMAY define agridcell
as expandable by using thearia-expanded
attribute. If thearia-expanded
attribute is provided, it applies only to the individual cell. It is not a proxy for the containerrow
, which also can be expanded. The main use case for providing this attribute on agridcell
is pivot table behavior.
AuthorsMUST ensureelements withrole gridcell are contained in, or owned by, an element with therolerow
.
Characteristic | Value |
---|---|
Superclass Role: | |
Subclass Roles: | |
Base Concept: | HTMLtd |
Required Context Role: | row |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
group
(role)§A set of user interfaceobjects which are not intended to be included in a page summary or table of contents byassistive technologies.
Contrast withregion
which is a grouping of user interface objects that will be included in a page summary or table of contents.
AuthorsSHOULD use agroup
to form logical collection of items in awidget such as children in a tree widget forming a collection of siblings in a hierarchy, or a collection of items having the same container in a directory. However, when agroup
is used in the context of list, authorsMUST limit its children tolistitem
elements. Therefore, proper handling ofgroup
by authors and assistive technologies is determined by the context in which it is provided.
AuthorsMAY nestgroup
elements. If a section is significant enough to warrant inclusion in the web page's table of contents, the authorSHOULD assign the section arole ofregion
or astandard landmark role.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Related Concepts: | HTMLfieldset |
Supported States and Properties: | aria-activedescendant |
Inherited States and Properties: |
|
Name From: | author |
heading
(role)§A heading for a section of the page.
Often,heading
elements will be referenced with thearia-labelledby
attribute of the section for which they serve as a heading. If headings are organized into a logical outline, thearia-level
attribute is used to indicate the nesting level.
Characteristic | Value |
---|---|
Superclass Role: | sectionhead |
Related Concepts: | HTMLh1 ,h2 ,h3 ,h4 ,h5 , andh6 |
Required States and Properties: | aria-level |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Implicit Value for Role: | Default foraria-level is2 . |
img
(role)§A container for a collection ofelements that form an image.
Animg
can contain captions and descriptive text, as well as multiple image files that when viewed together give the impression of a single image. Animg
represents a single graphic within a document, whether or not it is formed by a collection of drawingobjects. In order for elements with arole ofimg
beperceivable, authorsMUST provide alternative text or a label determined by theaccessible name calculation.
Characteristic | Value |
---|---|
Superclass Role: | section |
Related Concepts: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
input
(abstract role)§A generic type ofwidget that allows user input.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | widget |
Subclass Roles: | |
Related Concepts: | XForms input |
Inherited States and Properties: |
|
Name From: | author |
landmark
(abstract role)§A perceivablesection
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
Authors designate the purpose of the content by assigning a role that is a subclass of the landmark role and, when needed, by providing a brief, descriptive label.
Elements with a role that is a subclass of the landmark role are known as landmark regions or navigational landmark regions.Assistive technologiesSHOULD enable users to quickly navigate to landmark regions. Mainstreamuser agentsMAY enable users to quickly navigate to landmark regions.
landmark
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | section |
Subclass Roles: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | False |
link
(role)§An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See relatedbutton
.
If this is a native link in the host language (such as anHTML anchor with anhref
value), activating the link causes theuser agent to navigate to that resource. If this is a simulated link, the web application author is responsible for managing navigation.
If pressing the link triggers an action but does not change browser focus or page location, authors are advised to consider using thebutton
role instead of thelink
role.
Characteristic | Value |
---|---|
Superclass Role: | command |
Related Concepts: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
list
(role)§Asection
containinglistitem
elements. See relatedlistbox
.
Lists contain children whoserole islistitem
, or elements whoserole isgroup
which in turn contains children whoserole islistitem
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Base Concept: | |
Required Owned Elements: | |
Inherited States and Properties: |
|
Name From: | author |
listbox
(role)§Awidget that allows the user to select one or more items from a list of choices. See relatedcombobox
andlist
.
Items within the list are static and, unlike standardHTMLselect
elements, may contain images. List boxes contain children whoserole isoption
.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus.
Elements with the rolelistbox
have an implicitaria-orientation
value ofvertical
.
Characteristic | Value |
---|---|
Superclass Role: | |
Related Concepts: | |
Required Owned Elements: | option |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default foraria-orientation isvertical . |
listitem
(role)§A single item in a list or directory.
AuthorsMUST ensureelements withrolelistitem
are contained in, or owned by, anelement with therolelist
orgroup
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Base Concept: | HTMLli |
Related Concepts: | XForms item |
Required Context Role: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
log
(role)§A type oflive region where new information is added in meaningful order and old information may disappear. See relatedmarquee
.
Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in thisrole there is arelationship between the arrival of new items in the log and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points.
Elements with the rolelog
have an implicitaria-live
value ofpolite
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default foraria-live ispolite . |
main
(role)§The main content of a document.
This marks the content that is directly related to or expands upon the central topic of the document. Themain
role is a non-obtrusive alternative for "skip to main content" links, where the navigation option to go to the main content (or otherlandmarks) is provided by theuser agent through a dialog or byassistive technologies.
User agentsSHOULD treat elements with the role ofmain
as navigational landmarks.
Within anydocument
orapplication
, the authorSHOULD mark no more than oneelement with themain
role.
Becausedocument
andapplication
elements can be nested in theDOM, they may have multiplemain
elements asDOM descendants, assuming each of those is associated with different document nodes, either by aDOM nesting (e.g.,document
withindocument
) or by use of thearia-owns
attribute.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Inherited States and Properties: |
|
Name From: | author |
marquee
(role)§A type oflive region where non-essential information changes frequently. See relatedlog
.
Common usages ofmarquee
include stock tickers and ad banners. The primary difference between amarquee
and alog
is that logs usually have a meaningful order or sequence of important content changes.
Elements with the rolemarquee
have an implicitaria-live
value ofoff
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
math
(role)§Content that represents a mathematical expression.
Content with the rolemath
is intended to be marked up in an accessible format such asMathML [MathML3], or with another type of textual representation such as TeX or LaTeX, which can be converted to an accessible format by native browser implementations or a polyfill library.
While it is not ideal to use an image of a mathematical expression, there exists a significant amount of legacy content where images are used to represent mathematical expressions. AuthorsSHOULD ensure that images of math are labeled by text that describes the mathematical expression as it might be spoken.
Browsers that support native implementations ofMathML are able to provide a more robust, accessible math experience than can be accomplished with plain text approximations of math. Some rendering engines have close integration with screen readers that allow spacial touch exploration of the formula and refreshable braille display output in theNemeth Braille format. This level of integration is not supported with images of mathematical formulas, even if the author provides a plain text approximation.
At the time of this writing, some mainstream browsers do not supportMathML natively, and must be retrofit using a JavaScript polyfill library. When authoring math content, use nativeMathML wherever possible, and test thoroughly. Use a polyfill library or provide a fallback image with a text alternative approximation if necessary.
<!--Note: Use a JavaScript polyfill library to ensure this renders in user agents that do not support MathML. --><!-- The math element has an implicit role="math". --><mathxmlns="http://www.w3.org/1998/Math/MathML"><mrow><mi>x</mi><mo>=</mo><mfrac><mrow><moform="prefix">−</mo><mi>b</mi><mo>±</mo><msqrt><msup><mi>b</mi><mn>2</mn></msup><mo>−</mo><mn>4</mn><mo>⁢<!-- ⁢ --></mo><mi>a</mi><mo>⁢<!-- ⁢ --></mo><mi>c</mi></msqrt></mrow><mrow><mn>2</mn><mo>⁢<!-- ⁢ --></mo><mi>a</mi></mrow></mfrac></mrow><annotationencoding="TeX"> x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}</annotation></math>
If a rendering engine does not support a native math format such asMathML, authorsMAY use JavaScript to downgrade the content to a format the browser can display, such as thisHTML image using a dataURI and plain text alternative.
<imgrole="math"src="..."alt="x=⟮−b±√⟮b²−4ac⟯⟯÷2a">
Characteristic | Value |
---|---|
Superclass Role: | section |
Inherited States and Properties: |
|
Name From: | author |
Children Presentational: | True |
menu
(role)§A type ofwidget that offers a list of choices to the user.
A menu is often a list of common actions or functions that the user can invoke. Themenu
role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus.
Elements with the rolemenu
have an implicitaria-orientation
value ofvertical
.
Characteristic | Value |
---|---|
Superclass Role: | |
Subclass Roles: | |
Related Concepts: | |
Required Owned Elements: | |
Inherited States and Properties: |
|
Name From: | author |
Implicit Value for Role: | Default foraria-orientation isvertical . |
menubar
(role)§A presentation ofmenu
that usually remains visible and is usually presented horizontally.
Themenubar
role is used to create a menu bar similar to those found in Windows, Mac, and Gnome desktop applications. A menu bar is used to create a consistent set of frequently used commands. AuthorsSHOULD ensure thatmenubar
interaction is similar to the typical menu bar interaction in a desktop graphical user interface.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus.
Elements with the rolemenubar
have an implicitaria-orientation
value ofhorizontal
.
Characteristic | Value |
---|---|
Superclass Role: | menu |
Related Concepts: | toolbar |
Required Owned Elements: | |
Inherited States and Properties: |
|
Name From: | author |
Implicit Value for Role: | Default foraria-orientation ishorizontal . |
menuitem
(role)§An option in a set of choices contained by amenu
ormenubar
.
AuthorsMAY disable a menu item with thearia-disabled
attribute. If the menu item has itsaria-haspopup
attribute set totrue
, it indicates that the menu item may be used to launch a sub-level menu, and authorsSHOULD display a new sub-level menu when the menu item is activated.
AuthorsMUST ensure that menu items areowned by an element with rolemenu
ormenubar
in order to identify that they are relatedwidgets. AuthorsMAY separate menu items into sets by use of aseparator
or an element with an equivalent role from the native markup language.
Characteristic | Value |
---|---|
Superclass Role: | |
Subclass Roles: | |
Related Concepts: | |
Required Context Role: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
menuitemcheckbox
(role)§Amenuitem
with a checkable state whose possiblevalues aretrue
,false
, ormixed
.
Thearia-checked
attribute of amenuitemcheckbox
indicates whether the menu item is checked (true
), unchecked (false
), or represents a sub-level menu of other menu items that have a mixture of checked and unchecked values (mixed
).
AuthorsMUST ensure that menu item checkboxes areowned by an element with rolemenu
ormenubar
in order to identify that they are related widgets. AuthorsMAY separate menu items into sets by use of aseparator
or an element with an equivalent role from the native markup language.
Characteristic | Value |
---|---|
Superclass Role: | |
Subclass Roles: | |
Related Concepts: | menuitem |
Required Context Role: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-checked isfalse . |
menuitemradio
(role)§A checkablemenuitem
in a set of elements with the same role, only one of which can be checked at a time.
AuthorsSHOULD enforce that only onemenuitemradio
in a group can be checked at the same time. When one item in the group is checked, the previously checked item becomes unchecked (itsaria-checked
attribute becomesfalse
).
AuthorsMUST ensure that menu item radios areowned by an element with rolegroup
,menu
, ormenubar
in order to identify that they are related widgets. AuthorsMAY separate menu items into sets by use of aseparator
or an element with an equivalent role from the native markup language.
If amenu
ormenubar
contains more than one group ofmenuitemradio
elements, or if the menu contains one group and other, unrelated menu items, authorsSHOULD nest each set of relatedmenuitemradio
elements in an element using thegroup
role, and authorsSHOULD delimit the group from other menu items with an element using theseparator
role.
Characteristic | Value |
---|---|
Superclass Role: |
|
Related Concepts: | menuitem |
Required Context Role: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-checked isfalse . |
navigation
(role)§A collection of navigationalelements (usually links) for navigating the document or related documents.
User agentsSHOULD treat elements with the role ofnavigation
as navigationallandmarks.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Related Concepts: | HTMLnav |
Inherited States and Properties: |
|
Name From: | author |
none
(role)§Anelement whose implicit native role semantics will not be mapped to theaccessibilityAPI. See synonympresentation
.
none
role.§In ARIA 1.1, the working group introducednone
as a synonym to thepresentation
role, due to author confusion surrounding the intended meaning of the word "presentation" or "presentational." Many individuals erroneously considerrole="presentation"
to be synonymous witharia-hidden="true"
, and we believerole="none"
conveys the actual meaning more unambiguously.
Until implementations include sufficient support forrole="none"
, web authors are advised to use thepresentation
role alonerole="presentation"
or redundantly as a fallback to thenone
rolerole="none presentation"
.
note
(role)§A section whose content is parenthetic or ancillary to the main content of the resource.
Characteristic | Value |
---|---|
Superclass Role: | section |
Inherited States and Properties: |
|
Name From: | author |
option
(role)§A selectable item in aselect
list.
AuthorsMUST ensureelements withroleoption
are contained in, or owned by, an element with therolelistbox
. Options not associated with alistbox
might not be correctly mapped to anaccessibilityAPI.
Elements with the roleoption
have an implicitaria-selected
value offalse
.
Characteristic | Value |
---|---|
Superclass Role: | input |
Subclass Roles: | |
Base Concept: | HTMLoption |
Related Concepts: | |
Required Context Role: | listbox |
Required States and Properties: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-selected isfalse . |
presentation
(role)§Anelement whose implicit native role semantics will not be mapped to theaccessibilityAPI. See synonymnone
.
none
role.§In ARIA 1.1, the working group introducednone
as a synonym to thepresentation
role, due to author confusion surrounding the intended meaning of the word "presentation" or "presentational." Many individuals erroneously considerrole="presentation"
to be synonymous witharia-hidden="true"
, and we believerole="none"
conveys the actual meaning more unambiguously.
Until implementations include sufficient support forrole="none"
, web authors are advised to use thepresentation
role alonerole="presentation"
or redundantly as a fallback to thenone
rolerole="none presentation"
.
The intended use is when an element is used to change the look of the page but does not have all the functional, interactive, or structural relevance implied by the element type, or may be used to provide for an accessible fallback in older browsers that do not supportWAI-ARIA.
Example use cases:
img
role and where the full text alternative is available and is marked up witharia-labelledby
and (if needed)aria-describedby
;For any element with a role of presentation and which is not focusable, the user agentMUST NOT expose the implicit native semantics of the element (the role and its states and properties) to accessibilityAPIs. However, the user agentMUST expose content and descendant elements that do not have an explicit or inherited role of presentation. Thus, thepresentation
role causes a given element to be treated as having no role or to be removed from the accessibility tree, but does not cause the content contained within the element to be removed from the accessibility tree.
For example, according to an accessibilityAPI, the following markup elements would appear to have identical role semantics (no role) and identical content.
<!-- 1. [role="presentation"] negates the implicit 'heading' role semantics but does not affect the contents. --><h1role="presentation"> Sample Content</h1><!-- 2. There is no implicit role for span, so only the contents are exposed. --><span> Sample Content</span><!-- 3. Depending on styling and other factors, this role declaration is redundant in some implementations. --><spanrole="presentation"> Sample Content</span><!-- 4. In all cases, the element contents are exposed to accessibility APIs without any implied role semantics. --><!-- <> --> Sample Content<!-- </> -->
Thepresentation
role is used on an element that has implicit native semantics, meaning that there is a default accessibilityAPI role for the element. Some elements are only complete when additional descendant elements are provided. For example, inHTML, table elements (matching thegrid
role) requiretr
descendants (therow
role), which in turn requireth
ortd
children (thegridcell
,columnheader
,rowheader
roles). Similarly, lists require list item children. The descendant elements that complete the semantics of an element are described inWAI-ARIA asrequired owned elements.
When an explicit or inherited role ofpresentation
is applied to an element with the implicit semantic of aWAI-ARIA role that hasrequired owned elements, in addition to the element with the explicit role ofpresentation
, the user agentMUST apply an inherited role of presentation to any owned elements that do not have an explicit role defined. Also, when an explicit or inherited role of presentation is applied to a host language element which has required children as defined by the host language specification, in addition to the element with the explicit role of presentation, the user agentMUST apply an inherited role of presentation to any required children that do not have an explicit role defined.
InHTML, theimg
element is treated as a single entity regardless of the type of image file. Consequently, usingrole="presentation"
orrole="none"
on anHTMLimg
is equivalent to usingaria-hidden="true"
. In order to make the image contents accessible, authors can embed the object using anobject
oriframe
element, or use inlineSVG code, and follow the accessibility guidelines for the image content.
For any element with an explicit or inherited role of presentation and which is not focusable, user agentsMUST ignore role-specificWAI-ARIA states and properties for that element. For example, inHTML, aul
orol
element with a role ofpresentation
will have the implicit native semantics of itsli
elements removed because thelist
role to which theul
orol
corresponds has arequired owned element oflistitem
. Likewise, although anHTMLtable
element does not have an implicit native semantic role corresponding directly to aWAI-ARIA role, the implicit native semantics of itsthead
/tbody
/tfoot
/tr
/th
/td
descendants will also be removed, because theHTML specification indicates that these are required structural descendants of thetable
element.
Only the implicit native semantics of elements that correspond toWAI-ARIArequired owned elements are removed. All other content remains intact, including nested tables or lists, unless those elements also have a explicit role ofpresentation
applied.
For example, according to an accessibilityAPI, the following markup elements would appear to have identical role semantics (no roles) and identical content.
<!-- 1. [role="presentation"] negates the implicit 'list' and 'listitem' role semantics but does not affect the contents. --><ulrole="presentation"><li> Sample Content</li><li> More Sample Content</li></ul><!-- 2. There is no implicit role for "foo", so only the contents are exposed. --><foo><foo> Sample Content</foo><foo> More Sample Content</foo></foo>
For any element with an explicit or inherited role ofpresentation
, user agentsMUST apply an inherited role ofpresentation
to all host-language-specific labeling elements for the presentational element. For example, atable
element with a role ofpresentation
will have the implicit native semantics of itscaption
element removed, because the caption is merely a label for the presentational table.
AuthorsSHOULD NOT provide meaningful alternative text (for example, usealt=""
inHTML) when thepresentation
role is applied to an image.
In the following code sample, the containingimg
and is appropriately labeled by the caption paragraph. In this example theimg
element can be marked as presentation because the role and the text alternatives are provided by the containing element.
<div role="img" aria-labelledby="caption"><imgsrc="example.png"role="presentation"alt=""><pid="caption">A visible text caption labeling the image.</p></div>
In the following code sample, because the anchor (HTMLa
element) is acting as the treeitem, the list item (HTMLli
element) is assigned an explicitWAI-ARIA role of presentation to override the user agent's implicit native semantics for list items.
<ulrole="tree"><lirole="presentation"><arole="treeitem"aria-expanded="true">An expanded tree node</a></li> …</ul>
There are a number of ways presentational role conflicts are resolved.
Host languages elements, having implicit presentational roles for which no roles, may be applied,MUST never be exposed to in the accessibility tree. With this exception, user agentsMUST always expose globalWAI-ARIA states and properties to accessibilityAPIs. In this case, the user agent ignores thepresentation
role and exposes the element according to its implicit native semantics. However, user agentsMUST ignore any non-global, role-specificWAI-ARIA states and properties, unless it is on an inherited presentational role where an explicit role is applied.
For example,aria-haspopup
is a global attribute and would always be applied;aria-level
is not a global attribute and would therefore only apply if the element was not in a presentational state.
<!-- 1. [role="presentation"] is ignored due to the global aria-haspopup property. --><h1role="presentation"aria-haspopup="true"> Sample Content</h1><!-- 2. [role="presentation"] negates the both the implicit 'heading' and the non-global level. --><h1role="presentation"aria-level="2"> Sample Content</h1>
Explicit roles on a descendant orowned element override the inherited role ofpresentation
, and cause the owned element to behave as any other element with an explicit role. If the action of exposing the implicit role causes the accessibility tree to be malformed, the expected results are undefined and the user agentMAY resort to an internal recovery mechanism to repair the accessibility tree.
If an element with a role of presentation is focusable, or otherwise interactive, user agentsMUST ignore the normal effect of the role and expose the element with implicit native semantics, in order to ensure that the element is bothunderstandable andoperable.
User agentsMUST always expose globalWAI-ARIA states and properties to accessibilityAPIs, even if an element has an explicit or inherited role of presentation. In this case, the user agent ignores thepresentation
role and exposes the element according to its implicit native semantics. However, user agentsMUST ignore any non-global, role-specificWAI-ARIA states and properties, unless it is on an inherited presentational role where an explicit role is applied.
Characteristic | Value |
---|---|
Superclass Role: | structure |
Inherited States and Properties: |
|
Name From: | author (if role discarded by error conditions) |
progressbar
(role)§Anelement that displays the progress status for tasks that take a long time.
A progressbar indicates that the user's request has been received and the application is making progress toward completing the requested action. The authorSHOULD supplyvalues foraria-valuenow
,aria-valuemin
, andaria-valuemax
, unless the value is indeterminate, in which case the authorSHOULD omit thearia-valuenow
attribute. AuthorsSHOULD update these values when the visual progress indicator is updated. If theprogressbar
is describing the loading progress of a particular region of a page, the authorSHOULD usearia-describedby
to point to the status, and set thearia-busy
attribute totrue
on the region until it is finished loading. It is not possible for the user to alter the value of aprogressbar
because it is always readonly.
Assistive technologies generally will render the value ofaria-valuenow
as a percent of a range between the value ofaria-valuemin
andaria-valuemax
, unlessaria-valuetext
is specified. It is best to set the values foraria-valuemin
,aria-valuemax
, andaria-valuenow
in a manner that is appropriate for this calculation.
Characteristic | Value |
---|---|
Superclass Role: | range |
Related Concepts: | status |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
radio
(role)§A checkable input in a group of elements with the same role, only one of which can be checked at a time.
AuthorsSHOULD ensure thatelements with roleradio
are explicitly grouped in order to indicate which ones affect the same value. This is achieved by enclosing the radio elements in an element with roleradiogroup
. If it is not possible to make the radio buttonsDOM children of theradiogroup
, authorsSHOULD use thearia-owns
attribute on theradiogroup
element to indicate therelationship to its children.
Characteristic | Value |
---|---|
Superclass Role: | |
Subclass Roles: | |
Related Concepts: | HTMLinput[type="radio"] |
Required States and Properties: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-checked isfalse . |
radiogroup
(role)§A group ofradio
buttons.
Aradiogroup
is a type ofselect
list that can only have a single entry checked at any one time. AuthorsSHOULD enforce that only one radio button in a group can be checked at the same time. When one item in the group is checked, the previously checked item becomes unchecked (itsaria-checked
attribute becomesfalse
).
Characteristic | Value |
---|---|
Superclass Role: | select |
Related Concepts: | list |
Required Owned Elements: | radio |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
range
(abstract role)§An input representing a range of values that can be set by the user.
range
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | widget |
Subclass Roles: | |
Supported States and Properties: | aria-valuetext |
Inherited States and Properties: |
|
Name From: | author |
region
(role)§A perceivablesection
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
AuthorsSHOULD limit use of the region role to sections containing content with a purpose that is not accurately described by one of the otherlandmark
roles, such asmain
,complementary
, ornavigation
.
AuthorsMUST give each element with role region a brief label that describes the purpose of the content in the region. AuthorsSHOULD reference a visible label witharia-labelledby
if a visible label is present. AuthorsSHOULD include the label inside of a heading whenever possible. The headingMAY be an instance of the standard host language heading element or an instance of an element with roleheading
.
Assistive technologiesSHOULD enable users to quickly navigate to elements with role region. Mainstreamuser agentsMAY enable users to quickly navigate to elements with role region.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Related Concepts: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
roletype
(abstract role)§The baserole from which all other roles in thistaxonomy inherit.
Properties of this role describe the structural and functional purpose ofobjects that are assigned this role (known inRDF terms as "instances"). A role is a concept that can be used to understand and operate instances.
roletype
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Subclass Roles: | |
Related Concepts: | |
Supported States and Properties: |
|
Name From: |
row
(role)§A row of cells in a tabular container.
Rows containcell
orgridcell
elements, and thus serve to organize thetable
orgrid
.
In atreegrid
, authorsMAY mark rows as expandable, using thearia-expanded
attribute to indicate the present status. This is not the case for an ordinarytable
orgrid
, in which thearia-expanded
attribute is not present.
AuthorsMUST ensureelements withrolerow
are contained in, orowned by, an element with the roletable
,grid
,rowgroup
, ortreegrid
.
Characteristic | Value |
---|---|
Superclass Role: | |
Base Concept: | HTMLtr |
Required Context Role: | |
Required Owned Elements: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
rowgroup
(role)§A structure containing one or more row elements in a tabular container.
Therowgroup
role establishes arelationship betweenownedrow
elements. It is a structural equivalent to thethead
,tfoot
, andtbody
elements in anHTMLtable
element.
AuthorsMUST ensureelements withrolerowgroup
are contained in, orowned by, an element with the roletable
orgrid
.
Therowgroup
role exists, in part, to support role symmetry inHTML, and allows for the propagation of presentation inheritance onHTMLtable
elements with an explicitpresentation
role applied.
This role does not differentiate between types of row groups (e.g.,thead
vs.tbody
), but an issue has been raised forWAI-ARIA 2.0.
Characteristic | Value |
---|---|
Superclass Role: | structure |
Base Concept: | |
Required Context Role: | |
Required Owned Elements: | row |
Inherited States and Properties: |
|
Name From: |
|
rowheader
(role)§A cell containing header information for a row in a grid.
Rowheader can be used as a row header in a table or grid. The rowheader establishes arelationship between it and all cells in the corresponding row. It is a structural equivalent to settingscope="row"
on anHTMLth
element.
AuthorsMUST ensureelements withrolerowheader
are contained in, orowned by, an element with the rolegrid
.
Applying thearia-selected
state on a rowheaderMUST not cause the user agent to automatically propagate thearia-selected
state to all the cells in the corresponding row. An authorMAY choose to propagate selection in this manner depending on the specific application.
While therowheader
role can be used in both interactive grids and non-interactive tables, the use ofaria-readonly
andaria-required
is only applicable to interactive elements. Therefore, authorsSHOULD NOT usearia-required
oraria-readonly
in arowheader
that descends from atable
, and user agentsSHOULD NOT expose either property toassistive technologies unless therowheader
descends from agrid
.
Characteristic | Value |
---|---|
Superclass Role: | |
Base Concept: | HTMLth[scope="row"] |
Required Context Role: | row |
Supported States and Properties: | aria-sort |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
scrollbar
(role)§A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.
A scrollbar represents the current value and range of possible values via the size of the scrollbar and position of the thumb with respect to the visible range of the orientation (horizontal or vertical) it controls. Its orientation represents the orientation of the scrollbar and the scrolling effect on the viewing area controlled by the scrollbar. It is typically possible to add or subtract to the current value by using directional keys such as arrow keys.
AuthorsMUST set thearia-controls
attribute on the scrollbar element to reference the scrollable area it controls.
AuthorsMUST set thearia-valuemin
,aria-valuemax
, andaria-valuenow
attributes. If missing, their implicit values follow the same rules as theHTML range input type:
aria-valuemin
is missing or not anumber, it defaults to 0 (zero).aria-valuemax
is missing or not anumber, it defaults to 100.aria-valuenow
is missing or not anumber, it defaults to the value half way betweenaria-valuemin
andaria-valuemax
.aria-valuenow
is present but less thanaria-valuemin
, it defaults to the value ofaria-valuemin
.aria-valuenow
is present but greater thanaria-valuemax
, it defaults to the value ofaria-valuemax
.Elements with the rolescrollbar
have an implicitaria-orientation
value ofvertical
.
Assistive technologies generally will render the value ofaria-valuenow
as a percent of a range between the value ofaria-valuemin
andaria-valuemax
, unlessaria-valuetext
is specified. It is best to set the values foraria-valuemin
,aria-valuemax
, andaria-valuenow
in a manner that is appropriate for this calculation.
Characteristic | Value |
---|---|
Superclass Role: | |
Required States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | False |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-orientation isvertical .Default for aria-valuemin is0 .Default for aria-valuemax is100 .Default for aria-valuenow is half way betweenaria-valuemax andaria-valuemin . |
search
(role)§Alandmark
region that contains a collection of items and objects that, as a whole, combine to create a search facility. See relatedform
andsearchbox
.
A search region may be a mix of host language form controls, scripted controls, and hyperlinks.
User agentsSHOULD treat elements with the role ofsearch
as navigationallandmarks.
Characteristic | Value |
---|---|
Superclass Role: | landmark |
Inherited States and Properties: |
|
Name From: | author |
searchbox
(role)§Characteristic | Value |
---|---|
Superclass Role: | textbox |
Base Concept: | HTMLinput[type="search"] |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
section
(abstract role)§A renderable structural containment unit in a document or application.
section
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | structure |
Subclass Roles: | |
Related Concepts: | |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: |
|
Name From: | n/a |
sectionhead
(abstract role)§A structure that labels or summarizes the topic of its related section.
sectionhead
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | structure |
Subclass Roles: | |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: |
|
Name From: |
|
select
(abstract role)§A form widget that allows the user to make selections from a set of choices.
select
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | |
Subclass Roles: | |
Supported States and Properties: | aria-orientation |
Inherited States and Properties: |
|
Name From: | author |
separator
(role)§A divider that separates and distinguishes sections of content or groups of menuitems.
There are two types of separators: a staticstructure
that provides only a visible boundary and a focusable, interactivewidget
that is also moveable. If aseparator
is not focusable, it is revealed toassistive technologies as a static structural element. For example, a staticseparator
can be used to help visually divide two groups of menu items in a menu or to provide a horizontal rule between two sections of a page.
AuthorsMAY make aseparator
focusable to create awidget
that both provides a visible boundary between two sections of content and enables the user to change the relative size of the sections by changing the position of theseparator
. A variableseparator
widget can be moved continuously within a range, whereas a fixedseparator
widget supports only two discrete positions. Typically, a fixedseparator
widget is used to toggle one of the sections between expanded and collapsed states.
If theseparator
is focusable, authorsMUST set the value ofaria-valuenow
to anumber reflecting the current position of theseparator
and update that value when it changes. AuthorsSHOULD also provide the value ofaria-valuemin
if it is not0
and the value ofaria-valuemax
if it is not100
. If missing or not a number, the implicit values of these attributes are as follows:
aria-valuemin
is0
.aria-valuemax
is100
.aria-valuenow
is50
.In applications where there is more than one focusableseparator
, authorsSHOULD provide an accessible name for each one.
Elements with the roleseparator
have an implicitaria-orientation
value ofhorizontal
.
Characteristic | Value |
---|---|
Superclass Role: | |
Related Concepts: | HTMLhr |
Required States and Properties: |
|
Supported States and Properties: |
|
Inherited States and Properties: |
|
Name From: | author |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-orientation ishorizontal .Default for aria-valuemin is0 .Default for aria-valuemax is100 .Default for aria-valuenow is50 . |
Implicit Value for Role: | Default foraria-orientation ishorizontal . |
slider
(role)§A user input where the user selects a value from within a given range.
A slider represents the current value and range of possible values via the size of the slider and position of the thumb. It is typically possible to add or subtract to the value by using directional keys such as arrow keys.
AuthorsMUST set thearia-valuemin
,aria-valuemax
, andaria-valuenow
attributes.If missing, their implicit values follow the same rules as theHTML range input type:
aria-valuemin
is missing or not anumber, it defaults to 0 (zero).aria-valuemax
is missing or not anumber, it defaults to 100.aria-valuenow
is missing or not anumber, it defaults to the value half way betweenaria-valuemin
andaria-valuemax
.aria-valuenow
is present but less thanaria-valuemin
, it defaults to the value ofaria-valuemin
.aria-valuenow
is present but greater thanaria-valuemax
, it defaults to the value ofaria-valuemax
.Elements with the roleslider
have an implicitaria-orientation
value ofhorizontal
.
Characteristic | Value |
---|---|
Superclass Role: | |
Required States and Properties: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-orientation ishorizontal .Default for aria-valuemin is0 .Default for aria-valuemax is100 .Default for aria-valuenow is half way betweenaria-valuemax andaria-valuemin . |
spinbutton
(role)§A form ofrange
that expects the user to select from among discrete choices.
Aspinbutton
typically allows the user to select from the given range through the use of an up and down button on the keyboard. Visibly, the current value is incremented or decremented until a maximum or minimum value is reached. AuthorsSHOULD ensure this functionality is accomplished programmatically through the use ofup anddown arrows on the keyboard.
Although aspinbutton
is similar in appearance to many presentations ofselect
, it is advisable to usespinbutton
when working with known ranges (especially in the case of large ranges) as opposed to distinct options. For example, aspinbutton
representing a range from 1 to 1,000,000 would provide much better performance than aselect
widget representing the same values.
AuthorsMAY create aspinbutton
with children or owned elements, butMUST limit those elements to atextbox
and/or twobuttons
.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus. When aspinbutton
receives focus, authorsSHOULD ensure focus is placed on thetextbox
element if one is present, and on thespinbutton
itself otherwise. AuthorsSHOULD NOT include containedbutton
elements in the primary navigation ring, e.g., the Tab ring inHTML, because they are superfluous for people using keyboard devices.
AuthorsMUST set thearia-valuenow
attribute. AuthorsSHOULD set thearia-valuemin
attribute when there is a minimum value, and thearia-valuemax
attribute when there is a maximum value. If missing or not anumber, the implicit values of these attributes are as follows:
aria-valuemin
is that there is no minimum value.aria-valuemax
is that there is no maximum value.aria-valuenow
is0
.Characteristic | Value |
---|---|
Superclass Role: | |
Required States and Properties: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default foraria-valuemin is that there is no minimum value.Default for aria-valuemax is that there is no maximum value.Default for aria-valuenow is0 . |
status
(role)§A type oflive region whose content is advisory information for the user but is not important enough to justify analert
, often but not necessarily presented as a status bar.
AuthorsSHOULD ensure an element with rolestatus
does not receive focus as a result of change in status.
Status is a form oflive region. If another part of the page controls what appears in the status, authorsSHOULD make therelationship explicit with thearia-controls
attribute.
Assistive technologiesMAY reserve some cells of a Braille display to render the status.
Elements with the rolestatus
have an implicitaria-live
value ofpolite
and an implicitaria-atomic
value oftrue
.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Inherited States and Properties: |
|
Name From: | author |
Implicit Value for Role: | Default foraria-live ispolite .Default for aria-atomic istrue . |
structure
(abstract role)§A document structuralelement.
Roles for document structure support the accessibility of dynamic web content by helpingassistive technologies determine active content versus static document content. Structural roles by themselves do not all map toaccessibilityAPIs, but are used to createwidget roles or assist content adaptation for assistive technologies.
structure
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | roletype |
Subclass Roles: | |
Inherited States and Properties: |
|
Name From: |
switch
(role)§A type of checkbox that represents on/off values, as opposed to checked/unchecked values. See relatedcheckbox
.
Thearia-checked
attribute of aswitch
indicates whether the input is on (true
) or off (false
). Themixed
value is invalid, and user agentsMUST treat amixed
value as equivalent tofalse
for this role.
Aswitch
provides approximately the same functionality as acheckbox
and togglebutton
, but makes it possible for assistive technologies to present the widget in a fashion consistent with its on-screen appearance.
Characteristic | Value |
---|---|
Superclass Role: | checkbox |
Related Concepts: | button |
Required States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Children Presentational: | True |
Implicit Value for Role: | Default foraria-checked isfalse . |
tab
(role)§A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.
If atabpanel
or item in atabpanel
has focus, the associatedtab
is the currently active tab in thetablist
, as defined inManaging Focus.tablist
elements, which contain a set of associatedtab
elements, are typically placed near a series oftabpanel
elements, usually preceding it. See theWAI-ARIA Authoring Practices [wai-aria-practices-1.1] for details on implementing a tab set design pattern.
AuthorsMUST ensureelements withroletab
are contained in, orowned by, an element with the roletablist
.
AuthorsSHOULD ensure thetabpanel
associated with the currently active tab isperceivable to the user.
For a single-selectabletablist
, authorsSHOULD hide othertabpanel
elements from the user until the user selects the tab associated with that tabpanel. For a multi-selectabletablist
, authorsSHOULD ensure each visibletabpanel
has itsaria-expanded
attribute set totrue
, and that the remaining hiddentabpanel
elements have theiraria-expanded
attributes set tofalse
.
In either case, authorsSHOULD ensure that a selected tab has itsaria-selected
attribute set totrue
, that inactive tab elements have theiraria-selected
attribute set tofalse
, and that the currently selected tab provides a visual indication that it is selected. In the absence of anaria-selected
attribute on the current tab,user agentsSHOULD indicate toassistive technologies through the platformaccessibilityAPI that the currently focused tab is selected.
Characteristic | Value |
---|---|
Superclass Role: | |
Required Context Role: | tablist |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Children Presentational: | True |
Implicit Value for Role: | Default foraria-selected isfalse . |
table
(role)§Asection
containing data arranged in rows and columns. See relatedgrid
.
Thetable
role is intended for tabular containers which are not interactive. If the tabular container maintains a selection state, provides its own two-dimensional navigation, or allows the user to rearrange or otherwise manipulate its contents or the display thereof, authorsSHOULD usegrid
ortreegrid
instead.
AuthorsSHOULD prefer the use of the host language's semantics for table whenever possible, such as theHTMLtable
element.
Characteristic | Value |
---|---|
Superclass Role: | section |
Subclass Roles: | |
Base Concept: | HTMLtable |
Required Owned Elements: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
tablist
(role)§A list oftab
elements, which are references totabpanel
elements.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus.
For a single-selectabletablist
, authorsSHOULD hide othertabpanel
elements from the user until the user selects the tab associated with that tabpanel. For a multi-selectabletablist
, authorsSHOULD ensure each visibletabpanel
has itsaria-expanded
attribute set totrue
, and that the remaining hiddentabpanel
elements have theiraria-expanded
attributes set tofalse
.
tablist
elements are typically placed near usually preceding, a series oftabpanel
elements. See theWAI-ARIA Authoring Practices [wai-aria-practices-1.1] for details on implementing a tab set design pattern.
Elements with the roletablist
have an implicitaria-orientation
value ofhorizontal
.
Characteristic | Value |
---|---|
Superclass Role: | |
Related Concepts: | DAISY Guide |
Required Owned Elements: | tab |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Implicit Value for Role: | Default foraria-orientation ishorizontal . |
tabpanel
(role)§A container for the resources associated with atab
, where eachtab
is contained in atablist
.
AuthorsSHOULD associate atabpanel
element with itstab
, either by using thearia-controls
attribute on the tab to reference the tab panel, or by using thearia-labelledby
attribute on the tab panel to reference the tab.
tablist
elements are typically placed near, usually preceding, a series oftabpanel
elements. See theWAI-ARIA Authoring Practices [wai-aria-practices-1.1] for details on implementing a tab set design pattern.
Characteristic | Value |
---|---|
Superclass Role: | section |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
term
(role)§A word or phrase with a corresponding definition. See relateddefinition
.
Theterm
role is used to explicitly identify a word or phrase for which adefinition
has been provided by the author or is expected to be provided by the user.
AuthorsSHOULD NOT use theterm
role on interactive elements such as links because doing so could prevent users ofassistive technologies from interacting with those elements.
Characteristic | Value |
---|---|
Superclass Role: | section |
Related Concepts: | HTMLdt |
Inherited States and Properties: |
|
Name From: | author |
textbox
(role)§A type of input that allows free-form text as its value.
If thearia-multiline
attribute istrue
, thewidget accepts line breaks within the input, as in anHTMLtextarea
. Otherwise, this is a simple text box. The intended use is for languages that do not have a text inputelement, or cases in which an element with differentsemantics is repurposed as a text field.
In most user agent implementations, the default behavior of theENTER orRETURN key is different between the single-line and multi-line text fields inHTML. When user has focus in a single-line<input type="text">
element, the keystroke usually submits the form. When user has focus in a multi-line<textarea>
element, the keystroke inserts a line break. TheWAI-ARIAtextbox
role differentiates these types of boxes with thearia-multiline
attribute, so authors are advised to be aware of this distinction when designing the field.
Characteristic | Value |
---|---|
Superclass Role: | input |
Subclass Roles: | |
Related Concepts: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
timer
(role)§A type oflive region containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.
The text contents of the timerobject indicate the current time measurement, and are updated as that amount changes. The timer value is not necessarily machine parsable, but authorsSHOULD update the text contents at fixed intervals, except when the timer is paused or reaches an end-point.
Elements with the roletimer
have an implicitaria-live
value ofoff
.
Characteristic | Value |
---|---|
Superclass Role: | status |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
toolbar
(role)§A collection of commonly used function buttons or controls represented in compact visual form.
The toolbar is often a subset of functions found in amenubar
, designed to reduce user effort in using these functions. AuthorsMUST supply a label on each toolbar when the application contains more than one toolbar.
AuthorsMAY manage focus of descendants for all instances of thisrole, as described inManaging Focus.
Elements with the roletoolbar
have an implicitaria-orientation
value ofhorizontal
.
Characteristic | Value |
---|---|
Superclass Role: | group |
Related Concepts: | menubar |
Supported States and Properties: | aria-orientation |
Inherited States and Properties: |
|
Name From: | author |
Implicit Value for Role: | Default foraria-orientation ishorizontal . |
tooltip
(role)§A contextual popup that displays a description for an element.
Thetooltip
typically becomes visible in response to a mouse hover, or after the owning element receives keyboard focus. In each of these cases, authorsSHOULD display the tooltip after a short delay. The use of aWAI-ARIA tooltip is a supplement to the normal tooltip behavior of the user agent.
Typical tooltip delays last from one to five seconds.
AuthorsSHOULD ensure that elements with theroletooltip
are referenced through the use ofaria-describedby
before or at the time the tooltip is displayed.
Characteristic | Value |
---|---|
Superclass Role: | section |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
tree
(role)§A type oflist
that may contain sub-level nested groups that can be collapsed and expanded.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus.
Elements with the roletree
have an implicitaria-orientation
value ofvertical
.
Characteristic | Value |
---|---|
Superclass Role: | select |
Subclass Roles: | |
Required Owned Elements: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
Implicit Value for Role: | Default foraria-orientation isvertical . |
treegrid
(role)§Agrid
whose rows can be expanded and collapsed in the same manner as for atree
.
Ifaria-readonly
is set on anelement withroletreegrid
,user agentsMUST propagate the value to allgridcell
elements owned by thetreegrid
and expose the value in the accessibilityAPI. An authorMAY override the propagated value ofaria-readonly
for an individualgridcell
element.
When thearia-readonly
attribute is applied to a focusablegridcell
, it indicates whether the content contained in thegridcell
is editable. Thearia-readonly
attribute does not represent availability of functions for navigating or manipulating thetreegrid
itself.
In atreegrid
that provides content editing functions, if the content of a focusablegridcell
element is not editable, authorsMAY setaria-readonly
totrue
on thegridcell
element. However, if atreegrid
presents a collection of elements that do not supportaria-readonly
, such as a collection oflink
elements, it is not necessary for the author to specify a value foraria-readonly
.
To bekeyboard accessible, authorsSHOULD manage focus of descendants for all instances of thisrole, as described inManaging Focus.
Characteristic | Value |
---|---|
Superclass Role: | |
Required Owned Elements: | |
Inherited States and Properties: |
|
Name From: | author |
Accessible Name Required: | True |
treeitem
(role)§An option item of atree
. This is anelement within a tree that may be expanded or collapsed if it contains a sub-level group of tree item elements.
A collection oftreeitem
elements to be expanded and collapsed are enclosed in an element with thegroup
role.
AuthorsMUST ensureelements withroletreeitem
are contained in, orowned by, an element with the rolegroup
ortree
.
Characteristic | Value |
---|---|
Superclass Role: | |
Required Context Role: | |
Inherited States and Properties: |
|
Name From: |
|
Accessible Name Required: | True |
widget
(abstract role)§An interactive component of a graphical user interface (GUI).
Widgets are discrete user interface objects with which the user can interact. Widgetroles map to standard features inaccessibilityAPIs. When the user navigates an element assigned any of the non-abstract subclass roles ofwidget
,assistive technologies that typically intercept standard keyboard eventsSHOULD switch to an application browsing mode, and pass keyboard events through to the web application. The intent is to hint to certainassistive technologies to switch from normal browsing mode into a mode more appropriate for interacting with a web application; someuser agents have a browse navigation mode where keys, such as up and down arrows, are used to browse the document, and this native behavior prevents the use of these keys by a web application.
widget
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | roletype |
Subclass Roles: | |
Inherited States and Properties: |
|
Name From: |
window
(abstract role)§A browser or application window.
Elements with thisrole have a window-like behavior in a graphical user interface (GUI) context, regardless of whether they are implemented as a native window in the operating system, or merely as a section of the document styled to look like a window.
In the description of this role, the term "application" does not refer to theapplication
role, which specifies specific assistive technology behaviors.
window
is an abstract role used for the ontology. Authors should not use this role in content.
Characteristic | Value |
---|---|
Is Abstract: | True |
Superclass Role: | roletype |
Subclass Roles: | |
Supported States and Properties: | |
Inherited States and Properties: |
|
Name From: | author |
The terms "states" and "properties" refer to similar features. Both provide specific information about anobject, and both form part of the definition of the nature ofroles. In this document, states and properties are both treated as aria-prefixed markupattributes. However, they are maintained conceptually distinct to clarify subtle differences in their meaning. One major difference is that thevalues of properties (such asaria-labelledby
) are often less likely to change throughout the application life-cycle than the values of states (such asaria-checked
) which may change frequently due to user interaction. Note that the frequency of change difference is not a rule; a few properties, such asaria-valuetext
are expected to change often. Because the distinction between states and properties is of little consequence to most web content authors, this specification refers to both "states" and "properties" simply as "attributes" whenever possible. See the definitions ofstate andproperty for more information.
States and properties have the characteristics described in the following sections.
Advisory information about features from this or other languages that correspond to thisstate orproperty. While the correspondence may not be exact, it is useful to help understand the intent of the state or property.
Advisory information aboutroles that use thisstate orproperty. This information is provided to help understand the appropriate usage of the state or property. Use of a given state or property is not defined when used on roles other than those listed.
Advisory information aboutroles that inherit thestate orproperty from an ancestor role.
Value type of thestate orproperty. The value may be one of the following types:
false
unless otherwise specified.false
unless otherwise specified.aria-expanded
set tofalse
is not currently expanded; an element witharia-expanded
set toundefined
is not expandable. The default value for this value type isundefined
unless otherwise specified.undefined
for this type is the equivalent of providing no value.These are generic types for states and properties, but do not define specific representation. SeeState and Property Attribute Processing for details on how these values are expressed and handled in host languages.
Manystates andproperties accept a specific set of tokens asvalues. The allowed values and explanation of their meaning is shown after the table of characteristics. The default value, if defined, is shown instrong type, followed by the parenthetical term 'default'. When a value is indicated as the default, the user agentMUST follow the behavior prescribed by this value when the state or property is empty or unspecified. Someroles also define what behavior to use when certain states or properties, that do not have default values, are not provided.
Somestates andproperties are applicable to all host languageelements regardless of whether arole is applied. The following global states and properties are supported by all roles and by all base markup elements.
aria-atomic
aria-busy (state)
aria-controls
aria-current (state)
aria-describedby
aria-details
aria-disabled (state)
aria-dropeffect
aria-errormessage
aria-flowto
aria-grabbed (state)
aria-haspopup
aria-hidden (state)
aria-invalid (state)
aria-keyshortcuts
aria-label
aria-labelledby
aria-live
aria-owns
aria-relevant
aria-roledescription
Global states and properties are applied to the roleroletype
, which is the base role, and therefore inherit into all roles. To facilitate reading, they are not explicitly identified as either supported or inherited states and properties in the specification. Instead, the inheritance is indicated by a link to this section.
States and properties are categorized as follows:
This section containsattributes specific to common user interfaceelements found onGUI systems or in rich internet applications which receive user input and process user actions. These attributes are used to support thewidget roles.
aria-autocomplete
aria-checked
aria-disabled
aria-errormessage
aria-expanded
aria-haspopup
aria-hidden
aria-invalid
aria-label
aria-level
aria-modal
aria-multiline
aria-multiselectable
aria-orientation
aria-placeholder
aria-pressed
aria-readonly
aria-required
aria-selected
aria-sort
aria-valuemax
aria-valuemin
aria-valuenow
aria-valuetext
Widget attributes might be mapped by auser agent to platformaccessibilityAPIstate, for access byassistive technologies, or they might be accessed directly from theDOM. User agentsMUST provide a way for assistive technologies to be notified when states change, either throughDOM attribute changeevents or platform accessibilityAPI events.
This section containsattributes specific tolive regions in rich internet applications. These attributes may be applied to anyelement. The purpose of these attributes is to indicate that content changes may occur without the element having focus, and to provideassistive technologies with information on how to process those content updates. Someroles specify a default value for thearia-live
attribute specific to that role. An example of a live region is a ticker section that lists updating stock quotes.
aria-atomic
aria-busy
aria-live
aria-relevant
This section listsattributes which indicate information about drag-and-drop interfaceelements, such as draggable elements and their drop targets. Drop target information will be rendered visually by the author and provided toassistive technologies through an alternate modality.
This section listsattributes that indicaterelationships or associations betweenelements which cannot be readily determined from the document structure.
Below is an alphabetical list ofWAI-ARIAstates andproperties to be used by rich internet application authors. A detailed definition of eachWAI-ARIA state andproperty follows this compact list.
composite
widget,textbox
,group
, orapplication
.aria-relevant
attribute.aria-pressed
andaria-selected
.table
,grid
, ortreegrid
. See relatedaria-colindex
.table
,grid
, ortreegrid
. See relatedaria-colcount
andaria-colspan
.table
,grid
, ortreegrid
. See relatedaria-colindex
andaria-rowspan
.aria-owns
.aria-labelledby
.aria-describedby
.aria-hidden
andaria-readonly
.aria-invalid
andaria-describedby
.aria-disabled
.aria-errormessage
.aria-labelledby
.aria-describedby
.aria-controls
.aria-setsize
.aria-checked
andaria-selected
.aria-disabled
.aria-atomic
.table
,grid
, ortreegrid
. See relatedaria-rowindex
.table
,grid
, ortreegrid
. See relatedaria-rowcount
andaria-rowspan
.table
,grid
, ortreegrid
. See relatedaria-rowindex
andaria-colspan
.aria-checked
andaria-pressed
.aria-posinset
.aria-valuetext
.aria-valuenow
for a rangewidget.aria-activedescendant
(property)§Identifies the currently active element whenDOM focus is on acomposite
widget,textbox
,group
, orapplication
.
Thearia-activedescendant
property provides an alternative method of managing focus for interactive elements that may contain multiple focusable descendants, such as menus, grids, and toolbars. Instead of movingDOM focus among descendant elements, authorsMAY setDOM focus on anelement that supportsaria-activedescendant
and then usearia-activedescendant
to refer to the element that is active.
AuthorsMUST ensure that one of the following two sets of conditions is met when setting the value ofaria-activedescendant
on an element withDOM focus:
aria-activedescendant
refers to an element that is either a descendant of the element withDOM focus or is a logical descendant as indicated by thearia-owns
attribute.textbox
witharia-controls
referring to an element that supportsaria-activedescendant
, and the value ofaria-activedescendant
specified for thetextbox
refers to either a descendant of the element controlled by thetextbox
or is a logical descendant of that controlled element as indicated by thearia-owns
attribute. For example, in acombobox
, focus may remain on thetextbox
while the value ofaria-activedescendant
on thetextbox
element refers to a descendant of a popuplistbox
that is controlled by thetextbox
.AuthorsSHOULD also ensure that the currently active descendant is visible and in view (or scrolls into view) when focused.
Characteristic | Value |
---|---|
Related Concepts: | SVG [SVG2] andDOM [dom] active |
Used in Roles: | |
Inherits into Roles: | |
Value: | ID reference |
aria-atomic
(property)§Indicates whetherassistive technologies will present all, or only parts of, the changed region based on the change notifications defined by thearia-relevant
attribute.
BothaccessibilityAPIs and theDocument Object Model [dom] provide events to allow the assistive technologies to determine changed areas of the document.
When the content of alive region changes, user agentsSHOULD examine the changedelement and traverse the ancestors to find the first element witharia-atomic
set, and apply the appropriate behavior for the cases below.
aria-atomic
, the default is thataria-atomic
isfalse
, and assistive technologies will only present the changed node to the user.aria-atomic
is explicitly set tofalse
, assistive technologies will stop searching up the ancestor chain and present only the changed node to the user.aria-atomic
is explicitly set totrue
, assistive technologies will present the entire contents of the element, including the author-defined live region label if one exists.Whenaria-atomic
istrue
, assistive technologiesMAY choose to combine several changes and present the entire changed region at once.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | true/false |
Value | Description |
---|---|
false (default) | Assistive technologies will present only the changed node or nodes. |
true | Assistive technologies will present the entire changed region as a whole, including the author-defined label if one exists. |
aria-autocomplete
(property)§Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
Thearia-autocomplete
property describes the type of interaction model atextbox
,searchbox
, orcombobox
employs when dynamically helping users complete text input. It distinguishes between two models: the inline model (aria-autocomplete="inline"
) that presents a value completion prediction inside the text input and the list model (aria-autocomplete="list"
) that presents a collection of possible values in a separate element that pops up adjacent to the text input. It is possible for an input to offer both models at the same time (aria-autocomplete="both"
).
Thearia-autocomplete
property is limited to describing predictive behaviors of an input element. AuthorsSHOULD either omit specifying a value foraria-autocomplete
or setaria-autocomplete
tonone
if an input element provides one or more input proposals where none of the proposals are dependent on the specific input provided by the user. For instance, a combobox where the value ofaria-autocomplete
would benone
is a search field that displays suggested values by listing the 5 most recently used search terms without any filtering of the list based on the user's input. Elements with a role that supportsaria-autocomplete
have a default value foraria-autocomplete
ofnone
.
When an inline suggestion is made as a user types in an input, suggested text for completing the value of the field dynamically appears in the field after the input cursor, and the suggested value is accepted as the value of the input if the user performs an action that causes focus to leave the field. When an element hasaria-autocomplete
set toinline
orboth
, authorsSHOULD ensure that the automatically suggested portion of the text is presented as selected text. This enables assistive technologies to distinguish between a user's input and the automatic suggestion and, in the event that the suggestion is not the desired value, enables the user to easily delete the suggestion or replace it by continuing to type.
If an element hasaria-autocomplete
set tolist
orboth
, authorsMUST ensure both of the following conditions are met:
aria-controls
that refers to the element that contains the collection of suggested values.combobox
has a value foraria-haspopup
that matches the role of the element that contains the collection of suggested values.Some implementations of the list model require the user to perform an action, such as moving focus to the suggestion with theDown Arrow or clicking on the suggestion, in order to choose the suggestion. In such implementations, authorsMAY manage focus by either usingaria-activedescendant
if the collection container supports it or by movingDOM focus to the suggestion. However, other implementations of the list model automatically highlight one suggestion as the selected value that will be accepted when the field loses focus, e.g., when the user presses theTab key or clicks on a different field. If an element hasaria-autocomplete
set tolist
orboth
, and if a suggestion is automatically selected as the user provides input, authorsMUST ensure all the following conditions are met:
aria-activedescendant
.aria-activedescendant
set on the input field is dynamically adjusted to refer to the element containing the selected suggestion as described in the definition ofaria-activedescendant
.Thearia-autocomplete
property is not intended to indicate the presence of a completion suggestion, and authorsSHOULD NOT dynamically change its value in order to communicate the presence of a suggestion. When an element hasaria-autocomplete
set tolist
orboth
, authorsSHOULD use thearia-expanded
state to communicate whether the element that presents the suggestion collection is displayed.
Characteristic | Value |
---|---|
Related Concepts: | XForms selection attribute inselect |
Used in Roles: | |
Inherits into Roles: | |
Value: | token |
Value | Description |
---|---|
inline | When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret. |
list | When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. |
both | When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input. |
none (default) | When a user is providing input, an automatic suggestion that attempts to predict how the user intends to complete the input is not displayed. |
aria-busy
(state)§Indicates an element is being modified and that assistive technologiesMAY want to wait until the modifications are complete before exposing them to the user.
The default value ofaria-busy
isfalse
for all elements. Whenaria-busy
istrue
for an element, assistive technologiesMAY ignore changes to content owned by that element and then process all changes made during the busy period as a single, atomic update whenaria-busy
becomesfalse
.
If it is necessary to make multiple additions, modifications, or removals within a container element that is already either partially or fully rendered, authorsMAY setaria-busy
totrue
on the container element before the first change, and then set it tofalse
when the last change is complete. For example, if multiple changes to alive region should be spoken as a single unit of speech, authorsMAY setaria-busy
totrue
while the changes are being made and then set it tofalse
when the changes are complete and ready to be spoken.
If an element with rolefeed
is marked busy, assistive technologiesMAY defer rendering changes that occur inside thefeed
with the exception of user-initiated changes that occur inside thearticle
that the user is reading during the busy period.
If changes to a renderedwidget
would create a state where thewidget
is missingrequired owned elements during script execution, authorsMUST setaria-busy
totrue
on thewidget
during the update process. For example, if a rendered tree grid required a set of simultaneous updates to multiple discontiguous branches, an alternative to replacing the complete tree element with a single update would be to mark the tree busy while each of the branches are modified.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | true/false |
Value | Description |
---|---|
false (default): | There are no expected updates for the element. |
true | The element is being updated. |
aria-checked
(state)§Indicates the current "checked"state of checkboxes, radio buttons, and otherwidgets. See relatedaria-pressed
andaria-selected
.
Thearia-checked
attribute indicates whether theelement is checked (true
), unchecked (false
), or represents a group of other elements that have a mixture of checked and uncheckedvalues (mixed
). Most inputs only support values oftrue
andfalse
, but themixed
value is supported by certain tri-state inputs such as acheckbox
ormenuitemcheckbox
.
Themixed
value isnot supported onradio
,menuitemradio
,switch
or any element that inherits from these in thetaxonomy, anduser agentsMUST treat amixed
value as equivalent tofalse
for thoseroles.
Examples using themixed
value of tri-state inputs are covered inWAI-ARIA Authoring Practices [wai-aria-practices-1.1]
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | tristate |
Value | Description |
---|---|
false | The element supports being checked but is not currently checked. |
mixed | Indicates a mixed mode value for a tri-state checkbox or menuitemcheckbox. |
true | The element is checked. |
undefined (default) | The element does not support being checked. |
aria-colcount
(property)§Defines the total number of columns in atable
,grid
, ortreegrid
. See relatedaria-colindex
.
If all of the columns are present in theDOM, it is not necessary to set thisattribute as theuser agent can automatically calculate the total number of columns. However, if only a portion of the columns is present in theDOM at a given moment, this attribute is needed to provide an explicit indication of the number of columns in the full table.
AuthorsMUST set the value ofaria-colcount
to an integer equal to the number of columns in the full table. If the total number of columns is unknown, authorsMUST set the value ofaria-colcount
to-1
to indicate that the value should not be calculated by the user agent.
The following example shows a grid with 16 columns, of which columns 2, 3, 4, and 9 are displayed to the user.
<divrole="grid"aria-colcount="16"><divrole="rowgroup"><divrole="row"><spanrole="columnheader"aria-colindex="2">First Name</span><spanrole="columnheader"aria-colindex="3">Last Name</span><spanrole="columnheader"aria-colindex="4">Company</span><spanrole="columnheader"aria-colindex="9">Phone</span></div></div><divrole="rowgroup"><divrole="row"><spanrole="gridcell"aria-colindex="2">Fred</span><spanrole="gridcell"aria-colindex="3">Jackson</span><spanrole="gridcell"aria-colindex="4">Acme, Inc.</span><spanrole="gridcell"aria-colindex="9">555-1234</span></div><divrole="row"><spanrole="gridcell"aria-colindex="2">Sara</span><spanrole="gridcell"aria-colindex="3">James</span><spanrole="gridcell"aria-colindex="4">Acme, Inc.</span><spanrole="gridcell"aria-colindex="9">555-1235</span></div> …</div></div>
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-colindex
(property)§Defines anelement's column index or position with respect to the total number of columns within atable
,grid
, ortreegrid
. See relatedaria-colcount
andaria-colspan
.
If all of the columns are present in theDOM, it is not necessary to set thisattribute as theuser agent can automatically calculate the column index of each cell orgridcell
. However, if only a portion of the columns is present in theDOM at a given moment, this attribute is needed to provide an explicit indication of the column of each cell or gridcell with respect to the full table.
AuthorsMUST set thevalue foraria-colindex
to an integer greater than or equal to 1, greater than thearia-colindex
value of any previous elements within the same row, and less than or equal to the number of columns in the full table. For a cell or gridcell which spans multiple columns, authorsMUST set the value ofaria-colindex
to the start of the span.
If the set of columns which is present in theDOM is contiguous, and if there are no cells which span more than one row or column in that set, then authorsMAY placearia-colindex
on each row, setting the value to the index of the first column of the set. Otherwise, authorsSHOULD placearia-colindex
on all of the children orowned elements of each row.
The following example shows a grid with 16 columns, of which columns 2 through 5 are displayed to the user. Because the set of columns is contiguous,aria-colindex
can be placed on each row.
<divrole="grid"aria-colcount="16"><divrole="rowgroup"><divrole="row"aria-colindex="2"><spanrole="columnheader">First Name</span><spanrole="columnheader">Last Name</span><spanrole="columnheader">Company</span><spanrole="columnheader">Address</span></div></div><divrole="rowgroup"><divrole="row"aria-colindex="2"><spanrole="gridcell">Fred</span><spanrole="gridcell">Jackson</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">123 Broad St.</span></div><divrole="row"aria-colindex="2"><spanrole="gridcell">Sara</span><spanrole="gridcell">James</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">123 Broad St.</span></div> …</div></div>
The following example shows a grid with 16 columns, of which columns 2 through 5 are displayed to the user. While the set of columns is contiguous, some of the cells span multiple rows. As a result,aria-colindex
needs to be placed on all of the owned elements of each row.
<divrole="grid"aria-colcount="16"><divrole="rowgroup"><divrole="row"><spanrole="columnheader"aria-colindex="2">First Name</span><spanrole="columnheader"aria-colindex="3">Last Name</span><spanrole="columnheader"aria-colindex="4">Company</span><spanrole="columnheader"aria-colindex="5">Address</span></div></div><divrole="rowgroup"><divrole="row"><spanrole="gridcell"aria-colindex="2">Fred</span><spanrole="gridcell"aria-colindex="3">Jackson</span><spanrole="gridcell"aria-colindex="4"aria-rowspan="2">Acme, Inc.</span><spanrole="gridcell"aria-colindex="5"aria-rowspan="2">123 Broad St.</span></div><divrole="row"><spanrole="gridcell"aria-colindex="2">Sara</span><spanrole="gridcell"aria-colindex="3">James</span></div> …</div></div>
The following example shows a grid with 16 columns, of which columns 2, 3, 4, and 9 are displayed to the user. Because the set of columns is non-contiguous,aria-colindex
needs to be placed on all of the owned elements of each row.
<divrole="grid"aria-colcount="16"><divrole="rowgroup"><divrole="row"><spanrole="columnheader"aria-colindex="2">First Name</span><spanrole="columnheader"aria-colindex="3">Last Name</span><spanrole="columnheader"aria-colindex="4">Company</span><spanrole="columnheader"aria-colindex="9">Phone</span></div></div><divrole="rowgroup"><divrole="row"><spanrole="gridcell"aria-colindex="2">Fred</span><spanrole="gridcell"aria-colindex="3">Jackson</span><spanrole="gridcell"aria-colindex="4">Acme, Inc.</span><spanrole="gridcell"aria-colindex="9">555-1234</span></div><divrole="row"><spanrole="gridcell"aria-colindex="2">Sara</span><spanrole="gridcell"aria-colindex="3">James</span><spanrole="gridcell"aria-colindex="4">Acme, Inc.</span><spanrole="gridcell"aria-colindex="9">555-1235</span></div> …</div></div>
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-colspan
(property)§Defines the number of columns spanned by a cell or gridcell within atable
,grid
, ortreegrid
. See relatedaria-colindex
andaria-rowspan
.
Thisattribute is intended for cells and gridcells which are not contained in a native table. When defining the column span of cells or gridcells in a native table, authorsSHOULD use the host language's attribute instead ofaria-colspan
. Ifaria-colspan
is used on an element for which the host language provides an equivalent attribute,user agentsMUST ignore the value ofaria-colspan
and instead expose the value of the host language's attribute toassistive technologies.
AuthorsMUST set thevalue ofaria-colspan
to an integer greater than or equal to 1 and less than the value which would cause the cell or gridcell to overlap the next cell or gridcell in the same row.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-controls
(property)§Identifies theelement (or elements) whose contents or presence are controlled by the current element. See relatedaria-owns
.
For example:
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | ID reference list |
aria-current
(state)§Indicates theelement that represents the current item within a container or set of related elements.
Thearia-current
attribute is an enumerated type. Any value not included in the list of allowed valuesSHOULD be treated byassistive technologies as if the valuetrue
had been provided. If the attribute is not present or its value is an empty string orundefined
, the default value offalse
applies and thearia-current
stateMUST NOT be exposed by user agents or assistive technologies.
Thearia-current
attribute is used when an element within a set of related elements is visually styled to indicate it is the current item in the set. For example:
page
token used to indicate a link within a set of pagination links, where the link is visually styled to represent the currently-displayed page.step
token used to indicate a link within a step indicator for a step-based process, where the link is visually styled to represent the current step.location
token used to indicate the image that is visually highlighted as the current component of a flow chart.date
token used to indicate the current date within a calendar.time
token used to indicate the current time within a timetable.AuthorsSHOULD only mark one element in a set of elements as current witharia-current
.
AuthorsSHOULD NOT use thearia-current
attribute as a substitute foraria-selected
in widgets wherearia-selected
has the same meaning. For example, in atablist
,aria-selected
is used on atab
to indicate the currently-displayedtabpanel
.
In some use cases for widgets that supportaria-selected
, current and selected can have different meanings and can both be used within the same set of elements. For example,aria-current="page"
can be used in a navigationtree
to indicate which page is currently displayed, whilearia-selected="true"
indicates which page will be displayed if the user activates thetreeitem
. Furthermore, the same tree may support operating on one or more selected pages (treeitems) by way of a context menu containing options such as "delete" and "move."
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | token |
Value | Description |
---|---|
page | Represents the current page within a set of pages. |
step | Represents the current step within a process. |
location | Represents the current location within an environment or context. |
date | Represents the current date within a collection of dates. |
time | Represents the current time within a set of times. |
true | Represents the current item within a set. |
false (default) | Does not represent the current item within a set. |
aria-describedby
(property)§Identifies theelement (or elements) that describes theobject. See relatedaria-labelledby
.
Thearia-labelledby
attribute is similar to thearia-describedby
in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.
The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID.
Characteristic | Value |
---|---|
Related Concepts: |
|
Used in Roles: | All elements of the base markup |
Value: | ID reference list |
aria-details
(property)§Identifies theelement that provides a detailed, extended description for theobject. See relatedaria-describedby
.
Thearia-details
attribute references a single element that provides more detailed information than would normally be provided byaria-describedby
. It enablesassistive technologies to make users aware of the availability of an extended description as well as navigate to it. AuthorsSHOULD ensure the element referenced byaria-details
is visible to all users.
Unlike elements referenced byaria-describedby
, the element referenced byaria-details
is not used in either the AccessibleName Computation or the AccessibleDescription Computation as defined in the Accessible Name and Description specification [accname-aam-1.1]. Thus, the content of an element referenced byaria-details
is not flattened to a string when presented to assistive technology users. This makesaria-details
particularly useful when converting the information to a string would cause a loss of information or make the extended description more difficult to understand.
In some user agents, multiple reference relationships for descriptive information are not supported by the accessibilityAPI. In such cases, if botharia-describedby
andaria-details
are provided on an element,aria-details
takes precedence.
A common use foraria-details
is in digital publishing where an extended description needs to be conveyed in a book that requires structural markup or the embedding of other technology to provide illustrative content. The following example demonstrates this scenario.
<!-- Provision of an extended description --><imgsrc="pythagorean.jpg"alt="Pythagorean Theorem"aria-details="det"><detailsid="det"><summary>Example</summary><p> The Pythagorean Theorem is a relationship in Euclidean Geometry between the three sides of a right triangle, where the square of the hypotenuse is the sum of the squares of the two opposing sides.</p><p> The following drawing illustrates an application of the Pythagorean Theorem when used to construct a skateboard ramp.</p><objectdata="skatebd-ramp.svg"type="image/svg+xml"/><p> In this example you will notice a skateboard with a base and vertical board whose width is the width of the ramp. To compute how long the ramp must be, simply calculate the base length, square it, sum it with the square of the height of the ramp, and take the square root of the sum.</p></details>
Alternatively,aria-details
may refer to a link to a web page having the extended description, as shown in the following example.
<!-- Provision of an extended description --><imgsrc="pythagorean.jpg"alt="Pythagorean Theorem"aria-details="det"><p> See an<ahref="http://foo.com/pt.html"id="det">Application of the Pythagorean Theorem</a>.</p>
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | ID reference |
aria-disabled
(state)§Indicates that theelement isperceivable but disabled, so it is not editable or otherwiseoperable. See relatedaria-hidden
andaria-readonly
.
For example, irrelevant options in a radio group may be disabled. Disabled elements might not receive focus from the tab order. For some disabled elements, applications might choose not to support navigation to descendants. In addition to setting thearia-disabled
attribute, authorsSHOULD change the appearance (grayed out, etc.) to indicate that the item has been disabled.
Thestate of being disabled applies to the current element and all focusable descendant elements of the element on which thearia-disabled
attribute is applied.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | true/false |
Value | Description |
---|---|
false (default) | The element is enabled. |
true | The element and all focusable descendants are disabled and its value cannot be changed by the user. |
aria-dropeffect
(property)§[Deprecated in ARIA 1.1] Indicates what functions can be performed when a dragged object is released on the drop target.
Thearia-dropeffect
property is expected to be replaced by a new feature in a future version ofWAI-ARIA. Authors are therefore advised to treataria-dropeffect
asdeprecated.
Thisproperty allows assistive technologies to convey the possible drag options available to users, including whether a pop-up menu of choices is provided by the application. Typically, drop effect functions can only be provided once an object has been grabbed for a drag operation as the drop effect functions available are dependent on the object being dragged.
More than one drop effect may be supported for a givenelement. Therefore, the value of thisattribute is a space-delimited set of tokens indicating the possible effects, ornone
if there is no supported operation. In addition to setting thearia-dropeffect
attribute, authorsSHOULD show a visual indication of potential drop targets.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | token list |
Value | Description |
---|---|
copy | A duplicate of the source object will be dropped into the target. |
execute | A function supported by the drop target is executed, using the drag source as an input. |
link | A reference or shortcut to the dragged object will be created in the target object. |
move | The source object will be removed from its current location and dropped into the target. |
none (default) | No operation can be performed; effectively cancels the drag operation if an attempt is made to drop on this object. Ignored if combined with any other token value. e.g., 'none copy' is equivalent to a 'copy' value. |
popup | There is a popup menu or dialog that allows the user to choose one of the drag operations (copy, move, link, execute) and any other drag functionality, such as cancel. |
aria-errormessage
(property)§Identifies theelement that provides an error message for theobject. See relatedaria-invalid
andaria-describedby
.
Thearia-errormessage
attribute references another element that contains custom error message text. AuthorsMUST usearia-invalid
in conjunction witharia-errormessage
. Initially, the object is in a valid state and either hasaria-invalid
set tofalse
or noaria-invalid
attribute, and the element referenced byaria-errormessage
is not applicable. If the user enters an invalid value for the object,aria-invalid
is set totrue
to indicate thataria-errormessage
is now pertinent. Whenaria-errormessage
is pertinent, authorsMUST ensure the content is not hidden and is included in a container that exposes the content to the user as it is expected that the assistive technology user will navigate to the content in order to access it.
AuthorsMAY use live regions for the error messageelement applying either anaria-live
property or using one of thelive region roles, for example,alert
. A live region scenario is when an error message is displayed to users only after they have provided invalid information. The message describes what is wrong and advises users as to what is required. For example, an error message might be, "Invalid time: the time must be between 9:00 AM and 5:00 PM". The following example shows the markup for the initial valid state and for the subsequent invalid state. Note the changes toaria-invalid
on the text inputobject, and toaria-live
on theelement containing the text of the error message:
<!-- Initial valid state --><labelfor="startTime"> Please enter a start time for the meeting:</label><inputid="startTime"type="text"aria-errormessage="msgID"value=""aria-invalid="false"><spanid="msgID"aria-live="off"style="visibility:hidden"> Invalid time: the time must be between 9:00 AM and 5:00 PM"</span><!-- User has input an invalid value --><labelfor="startTime"> Please enter a start time for the meeting:</label><inputid="startTime"type="text"aria-errormessage="msgID"aria-invalid="true"value="11:30 PM" ><spanid="msgID"aria-live="assertive"style="visibility:visible"> Invalid time: the time must be between 9:00 AM and 5:00 PM"</span>
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | ID reference |
aria-expanded
(state)§Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
For example, this indicates whether a portion of a tree is expanded or collapsed. In other instances, this may be applied to page sections to mark expandable and collapsible regions that are flexible for managing content density. Simplifying the user interface by collapsing sections may improve usability for all, including those with cognitive or developmental disabilities.
If the element with thearia-expanded
attribute controls the expansion of another grouping container that is not 'owned by' the element, the authorSHOULD reference the container by using thearia-controls
attribute.
Characteristic | Value |
---|---|
Related Concepts: | Tapered prompts in voice browsing. Switch inSMIL [SMIL3]. |
Used in Roles: | |
Inherits into Roles: |
|
Value: | true/false/undefined |
Value | Description |
---|---|
false | The element, or another grouping element it controls, is collapsed. |
true | The element, or another grouping element it controls, is expanded. |
undefined (default) | The element, or another grouping element it controls, is neither expandable nor collapsible; all its child elements are shown or there are no child elements. |
aria-flowto
(property)§Identifies the nextelement (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order.
Whenaria-flowto
has a single IDREF, it allowsassistive technologies to, at the user's request, forego normal document reading order and go to the targetedobject. However, whenaria-flowto
is provided with multiple IDREFS, assistive technologiesSHOULD present the referenced elements as path choices.
In the case of one or more IDREFS,user agents or assistive technologiesSHOULD give the user the option of navigating to any of the targeted elements. The name of the path can be determined by the name of the target element of thearia-flowto
attribute.AccessibilityAPIs can provide named pathrelationships.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | ID reference list |
aria-grabbed
(state)§[Deprecated in ARIA 1.1] Indicates an element's "grabbed"state in a drag-and-drop operation.
Thearia-grabbed
state is expected to be replaced by a new feature in a future version ofWAI-ARIA. Authors are therefore advised to treataria-grabbed
asdeprecated.
Settingaria-grabbed
totrue
indicates that theelement has been selected for dragging. Settingaria-grabbed
tofalse
indicates that the element can be grabbed for a drag-and-drop operation, but is not currently grabbed. Ifaria-grabbed
is unspecified or set toundefined
(default), the element cannot be grabbed.
Whenaria-grabbed
is set totrue
, authorsSHOULD update thearia-dropeffect
attribute of all potential drop targets. When an element is not grabbed (the value is set tofalse
orundefined
, or the attribute is removed), authorsSHOULD revert thearia-dropeffect
attributes of the associated drop targets tonone
.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | true/false/undefined |
Value | Description |
---|---|
false | Indicates that the element supports being dragged. |
true | Indicates that the element has been "grabbed" for dragging. |
undefined (default) | Indicates that the element does not support being dragged. |
aria-haspopup
(property)§Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by anelement.
A popup element usually appears as a block of content that is on top of other content. AuthorsMUST ensure that the role of the element that serves as the container for the popup content ismenu
,listbox
,tree
,grid
, ordialog
, and that the value ofaria-haspopup
matches the role of the popup container.
For the popup element to be keyboard accessible, authorsSHOULD ensure that the element that can trigger the popup is focusable, that there is a keyboard mechanism for opening the popup, and that the popup element manages focus of all its descendants as described inManaging Focus.
Thearia-haspopup
property is an enumerated type.User agentsMUST treat any value ofaria-haspopup
that is not included in the list of allowed values, including an empty string, as if the valuefalse
had been provided. To provide backward compatibility with ARIA 1.0 content, user agentsMUST treat anaria-haspopup
value oftrue
as equivalent to a value ofmenu
.
Assistive technologiesSHOULD NOT expose thearia-haspopup
property if it has a value offalse
.
Atooltip
is not considered to be a popup in this context.
Characteristic | Value |
---|---|
Related Concepts: |
|
Used in Roles: | All elements of the base markup |
Value: | token |
Value | Description |
---|---|
false (default) | Indicates the element does not have a popup. |
true | Indicates the popup is amenu . |
menu | Indicates the popup is amenu . |
listbox | Indicates the popup is alistbox . |
tree | Indicates the popup is atree . |
grid | Indicates the popup is agrid . |
dialog | Indicates the popup is adialog . |
aria-hidden
(state)§Indicates whether theelement is exposed to an accessibilityAPI. See relatedaria-disabled
.
User agents determine an element'shidden status based on whether it is rendered, and the rendering is usually controlled byCSS. For example, an element whosedisplay
property is set tonone
is not rendered. An element is consideredhidden if it, or any of its ancestors are not rendered or have theiraria-hidden
attribute value set totrue
.
[aria-hidden="true"] { visibility: hidden; }
AuthorsMAY, with caution, use aria-hidden to hide visibly rendered content from assistive technologiesonly if the act of hiding this content is intended to improve the experience for users of assistive technologies by removing redundant or extraneous content. Authors using aria-hidden to hide visible content from screen readersMUST ensure that identical or equivalent meaning and functionality is exposed to assistive technologies.
Authors are advised to use extreme caution and consider a wide range of disabilities when hiding visibly rendered content from assistive technologies. For example, a sighted, dexterity-impaired individual may use voice-controlled assistive technologies to access a visual interface. If an author hides visible link text "Go to checkout" and exposes similar, yet non-identical link text "Check out now" to the accessibilityAPI, the user may be unable to access the interface they perceive using voice control. Similar problems may also arise for screen reader users. For example, a sighted telephone support technician may attempt to have the blind screen reader user click the "Go to checkout" link, which they may be unable to find using a type-ahead item search ("Go to…").
At the time of this writing,
is known to work inconsistently in browsers. As future implementations improve, use caution and test thoroughly before relying on this approach.aria-hidden
="false"
It is recommended that authors key visibility of elements off this attribute, rather than change visibility and separately update thisproperty.CSS 2 introduced a way toselect on attribute values ([css3-selectors]). The followingCSS declaration makes content visible unless thearia-hidden
attribute istrue
; scripts need only update thevalue of this attribute to change visibility:
[aria-hidden="true"] { visibility: hidden; }
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | true/false/undefined |
Value | Description |
---|---|
false | The element is exposed to the accessibilityAPI as if it was rendered. |
true | The element is hidden from the accessibilityAPI. |
undefined (default) | The element's hidden state is determined by the user agent based on whether it is rendered. |
aria-invalid
(state)§Indicates the entered value does not conform to the format expected by the application. See relatedaria-errormessage
.
If the value is computed to be invalid or out-of-range, the application authorSHOULD set thisattribute totrue
.User agentsSHOULD inform the user of the error. Application authorsSHOULD provide suggestions for corrections if they are known.
When the user attempts to submit data involving a field for whicharia-required
istrue
, authorsMAY use thearia-invalid
attribute to signal there is an error. However, if the user has not attempted to submit the form, authorsSHOULD NOT set thearia-invalid
attribute on requiredwidgets simply because the user has not yet entered data.
For future expansion, thearia-invalid
attribute is an enumerated type. Any value not recognized in the list of allowedvaluesMUST be treated by user agents as if the valuetrue
had been provided. If the attribute is not present, or its value isfalse
, or its value is an empty string, the default value offalse
applies.
Characteristic | Value |
---|---|
Related Concepts: | XForms [XFORMS11]'invalid' event. This state istrue if a form field is required but empty. However, the XFormsvalid property would be set tofalse . |
Used in Roles: | All elements of the base markup |
Value: | token |
Value | Description |
---|---|
grammar | A grammatical error was detected. |
false (default) | There are no detected errors in the value. |
spelling | A spelling error was detected. |
true | The value entered by the user has failed validation. |
aria-keyshortcuts
(property)§Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.
The value of thearia-keyshortcuts
attribute is a space-delimited list of keyboard shortcuts that can be pressed to activate a command or textbox widget. The keys defined in the shortcuts represent the physical keys pressed and not the actual characters generated. Each keyboard shortcut consists of one or more tokens delimited by the plus sign ("+") representing zero or more modifier keys and exactly one non-modifier key that must be pressed simultaneously to activate the given shortcut.
AuthorsMUST specify modifier keys exactly according to theUI Events KeyboardEvent key Values spec [uievents-key] - for example, "Alt", "Control", "Shift", "Meta", or "AltGraph". Note that Meta corresponds to the Command key, and Alt to the Option key, on Apple computers.
The valid names for non-modifier keys are any printable character such as "A", "B", "1", "2", "$", "Plus" for a plus sign, "Space" for the spacebar, or the names of any other non-modifier key specified in theUI Events KeyboardEvent key Values spec [uievents-key] - for example, "Enter", "Tab", "ArrowRight", "PageDown", "Escape", or "F1". The use of "Space" for the spacebar is an exception to theUI Events KeyboardEvent key Values spec [uievents-key] as the space or spacebar key is encoded as' '
and would be treated as a whitespace character.
AuthorsMUST ensure modifier keys come first when they are part of a keyboard shortcut. AuthorsMUST ensure that required non-modifier keys come last when they are part of a shortcut. The order of the modifier keys is not otherwise significant, so "Alt+Shift+T" and "Shift+Alt+T" are equivalent, but "T+Shift+Alt" is not valid because all of the modifier keys don't come first, and "Alt" is not valid because it doesn't include at least one non-modifier key.
When specifying an alphabetic key, both the uppercase and lowercase variants are considered equivalent: "a" and "A" are the same.
When implementing keyboard shortcuts authors should consider the keyboards they intend to support to avoid unintended results. Keyboard designs vary significantly based on the device used and the languages supported. For example, many modifier keys are used in conjunction with other keys to create common punctuation symbols, create number characters, swap keyboard sides on bilingual keyboards to switch languages, and perform a number of other functions.
For many supported keyboards, authors can prevent conflicts by avoiding keys other than ASCII letters, as number characters and common punctuation often require modifiers. Here, the keyboard shortcut entered does not equate to the key generated. For example, in French keyboard layouts, the number characters are not available until you press the Control key, so a keyboard shortcut defined as "Control+2" would be ambiguous as this is how one would type the "2" character on a French keyboard.
If the character used is determined by a modifier key, the authorMUST specify the actual key used to generate the character, that is generated by the key, and not the resulting character. This convention enables the assistive technology to accurately convey what keys must be used to generate the shortcut. For example, on most U.S. English keyboards, the percent sign "%" can be input by pressing Shift+5. The correct way to specify this shortcut is "Shift+5". It is incorrect to specify "%" or "Shift+%". However, note that on some international keyboards the percent sign may be an unmodified key, in which case "%" and "Shift+%" could be correct on those keyboards.
If the key that needs to be specified is illegal in the host language or would cause a string to be terminated, authorsMUST use the string escaping sequence of the host language to specify it. For example, the double-quote character can be encoded as "Shift+'" inHTML.
Examples of valid keyboard shortcuts include:
User agentsMUST NOT change keyboard behavior in response to thearia-keyshortcuts
attribute. AuthorsMUST handle scripted keyboard events to processaria-keyshortcuts
. Thearia-keyshortcuts
attribute exposes the existence of these shortcuts so that assistive technologies can communicate this information to users.
AuthorsSHOULD provide a way to expose keyboard shortcuts so that all users may discover them, such as through the use of a tooltip. AuthorsMUST ensure thataria-keyshortcuts
applied to disabled elements are unavailable.
AuthorsSHOULD avoid implementing shortcut keys that inhibit operating system, user agent, or assistive technology functionality. This requires the author to carefully consider both which keys to assign and the contexts and conditions in which the keys are available to the user. For guidance, see the keyboard shortcuts section of theWAI-ARIA Authoring Practices Guide [wai-aria-practices-1.1].
Characteristic | Value |
---|---|
Related Concepts: | Keyboard shortcut |
Used in Roles: | All elements of the base markup |
Value: | string |
aria-label
(property)§Defines a string value that labels the current element. See relatedaria-labelledby
.
The purpose ofaria-label
is the same as that ofaria-labelledby
. It provides the user with a recognizable name of the object. The most commonaccessibilityAPI mapping for a label is theaccessible name property.
If the label text is visible on screen, authorsSHOULD usearia-labelledby
andSHOULD NOT usearia-label
. There may be instances where the name of an element cannot be determined programmatically from the content of the element, and there are cases where providing a visible label is not the desired user experience. Most host languages provide an attribute that could be used to name the element (e.g., thetitle
attribute inHTML), yet this could present a browser tooltip. In the cases where a visible label or visible tooltip is undesirable, authorsMAY set the accessible name of the element usingaria-label
. As required by thetext alternative computation, user agents give precedence toaria-labelledby
overaria-label
when computing the accessible name property.
Characteristic | Value |
---|---|
Related Concepts: | HTMLtitle |
Used in Roles: | All elements of the base markup |
Value: | string |
aria-labelledby
(property)§Identifies theelement (or elements) that labels the current element. See relatedaria-describedby
.
The purpose ofaria-labelledby
is the same as that ofaria-label
. It provides the user with a recognizable name of the object. The most commonaccessibilityAPI mapping for a label is theaccessible name property.
If the interface is such that it is not possible to have a visible label on the screen, authorsSHOULD usearia-label
andSHOULD NOT usearia-labelledby
. As required by thetext alternative computation, user agents give precedence toaria-labelledby
overaria-label
when computing the accessible name property.
Thearia-labelledby
attribute is similar toaria-describedby
in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.
The expected spelling of this property inU.S. English is "labeledby." However, theaccessibilityAPI features to which this property is mapped have established the "labelledby" spelling. This property is spelled that way to match the convention and minimize the difficulty for developers.
Characteristic | Value |
---|---|
Related Concepts: | HTMLlabel |
Used in Roles: | All elements of the base markup |
Value: | ID reference list |
aria-level
(property)§Defines the hierarchical level of anelement within a structure.
This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that may appear inside a container or participate in an ownership hierarchy. The value foraria-level
is an integer greater than or equal to 1.
Levels increase with depth. If theDOM ancestry does not accurately represent the level, authorsSHOULD explicitly define thearia-level
attribute.
This attribute is applied to elements that act as leaf nodes within the orientation of the set, for example, on elements with roletreeitem
rather than elements with rolegroup
. This means that multiple elements in a set may have the same value for this attribute. Although it would be less repetitive to provide a single value on the container, restricting this to leaf nodes ensures that there is a single way forassistive technologies to use the attribute.
If theDOM ancestry accurately represents the level, theuser agent can calculate the level of an item from the document structure. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or thearia-owns
attribute. User agent support for automatic calculation of level may vary; authorsSHOULD test withuser agents and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the authorSHOULD omit this attribute.
In the case of atreegrid
,aria-level
is supported on elements with the rolerow
, not elements with rolegridcell
. At first glance, this may seem inconsistent with the application ofaria-level
ontreeitem
elements, but it is consistent in that therow
acts as the leaf node within the vertical orientation of thegrid
, whereas thegridcell
is a leaf node within the horizontal orientation of eachrow
. Level is not supported on sets of cells within rows, so thearia-level
attribute is applied to the element with the rolerow
.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-live
(property)§Indicates that anelement will be updated, and describes the types of updates theuser agents,assistive technologies, and user can expect from thelive region.
Thevalues of thisattribute are expressed in degrees of importance. When regions are specified aspolite
, assistive technologies will notify users of updates but generally do not interrupt the current task, and updates take low priority. When regions are specified asassertive
, assistive technologies will immediately notify the user, and could potentially clear the speech queue of previous updates.
Politeness levels are essentially an ordering mechanism for updates and serve as a strong suggestion to user agents or assistive technologies. The value may be overridden by user agents, assistive technologies, or the user. For example, if assistive technologies can determine that a change occurred in response to a key press or a mouse click, the assistive technologies may present that change immediately even if the value of thearia-live
attribute states otherwise.
Since different users have different needs, it is up to the user to tweak his or her assistive technologies' response to a live region with a certain politeness level from the commonly defined baseline. Assistive technologies may choose to implement increasing and decreasing levels of granularity so that the user can exercise control over queues and interruptions.
When theproperty is not set on anobject that needs to send updates, the politeness level is the value of the nearest ancestor that sets thearia-live
attribute.
Thearia-live
attribute is the primary determination for the order of presentation of changes to live regions. Implementations will also consider the default level of politeness in arole when thearia-live
attribute is not set in the ancestor chain (e.g.,log
changes arepolite
by default). Items which areassertive
will be presented immediately, followed bypolite
items. User agents or assistive technologiesMAY choose to clear queued changes when an assertive change occurs. (e.g., changes in an assertive region may remove all currently queued changes)
When live regions are marked aspolite
, assistive technologiesSHOULD announce updates at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. When live regions are marked asassertive
, assistive technologiesSHOULD notify the user immediately. Because an interruption may disorient users or cause them to not complete their current task, authorsSHOULD NOT use the assertive value unless the interruption is imperative.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | token |
Value | Description |
---|---|
assertive | Indicates that updates to the region have the highest priority and should be presented the user immediately. |
off (default) | Indicates that updates to the region should not be presented to the user unless the used is currently focused on that region. |
polite | Indicates that updates to the region should be presented at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. |
aria-modal
(property)§Indicates whether anelement is modal when displayed.
Thearia-modal
attribute is used to indicate that the presence of a "modal" element precludes usage of other content on the page. For example, when a modal dialog is displayed, it is expected that the user's interaction is limited to the contents of the dialog, until the modal dialog loses focus or is no longer displayed.
When a modal element is displayed, assistive technologiesSHOULD navigate to the element unless focus has explicitly been set elsewhere. Assistive technologiesMAY limit navigation to the modal element's contents. If focus moves to an element outside the modal element, assistive technologiesSHOULD NOT limit navigation to the modal element.
When a modal element is displayed, authorsMUST ensure the interface can be controlled using only descendants of the modal element. In other words, if a modal dialog has a close button, the button should be a descendant of the dialog. When a modal element is displayed, authorsSHOULD mark all other contents as inert (such as "inert subtrees" inHTML) if the ability to do so exists in the host language.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | true/false |
Value | Description |
---|---|
false (default) | Element is not modal. |
true | Element is modal. |
aria-multiline
(property)§Indicates whether a text box accepts multiple lines of input or only a single line.
In most user agent implementations, the default behavior of theENTER orRETURN key is different between the single-line and multi-line text fields inHTML. When user has focus in a single-line<input type="text">
element, the keystroke usually submits the form. When user has focus in a multi-line<textarea>
element, the keystroke inserts a line break. TheWAI-ARIAtextbox
role differentiates these types of boxes with thearia-multiline
attribute, so authors are advised to be aware of this distinction when designing the field.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | true/false |
Value | Description |
---|---|
false (default) | This is a single-line text box. |
true | This is a multi-line text box. |
aria-multiselectable
(property)§Indicates that the user may select more than one item from the current selectable descendants.
AuthorsSHOULD ensure that selected descendants have thearia-selected
attribute set totrue
, and selectable descendant have thearia-selected
attribute set tofalse
. AuthorsSHOULD NOT use thearia-selected
attribute on descendants that are not selectable.
Lists and trees are examples of roles that might allow users to select more than one item at a time.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | true/false |
Value | Description |
---|---|
false (default) | Only one item can be selected. |
true | More than one item in the widget may be selected at a time. |
aria-orientation
(property)§Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
In ARIA 1.1, the default value foraria-orientation
changed fromhorizontal
toundefined
. Implicit defaults are defined on some roles (e.g.,slider
defaults to horizontal;scrollbar
defaults to vertical) but remain undefined on roles where an expected default orientation is ambiguous (e.g.,radiogroup
).
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | token |
Value | Description |
---|---|
horizontal | The element is oriented horizontally. |
undefined (default) | The element's orientation is unknown/ambiguous. |
vertical | The element is oriented vertically. |
aria-owns
(property)§Identifies anelement (or elements) in order to define a visual, functional, or contextual parent/childrelationship betweenDOM elements where theDOM hierarchy cannot be used to represent the relationship. See relatedaria-controls
.
The value of thearia-owns
attribute is a space-separated list of IDREFS that reference one or more elements in the document by ID. The reason for addingaria-owns
is to expose a parent/child contextual relationship toassistive technologies that is otherwise impossible to infer from theDOM.
If an element has botharia-owns
andDOM children then the order of the child elements with respect to the parent/child relationship is theDOM children first, then the elements referenced inaria-owns
. If the author intends that theDOM children are not first, then list theDOM children inaria-owns
in the desired order. AuthorsSHOULD NOT usearia-owns
as a replacement for theDOM hierarchy. If the relationship is represented in theDOM, do not usearia-owns
. AuthorsMUST ensure that an element's ID is not specified in more than one other element'saria-owns
attribute at any time. In other words, an element can have only one explicit owner.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | ID reference list |
aria-placeholder
(property)§Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format.
AuthorsSHOULD NOT usearia-placeholder
instead of a label as their purposes are different: The label indicates what kind of information is expected. The placeholder text is a hint about the expected value. See relatedaria-labelledby
andaria-label
.
AuthorsSHOULD present this hint to the user by displaying the hint text at any time the control'svalue is the empty string. This includes cases where the control first receives focus, and when users remove a previously-entered value.
As is the case with the relatedHTMLplaceholder
attribute, use of placeholder text as a replacement for a displayed label can reduce the accessibility and usability of the control for a range of users including older users and users with cognitive, mobility, fine motor skill or vision impairments. While the hint given by the control's label is shown at all times, the short hint given in the placeholder attribute is only shown before the user enters a value. Furthermore, placeholder text may be mistaken for a pre-filled value, and as commonly implemented the default color of the placeholder text provides insufficient contrast and the lack of a separate visible label reduces the size of the hit region available for setting focus on the control.
The following example shows asearchbox
in which the user has entered a value:
<spanid="label">Birthday:</span><divcontenteditablerole="searchbox"aria-labelledby="label"aria-placeholder="MM-DD-YYYY">03-14-1879</div>
The following example shows the samesearchbox
in which the user has not yet entered a value or has removed a previously-entered value:
<spanid="label">Birthday:</span><divcontenteditablerole="searchbox"aria-labelledby="label"aria-placeholder="MM-DD-YYYY">MM-DD-YYYY</div>
Characteristic | Value |
---|---|
Related Concepts: | HTMLplaceholder |
Used in Roles: | |
Inherits into Roles: | |
Value: | string |
aria-posinset
(property)§Defines anelement's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in theDOM. See relatedaria-setsize
.
If all items in a set are present in the document structure, it is not necessary to set thisattribute, as theuser agent can automatically calculate the set size and position for each item. However, if only a portion of the set is present in the document structure at a given moment, thisproperty is needed to provide an explicit indication of an element's position.
The following example shows items 5 through 8 in a set of 16.
<h2id="label_fruit"> Available Fruit</h2><ulrole="listbox"aria-labelledby="label_fruit"><lirole="option"aria-setsize="16"aria-posinset="5"> apples</li><lirole="option"aria-setsize="16"aria-posinset="6"> bananas</li><lirole="option"aria-setsize="16"aria-posinset="7"> cantaloupes</li><lirole="option"aria-setsize="16"aria-posinset="8"> dates</li></ul>
AuthorsMUST set the value foraria-posinset
to an integer greater than or equal to 1, and less than or equal to the size of the set when that size is known. AuthorsSHOULD usearia-setsize
.
When exposingaria-posinset
on amenuitem
,menuitemcheckbox
, ormenuitemradio
, authorsSHOULD set the value ofaria-posinset
with respect to the total number of items in themenu
, excluding any separators.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-pressed
(state)§Indicates the current "pressed"state of toggle buttons. See relatedaria-checked
andaria-selected
.
Toggle buttons require a full press-and-release cycle to change their value. Activating it once changes the value totrue
, and activating it another time changes the value back tofalse
. A value ofmixed
means that the values of more than one item controlled by the button do not all share the same value. Examples of mixed-state buttons are described inWAI-ARIA Authoring Practices [wai-aria-practices-1.1]. If theattribute is not present, the button is not a toggle button.
Thearia-pressed
attribute is similar but not identical to thearia-checked
attribute. Operating systems supportpressed
on buttons andchecked
on checkboxes.
Characteristic | Value |
---|---|
Used in Roles: | |
Value: | tristate |
Value | Description |
---|---|
false | The element supports being pressed but is not currently pressed. |
mixed | Indicates a mixed mode value for a tri-state toggle button. |
true | The element is pressed. |
undefined (default) | The element does not support being pressed. |
aria-readonly
(property)§ Indicates that theelement is not editable, but is otherwiseoperable. See relatedaria-disabled
.
This means the user can read but not set the value of thewidget. Readonly elements are relevant to the user, and application authorsSHOULD NOT restrict navigation to the element or its focusable descendants. Other actions such as copying the value of the element are also supported. This is in contrast to disabled elements, to which applications might not allow user navigation to descendants.
Examples include:
Characteristic | Value |
---|---|
Related Concepts: | XForms [XFORMS10] Readonly |
Used in Roles: | |
Inherits into Roles: | |
Value: | true/false |
Value | Description |
---|---|
false (default) | The user can set the value of the element. |
true | The user cannot change the value of the element. |
aria-relevant
(property)§Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. See relatedaria-atomic
.
Theattribute is represented as a space delimited list of the followingvalues:additions
,removals
,text
; or a single catch-all valueall
.
This is used to describesemantically meaningful changes, as opposed to merely presentational ones. For example, nodes that are removed from the top of a log are merely removed for purposes of creating room for other entries, and the removal of them does not have meaning. However, in the case of a buddy list, removal of a buddy name indicates that they are no longer online, and this is a meaningfulevent. In that casearia-relevant
will be set toall
. When thearia-relevant
attribute is not provided, the default value,additions text
, indicates that text modifications and node additions are relevant, but that node removals are irrelevant.
aria-relevant
values of removals or all are to be used sparingly. Assistive technologies only need to be informed of content removal when its removal represents an important change, such as a buddy leaving a chat room.
Text removals should only be considered relevant if one of the specified values is 'removals' or 'all'. For example, for a text change from 'foo' to 'bar' in a live region with a defaultaria-relevant
value, the text addition ('bar') would be spoken, but the text removal ('foo') would not.
aria-relevant
is an optional attribute of live regions. This is a suggestion toassistive technologies, but assistive technologies are not required to present changes of all the relevant types.
Whenaria-relevant
is not defined, an element's value is inherited from the nearest ancestor with a defined value. Although the value is atoken list, inherited values are not additive; the value provided on a descendant element completely overrides any inherited value from an ancestor element.
When text changes are denoted as relevant, user agentsMUST monitor any descendant node change that affects thetext alternative computation of the live region as if the accessible name were determined from contents (nameFrom: contents). For example, a text change would be triggered if theHTMLalt
attribute of a contained image changed. However, no change would be triggered if there was a text change to a node outside the live region, even if that node was referenced (viaaria-labelledby
) by an element contained in the live region.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | token list |
Value | Description |
---|---|
additions | Element nodes are added to the accessibility tree within the live region. |
additions text | Equivalent to the combination of values, "additions text". |
all | Equivalent to the combination of all values, "additions removals text". |
removals | Text content, a text alternative, or an element node within the live region is removed from the accessibility tree. |
text | Text content or a text alternative is added to any descendant in the accessibility tree of the live region. |
aria-required
(property)§Indicates that user input is required on theelement before a form may be submitted.
For example, if the user needs to fill in an address field, the author will need to set the field'saria-required
attribute totrue
.
The fact that the element is required is often presented visually (such as a sign or symbol after thewidget). Using thearia-required
attribute allows the author to explicitly convey toassistive technologies that an element is required.
Unless an exactly equivalent native attribute is available, host languagesSHOULD allow authors to use thearia-required
attribute on host language form elements that require input or selection by the user.
Characteristic | Value |
---|---|
Related Concepts: | HTMLrequired |
Used in Roles: | |
Inherits into Roles: | |
Value: | true/false |
Value | Description |
---|---|
false (default) | User input is not necessary to submit the form. |
true | Users need to provide input on an element before a form is submitted. |
aria-roledescription
(property)§Defines a human-readable, author-localized description for therole of anelement.
Someassistive technologies, such as screen readers, present the role of an element as part of the user experience. Such assistive technologies typically localize the name of the role, and they may customize it as well. Users of these assistive technologies depend on the presentation of the role name, such as "region," "button," or "slider," for an understanding of the purpose of the element and, if it is a widget, how to interact with it.
Thearia-roledescription
property gives authors the ability to override how assistive technologies localize and express the name of a role. Thus inappropriately usingaria-roledescription
may inhibit users' ability to understand or interact with an element. AuthorsSHOULD limit use ofaria-roledescription
to clarifying the purpose of non-interactive container roles likegroup
orregion
, or to providing amore specific description of awidget
.
When usingaria-roledescription
, authorsSHOULD also ensure that:
aria-roledescription
is applied has a validWAI-ARIA role or has an implicitWAI-ARIA role semantic.aria-roledescription
is not empty or does not contain only whitespace characters.User agentsMUST NOT expose thearia-roledescription
property if any of the following conditions exist:
aria-roledescription
is applied does not have a validWAI-ARIA role or does not have an implicitWAI-ARIA role semantic.Assistive technologiesSHOULD use the value ofaria-roledescription
when presenting the role of an element, butSHOULD NOT change other functionality based on the role of an element that has a value foraria-roledescription
. For example, an assistive technology that provides functions for navigating to the nextregion
orbutton
SHOULD allow those functions to navigate to regions and buttons that have anaria-roledescription
.
The following two examples show the use ofaria-roledescription
to indicate that a non-interactive container is a "slide" in a web-based presentation application.
<divrole="region"aria-roledescription="slide"id="slide42"aria-labelledby="slide42heading"><h1id="slide42heading">Quarterly Report</h1><!-- remaining slide contents --></div>
<sectionaria-roledescription="slide"id="slide42"aria-labelledby="slide42heading"><h1id="slide42heading">Quarterly Report</h1><!-- remaining slide contents --></section>
In the previous examples, a screen reader user may hear "Quarterly Report, slide" rather than the more vague "Quarterly Report, region" or "Quarterly Report, group."
The following examples show the use ofaria-roledescription
to indicate that abutton
in a web-based email client is associated with an "attachment."
<divrole="button"tabindex="0"aria-roledescription="attachment button">family_reunion.jpg</div>
<buttonaria-roledescription="attachment button">family_reunion.jpg</button>
In the previous two examples, because "button" is part of the localized description, a screen reader user should still understand how to interact with that control.
Characteristic | Value |
---|---|
Used in Roles: | All elements of the base markup |
Value: | string |
aria-rowcount
(property)§Defines the total number of rows in atable
,grid
, ortreegrid
. See relatedaria-rowindex
.
If all of the rows are present in theDOM, it is not necessary to set thisattribute as theuser agent can automatically calculate the total number of rows. However, if only a portion of the rows is present in theDOM at a given moment, this attribute is needed to provide an explicit indication of the number of rows in the full table.
AuthorsMUST set the value ofaria-rowcount
to an integer equal to the number of rows in the full table. If the total number of rows is unknown, authorsMUST set the value ofaria-rowcount
to-1
to indicate that the value should not be calculated by the user agent.
The following example shows a grid with 2000 rows, of which the first row and rows 100 through 102 are displayed to the user.
<divrole="grid"aria-rowcount="2000"><divrole="rowgroup"><divrole="row"aria-rowindex="1"><spanrole="columnheader">First Name</span><spanrole="columnheader">Last Name</span><spanrole="columnheader">Company</span><spanrole="columnheader">Phone</span></div></div><divrole="rowgroup"><divrole="row"aria-rowindex="100"><spanrole="gridcell">Fred</span><spanrole="gridcell">Jackson</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">555-1234</span></div><divrole="row"aria-rowindex="101"><spanrole="gridcell">Sara</span><spanrole="gridcell">James</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">555-1235</span></div><divrole="row"aria-rowindex="102"><spanrole="gridcell">Taylor</span><spanrole="gridcell">Johnson</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">555-1236</span></div></div></div>
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-rowindex
(property)§Defines anelement's row index or position with respect to the total number of rows within atable
,grid
, ortreegrid
. See relatedaria-rowcount
andaria-rowspan
.
If all of the rows are present in theDOM, it is not necessary to set thisattribute as theuser agent can automatically calculate the index of each row. However, if only a portion of the rows is present in theDOM at a given moment, this attribute is needed to provide an explicit indication of each row's position with respect to the full table.
AuthorsMUST set thevalue foraria-rowindex
to an integer greater than or equal to 1, greater than thearia-rowindex
value of any previous rows, and less than or equal to the number of rows in the full table. For a cell or gridcell which spans multiple rows, authorsMUST set the value ofaria-rowindex
to the start of the span.
AuthorsSHOULD placearia-rowindex
on each row. AuthorsMAY also placearia-rowindex
on all of the children orowned elements of each row.
The following example shows a grid with 2000 rows, of which the first row and rows 100 through 102 are displayed to the user.
<divrole="grid"aria-rowcount="2000"><divrole="rowgroup"><divrole="row"aria-rowindex="1"><spanrole="columnheader">First Name</span><spanrole="columnheader">Last Name</span><spanrole="columnheader">Company</span><spanrole="columnheader">Phone</span></div></div><divrole="rowgroup"><divrole="row"aria-rowindex="100"><spanrole="gridcell">Fred</span><spanrole="gridcell">Jackson</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">555-1234</span></div><divrole="row"aria-rowindex="101"><spanrole="gridcell">Sara</span><spanrole="gridcell">James</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">555-1235</span></div><divrole="row"aria-rowindex="102"><spanrole="gridcell">Taylor</span><spanrole="gridcell">Johnson</span><spanrole="gridcell">Acme, Inc.</span><spanrole="gridcell">555-1236</span></div></div></div>
The following example shows the grid from the previous example witharia-rowindex
also placed on all of the owned elements of each row.
<divrole="grid"aria-rowcount="2000"><divrole="rowgroup"><divrole="row"aria-rowindex="1"><spanrole="columnheader"aria-rowindex="1">First Name</span><spanrole="columnheader"aria-rowindex="1">Last Name</span><spanrole="columnheader"aria-rowindex="1">Company</span><spanrole="columnheader"aria-rowindex="1">Phone</span></div></div><divrole="rowgroup"><divrole="row"aria-rowindex="100"><spanrole="gridcell"aria-rowindex="100">Fred</span><spanrole="gridcell"aria-rowindex="100">Jackson</span><spanrole="gridcell"aria-rowindex="100">Acme, Inc.</span><spanrole="gridcell"aria-rowindex="100">555-1234</span></div><divrole="row"aria-rowindex="101"><spanrole="gridcell"aria-rowindex="101">Sara</span><spanrole="gridcell"aria-rowindex="101">James</span><spanrole="gridcell"aria-rowindex="101">Acme, Inc.</span><spanrole="gridcell"aria-rowindex="101">555-1235</span></div><divrole="row"aria-rowindex="102"><spanrole="gridcell"aria-rowindex="102">Taylor</span><spanrole="gridcell"aria-rowindex="102">Johnson</span><spanrole="gridcell"aria-rowindex="102">Acme, Inc.</span><spanrole="gridcell"aria-rowindex="102">555-1236</span></div></div></div>
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-rowspan
(property)§Defines the number of rows spanned by a cell or gridcell within atable
,grid
, ortreegrid
. See relatedaria-rowindex
andaria-colspan
.
Thisattribute is intended for cells and gridcells which are not contained in a native table. When defining the row span of cells or gridcells in a native table, authorsSHOULD use the host language's attribute instead ofaria-rowspan
. Ifaria-rowspan
is used on an element for which the host language provides an equivalent attribute,user agentsMUST ignore the value ofaria-rowspan
and instead expose the value of the host language's attribute toassistive technologies.
AuthorsMUST set thevalue ofaria-rowspan
to an integer greater than or equal to 0 and less than the value which would cause the cell or gridcell to overlap the next cell or gridcell in the same column. Setting the value to 0 indicates that the cell or gridcell is to span all the remaining rows in the row group.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-selected
(state)§Indicates the current "selected"state of variouswidgets. See relatedaria-checked
andaria-pressed
.
Thisattribute is used with single-selection and multiple-selection widgets:
aria-multiselectable
attribute istrue
specifies a value of eithertrue
orfalse
for thearia-selected
attribute.Any explicit assignment ofaria-selected
takes precedence over the implicit selection based on focus. If noDOM element in the widget is explicitly marked as selected, assistive technologiesMAY convey implicit selection which follows the keyboard focus of themanaged focus widget. If anyDOM element in the widget is explicitly marked as selected, the user agentMUST NOT convey implicit selection for the widget.
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | true/false/undefined |
Value | Description |
---|---|
false | The selectable element is not selected. |
true | The selectable element is selected. |
undefined (default) | The element is not selectable. |
aria-setsize
(property)§Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in theDOM. See relatedaria-posinset
.
Thisproperty is marked on the members of a set, not the container element that collects the members of the set. To orient the user by saying an element is "item X out of Y," theassistive technologies would use X equal to thearia-posinset
attribute and Y equal to thearia-setsize
attribute.
If all items in a set are present in the document structure, it is not necessary to set this property, as theuser agent can automatically calculate the set size and position for each item. However, if only a portion of the set is present in the document structure at a given moment (in order to reduce document size), this property is needed to provide an explicit indication of set size.
AuthorsMUST set the value ofaria-setsize
to an integer equal to the number of items in the set. If the total number of items is unknown, authorsSHOULD set the value ofaria-setsize
to-1
.
When exposingaria-setsize
on amenuitem
,menuitemcheckbox
, ormenuitemradio
, authorsSHOULD set the value ofaria-setsize
based on the total number of items in themenu
, excluding any separators.
The following example shows items 5 through 8 in a set of 16.
<h2id="label_fruit"> Available Fruit</h2><ulrole="listbox"aria-labelledby="label_fruit"><lirole="option"aria-setsize="16"aria-posinset="5"> apples</li><lirole="option"aria-setsize="16"aria-posinset="6"> bananas</li><lirole="option"aria-setsize="16"aria-posinset="7"> cantaloupes</li><lirole="option"aria-setsize="16"aria-posinset="8"> dates</li></ul>
The following example shows items 5 through 8 in a set whose total size is unknown.
<h2id="label_fruit"> Available Fruit</h2><ulrole="listbox"aria-labelledby="label_fruit"><lirole="option"aria-setsize="-1"aria-posinset="5"> apples</li><lirole="option"aria-setsize="-1"aria-posinset="6"> bananas</li><lirole="option"aria-setsize="-1"aria-posinset="7"> cantaloupes</li><lirole="option"aria-setsize="-1"aria-posinset="8"> dates</li></ul>
Characteristic | Value |
---|---|
Used in Roles: | |
Inherits into Roles: | |
Value: | integer |
aria-sort
(property)§Indicates if items in a table or grid are sorted in ascending or descending order.
AuthorsSHOULD only apply thisproperty to table headers or grid headers. If the property is not provided, there is no defined sort order. For each table or grid, authorsSHOULD applyaria-sort
to only one header at a time.
Characteristic | Value |
---|---|
Used in Roles: | |
Value: | token |
Value | Description |
---|---|
ascending | Items are sorted in ascending order by this column. |
descending | Items are sorted in descending order by this column. |
none (default) | There is no defined sort applied to the column. |
other | A sort algorithm other than ascending or descending has been applied. |
aria-valuemax
(property)§Defines the maximum allowed value for a rangewidget.
AuthorsMUST ensure the value ofaria-valuemax
is greater than or equal to the value ofaria-valuemin
. If thearia-valuenow
has a known maximum and minimum, the authorSHOULD provide properties foraria-valuemax
andaria-valuemin
.
A range widget starts with a given value, which can be increased until reaching the maximum value, defined by thisproperty. Declaring the minimum and maximumvalues allows assistive technology to convey the size of the range to users.
Characteristic | Value |
---|---|
Related Concepts: | XForms [XFORMS10] range |
Used in Roles: | |
Inherits into Roles: | |
Value: | number |
aria-valuemin
(property)§Defines the minimum allowed value for a rangewidget.
AuthorsMUST ensure the value ofaria-valuemin
is less than or equal to the value ofaria-valuemax
. If thearia-valuenow
has a known maximum and minimum, the authorSHOULD provide properties foraria-valuemax
andaria-valuemin
.
A range widget starts with a given value, which can be decreased until reaching the minimum value, defined by thisproperty. Declaring the minimum and maximumvalues allows assistive technology to convey the size of the range to users.
Characteristic | Value |
---|---|
Related Concepts: | XForms [XFORMS10] range |
Used in Roles: | |
Inherits into Roles: | |
Value: | number |
aria-valuenow
(property)§Defines the current value for a rangewidget. See relatedaria-valuetext
.
This property is used, for example, on a range widget such as a slider or progress bar.
If the current value is not known (for example, an indeterminate progress bar), the authorSHOULD NOT set thearia-valuenow
attribute. If thearia-valuenow
attribute is absent, no information is implied about the current value. If thearia-valuenow
has a known maximum and minimum, the authorSHOULD provide properties foraria-valuemax
andaria-valuemin
.
The value ofaria-valuenow
is a decimal number. If the range is a set of numeric values, thenaria-valuenow
is one of those values. For example, if the range is [0, 1], a validaria-valuenow
is 0.5. A value outside the range, such as -2.5 or 1.1, is invalid.
Forprogressbar
elements andscrollbar
elements, assistive technologiesSHOULD render the value to users as a percent, calculated as a position on the range fromaria-valuemin
toaria-valuemax
if both are defined, otherwise the actual value with a percent indicator. For elements with roleslider
andspinbutton
, assistive technologiesSHOULD render the actual value to users.
When the rendered value cannot be accurately represented as a number, authorsSHOULD use thearia-valuetext
attribute in conjunction witharia-valuenow
to provide a user-friendly representation of the range's current value. For example, a slider may have rendered values ofsmall
,medium
, andlarge
. In this case, the values ofaria-valuetext
would be one of the strings:small
,medium
, orlarge
.
Ifaria-valuetext
is specified, assistive technologies render that instead of the value ofaria-valuenow
.
Characteristic | Value |
---|---|
Related Concepts: | XForms [XFORMS10] range, start |
Used in Roles: | |
Inherits into Roles: | |
Value: | number |
aria-valuetext
(property)§Defines the human readable text alternative ofaria-valuenow
for a rangewidget.
This property is used, for example, on a range widget such as a slider or progress bar.
If thearia-valuetext
attribute is set, authorsSHOULD also set thearia-valuenow
attribute, unless that value is unknown (for example, on an indeterminateprogressbar
).
AuthorsSHOULD only set thearia-valuetext
attribute when the rendered value cannot be meaningfully represented as a number. For example, a slider may have rendered values ofsmall
,medium
, andlarge
. In this case, the values ofaria-valuenow
could range from 1 through 3, which indicate the position of each value in the value space, but thearia-valuetext
would be one of the strings:small
,medium
, orlarge
. If thearia-valuetext
attribute is absent, theassistive technologies will rely solely on thearia-valuenow
attribute for the current value.
If aria-valuetext is specified, assistive technologiesSHOULD render that value instead of the value ofaria-valuenow
.
Characteristic | Value |
---|---|
Related Concepts: | XForms [XFORMS10] range, start |
Used in Roles: | |
Inherits into Roles: | |
Value: | string |
Theroles,state, andproperties defined in this specification do not form a complete web language or format. They are intended to be used in the context of a host language. This section discusses how host languages are to implementWAI-ARIA, to ensure that the markup specified here will integrate smoothly and effectively with the host language markup.
Although markup languages look alike superficially, they do not share language definition infrastructure. To accommodate differences in language-building approaches, the requirements are both general and modularization-specific. While allowing for differences in how the specifications are written, the intent is to maintain consistency in how theWAI-ARIA information looks to authors and how it is manipulated in theDOM by scripts.
WAI-ARIA roles, states, and properties are implemented asattributes ofelements. Roles are applied by placing their names among the tokens appearing in the value of a host-language-providedrole
attribute. States and properties each get their own attribute, with values as defined for each particular state or property in this specification. The name of the attribute is the aria-prefixed name of the state or property.
An implementing host language will provide anattribute with the following characteristics:
role
;An implementing host languageMUST allowattributes with the following characteristics:
aria-busy
,aria-selected
,aria-activedescendant
,aria-valuetext
;Host languages that supportXML Namespaces [xml-names]MAY require thatWAI-ARIA attributes be used with a namespace. In this case, the namespace forWAI-ARIA state and property attributesMUST behttp://www.w3.org/ns/wai-aria/
. To useWAI-ARIA in host languages that do not explicitly describe support for it, authorsSHOULD use this namespace as well, if the host language supports namespaces and there is expectation that user agents will recognize theWAI-ARIA namespace. The namespace prefix is not defined by this specification but generally is expected to be "aria
".
TheWAI-ARIA state and property attributes have a naming convention such that they all begin with the string "aria-
". This isnot a namespace prefix, it is a part of the state or property name. Therefore, when usingWAI-ARIA states and properties with namespace prefixes, the complete attribute name will be like "aria:aria-foo
".
Some host languages do not use namespaces withWAI-ARIA state and property attributes, either because the host language does not support namespaces or because the designers wish to incorporateWAI-ARIA into the core feature set. In these host languages, the namespace name for these attributes has no value. The names of these attributes do not have a prefix offset by a colon; in the terms of namespaces they are unprefixed attribute names. The ECMAScript binding of theDOM interfacegetAttributeNS
for example, treats an empty string (""
) as representing this condition, so that bothgetAttribute("aria-busy")
andgetAttributeNS("", "aria-busy")
access the samearia-busy
attribute in theDOM.
According to the requirements of this section, some user agents recognizeWAI-ARIA state and property attributeswith namespaces, somewithout namespaces, and some might recognize both. Authors are advised to be aware of which form is supported for the host language they are using. Unless the host language and supporting user agents explicitly indicate that the namespace is required, authors are advised to use the attribute without namespaces. Even user agents that support namespaces generally do not publish namespacedWAI-ARIA states and properties to accessibilityAPIs. In particular, current implementations ofHTML, includingXHTML, do not support this namespace.
An implementing host languageMUST provide support for the author to make all interactive elements focusable, that is, any renderable or event-receiving elements. An implementing host languageMUST provide a facility to allow web authors to define whether these focusable, interactive elements appear in the default tab navigation order. Thetabindex
attribute inHTML 5 is an example of one implementation.
WAI-ARIA is designed to providesemantic information about objects when host languages lack native semantics for the object.WAI-ARIA is designed, however, to provide additional semantics for many host languages. Furthermore, host languages over time can evolve and provide new native features that correspond toWAI-ARIA features. Therefore, there are many situations in whichWAI-ARIA semantics are redundant with host language semantics.
These host language features can be viewed as having "implicitWAI-ARIA semantics". User agent processing of features with implicitWAI-ARIA semantics would be similar to the processing for theWAI-ARIA feature. The processing might not be identical because of lexical differences between the host language feature and theWAI-ARIA feature, but generally the user agent would expose the same information to the accessibilityAPI. Features with implicitWAI-ARIA semantics satisfyWAI-ARIA structural requirements such as required owned elements, required states and properties, etc. and do not require explicitWAI-ARIA semantics to be provided. On elements with implicitWAI-ARIA roles, authors can also useWAI-ARIA states and properties supported by those roleswithout requiring explicit indication of theWAI-ARIA role.
For example, if an element with the functionality already exists, such as a checkbox or radio button, use the native semantics of the host language.WAI-ARIA markup is only intended to be used to enhance the native semantics (e.g., indicating that the element is required witharia-required
), or to change the semantics to a different purpose from the standard functionality of the element.
ImplicitWAI-ARIA semantics affect the conflict resolution procedures in the following section, Conflicts with Host Language Semantics. Therefore, implicitWAI-ARIA semantics need to be defined in a normative specification, such as the host language specification or theCore AccessibilityAPI Mappings [core-aam-1.1].
WAI-ARIA roles, states, and properties are intended to addsemantic information when native host language elements with these semantics are not available, and are generally used on elements that have no native semantics of their own. They can also be used on elements that have similar but non-identical semantics (for example, a nested list could be used to represent a tree structure). This method can be part of a fallback strategy for older browsers that have noWAI-ARIA implementation, or because native presentation of the repurposed element reduces the amount of style and/or script needed. Except for the cases outlined below, user agentsMUST always use theWAI-ARIA semantics to define how it exposes the element to accessibilityAPIs, rather than using the host language semantics.
In addition to these normal situations in whichWAI-ARIA is expected to override native semantics, there are elements that are inappropriate to override withWAI-ARIA. This could be because identical host language semantics exist, soWAI-ARIA is not needed, or because semantics fromWAI-ARIA directly conflict with host language semantics. When a feature in the host language with identical role semantics and values is available, and the author has no compelling reason to avoid using the host language feature, authorsSHOULD use the host language features rather than repurpose other elements withWAI-ARIA.
Host languages can have features that have implicitWAI-ARIA semantics corresponding to roles. When aWAI-ARIA role is provided, user agentsMUST use the semantic of theWAI-ARIA role for processing, not the native semantic, unless the role requiresWAI-ARIA states and properties whose attributes are explicitly forbidden on the native element by the host language. Values for roles do not conflict in the same way as values for states and properties (for example, theHTML 'checked' attribute and the 'aria-checked' attribute could have conflicting values), and authors are expected to have valid reason to provide aWAI-ARIA role even on elements that would not normally be repurposed.
WhenWAI-ARIA states and properties correspond to host language features that have the sameimplicitWAI-ARIA semantic, it can be particularly problematic to use theWAI-ARIA feature. If theWAI-ARIA feature and the host language feature are both provided but their values are not kept in sync, user agents and assistive technologies cannot know which value to use. Therefore, to prevent providing conflicting states and properties to assistive technologies, host languagesMUST explicitly declare where the use ofWAI-ARIA attributes on each host language element conflicts with native attributes for that element. When a host language declares aWAI-ARIA attribute to be in direct semantic conflict with a native attribute for a given element, user agentsMUST ignore theWAI-ARIA attribute and instead use the host language attribute with the same implicit semantic.
Host languagesMAY document features that cannot be overridden withWAI-ARIA (these are called "strong native semantics"). These can be features that have implicitWAI-ARIA semantics, as well as features where the processing would be uncertain if the semantics were changed withWAI-ARIA. Conformance checkersMAY signal an error or warning when aWAI-ARIA role is used on elements with strong native semantics, but as described above, user agentsMUST still use the value of the semantic of theWAI-ARIA role when exposing the element to accessibilityAPIs unless the native host language semantic is permanently presentational.
The opportunity for host languages to create exceptions to theWAI-ARIA override of native features is meant to avoid potential author errors or problems with intrinsic processing of host language features. Author errors could happen when a host language andWAI-ARIA provide similar but not identical features, where it might not be clear how changing one but not the other affects the accessibilityAPI. Intrinsic processing refers to the way a feature is processed, beyond simple rendering and exposure to the AccessibilityAPI, that cannot reasonably be changed in response to a ARIA feature, and would lead to unpredictable results were ARIA allowed. In these situations, there is good reason for host languages to limit the scope ofWAI-ARIA. However, this provision does not give blanket permission for host languages to forbid the use ofWAI-ARIA simply by documenting, feature by feature, that it may not be used. Host languages should create restrictions on the use of ARIA only when it is critical to effective processing of content.
Certain ARIA features are critical to building a complete model in the accessibilityAPI. Such features are not expected to conflict with native host language semantics (though they may complement them). Therefore, host languagesMUST NOT declare strong native semantics that prevent use of the following ARIA features:
State and property attributes are included in host languages, and therefore syntax for representation of their value types is governed by the host language. For each of the value types defined inValue, an appropriate value type from the host language is used. Recommended correspondences betweenWAI-ARIA value types and various host language value types are listed inMappingWAI-ARIA Value types to languages. This is a non-normative mapping in order to accommodate new host languages supportingWAI-ARIA.
The list value types—ID reference list and token list—allow more than one value of the given type to be provided. The values are separated by delimiter characters recognized by the host language for list attributes, such as space characters, commas, etc. Some languages may require a specific, single delimiter, while others may allow various delimiters.
Global states and properties are supported on any element in the host language. However, authorsMUST only use non-global states and properties on elements with a role supporting the state or property; either defined as an explicitWAI-ARIA role, or as defined by the host language implicitWAI-ARIA semantic matching an appropriateWAI-ARIA role. When a role attribute is added to an element, thesemantics and behavior of the element, including support forWAI-ARIA states and properties, are augmented or overridden by the role behavior. User agentsMUST ignore non-global states and properties used on an element without a role supporting the state or property; either defined as an explicitWAI-ARIA role, or as defined by the host languageWAI-ARIA semantic matching an appropriateWAI-ARIA role. For example, thearia-valuetext
attribute may be used on aprogressbar
.
WAI-ARIA roles have associated states and properties that are qualified as "supported" or "required". An example of a propertysupported by thecombobox role isaria-autocomplete. The property is designated "supported" in this case because a givencombobox
might or might not implement auto completion. In contrast, thecombobox
rolerequires thearia-expanded state in order to indicate that it is expandable. Comboboxes have a descendantlistbox
that is either open or closed. If thelistbox
is open, thecombobox
is in its expanded state; otherwise it is collapsed.
WhenWAI-ARIA roles are used,supported states and properties that are not present in theDOM are treated according to their default value. Keeping with thecombobox
example, a missingaria-autocomplete
attribute is equivalent toaria-autocomplete="none"
, meaning thecombobox
does not offer auto completion.
However,required states and properties that are absent are an author error. Missing required states and properties are treated as if they were present and have an implicit neutral value that is not necessarily their default value. For example, the default value ofaria-expanded
isundefined
, meaning neither expandable nor collapsible. But that does not apply to the case of acombobox
. In this case,aria-expanded
is needed to convey the expandable/collapsible nature of thecombobox
. Thus, the implicit value ofaria-expanded
for thecombobox
role isfalse
, meaning expandable (and currently collapsed). The characteristics table associated with eachWAI-ARIA role has an "Implicit Value for Role" entry that specifies the value of a state or property to use in the context of that role when the state or property is missing.
Elements that have implicitWAI-ARIA semantics support the full set ofWAI-ARIA states and properties supported by the corresponding role. Therefore, authorsMAY omit the role when setting states and properties. The role is only needed when the implicitWAI-ARIA role of the element needs to be changed.
Sometimes states and properties are present in theDOM but have a zero-length string ("") as their value. This is equivalent to their absence. User agentsSHOULD treat state and property attributes with a value of "" the same as they treat an absent attribute. For supported states and properties, this corresponds to the default value, but if it is a required attribute, it signals an author error, and the implicit value for the role is used.
This section is non-normative.
WAI-ARIA roles, states, and properties are available in a number of machine-readable formats to support validation of content usingWAI-ARIA attributes.WAI-ARIA is not finalized, however, so these files are subject to change without notice.Todo: Remove disclaimers about not final at rec.
It is not appropriate to use these document types for live content. These are made available only for download, to support local use in development, evaluation, and validation tools. Using these versions directly from theW3C server could cause automatic blockage, preventing them from loading.
If it is necessary to use schemata in content, followguidelines to avoid excessiveDTD traffic. For instance, use caching proxies to avoid fetching the schema each time it is used, or ensure software uses a local cache, such as withXML catalogs.
The taxonomy forWAI-ARIA expressed inRDF is available fromhttp://www.w3.org/WAI/ARIA/schemata/aria-1.rdf.
This module declares theWAI-ARIAattributes as a module that can be included in a modularizedDTD. A sampleXHTMLDTD using this module follows. Note theWAI-ARIA attributes are in no namespace, and the attribute name begins with "aria-" to reduce the likelihood of collision with existing attributes.
This module is available fromhttp://www.w3.org/MarkUp/DTD/aria-attributes-1.mod.
ThisDTD extendsXHTML 1.1 and adds theWAI-ARIAstate andpropertyattributes to all itselements. In order to provide broader keyboard support and conform with the Focus Navigation section above, it also adds thetabindex
attribute to a wider set of elements.
This is not a formal document type and may be obsoleted by future formalXHTML DTDs that supportWAI-ARIA.
TheXHTML 1.1 plusWAI-ARIADTD is available fromhttp://www.w3.org/WAI/ARIA/schemata/xhtml-aria-1.dtd.
Documents written using thisXHTML Family markup language can be validated using the aboveDTD. If a document author wants to facilitate such validation, they can include the following declaration at the top of their document:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+ARIA 1.0//EN" "http://www.w3.org/WAI/ARIA/schemata/xhtml-aria-1.dtd">
However, note that when this DOCTYPE is present in a document, most user agents treat the document as genericXML rather thanHTML. This causes them to be unable to support named character entities defined by theDTD (e.g., ©). Therefore, authors need to avoid use of named entities outside of thepredefined entities inXML ([xml11], Section 4.6).
To avoid the above problem, authors can omit the above DOCTYPE statement. This causes user agents to treat the document as genericHTML with named character entity support as well as built-in ARIA support. However, it causes user agents to enter "quirks" mode which affectsCSS rendering, and causes conformance checkers to fail the document due to the added ARIA attributes.
To avoid the issues of named character entity support and quirks mode, authors can instead use the following generic DOCTYPE declaration forHTML:
<!DOCTYPE html>
However, this still does not guarantee that documents will be validated by conformance checkers.
This section contains the SGML Open Catalog-format definition [SGML-CATALOG] of the public identifiers forXHTML+ARIA 1.0.
-- .......................................................................... ---- File catalog ............................................................ ---- XHTML+ARIA Catalog Data FileRevision: $Revision:1.40 $See"Entity Management", SGML Open Technical Resolution9401for detailedinformation on supplying and using catalog data. Thisdocument is availablefrom OASIS at URL:<http://www.oasis-open.org/html/tr9401.html>---- .......................................................................... ---- SGML declaration associated with XHTML .................................. --OVERRIDE YESSGMLDECL "xml1.dcl"-- :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ---- XHTML+ARIA modules .............................................. --PUBLIC "-//W3C//DTD XHTML+ARIA 1.0//EN" "xhtml-aria-1.dtd"PUBLIC "-//W3C//ENTITIES XHTML ARIA Attributes 1.0//EN" "aria-attributes-1.mod"-- End of catalog data ..................................................... ---- .......................................................................... --
This module declares theWAI-ARIAattributes as anXML Schema module that can be included in a modularized schema. Note theWAI-ARIA attributes are in no namespace, and the attribute name begins with "aria-" to reduce the likelihood of collision with existing attributes.
This module is available fromhttp://www.w3.org/MarkUp/SCHEMA/aria-attributes-1.xsd.
This standaloneDTD addsWAI-ARIAstate andpropertyattributes to allelements inHTML 4.01, as well as arole
attribute. In order to provide broader keyboard support, it also adds thetabindex
attribute to a wider set of elements.
TheDTD is based on theHTML 4.01 TransitionalDTD, and includes all entity references needed to make it a standalone file.This is not an officialW3CDTD and should be considered a derivative work ofHTML 4.01.
Documents written using this markup language can be validated using the aboveDTD. If a document author wants to facilitate such validation, they can include the following declaration at the top of their document:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML+ARIA 1.0//EN""http://www.w3.org/WAI/ARIA/schemata/html4-aria-1.dtd">
However, note that when this DOCTYPE is present in a document, most user agents treat the document as genericXML rather thanHTML. This causes them to be unable to support named character entities defined by theDTD (e.g., ©). Therefore, authors need to avoid use of named entities outside of thepredefined entities inXML ([xml11], Section 4.6).
To avoid the above problem, authors can omit the above DOCTYPE statement. This causes user agents to treat the document as genericHTML with named character entity support as well as built-in ARIA support. However, it causes user agents to enter "quirks" mode which affectsCSS rendering, and causes conformance checkers to fail the document due to the added ARIA attributes.
To avoid the issues of named character entity support and quirks mode, authors can instead use the following generic DOCTYPE declaration forHTML:
<!DOCTYPE html>
However, this still does not guarantee that documents will be validated by conformance checkers.
TheHTML Working Group is incorporatingWAI-ARIA intoHTML5. Official support forWAI-ARIA inHTML will be provided in that specification. ThisDTD is made availableonly as a bridging solution for applications requiringDTD validation but not usingHTML 5.
This module is available fromhttp://www.w3.org/WAI/ARIA/schemata/html4-aria-1.dtd.
This section is non-normative.
TheHTML 5 column of the table below is advisory. Guidance on use ofWAI-ARIA state and properties inHTML 5 is provided inState and Property Attributes ([html51], section 3.2.7.3.2).
The suggested mappings for true/false values inHTML 5 useKeyword and enumerated attributes with allowed values oftrue
andfalse
, instead of using theHTML 5 boolean value type.
The table below provides recommended mappings betweenWAI-ARIA state and property types and attribute types fromHTML 5,XML Schema Datatypes [xmlschema-2],SVG, and SGML.
Languages not listed below might have appropriate value types defined in the language. If they do not, we recommendXML Schema Datatypes for general purposeXML languages. Documents using DTDs instead of schemas will not be able to validate automatically and require additional processing onWAI-ARIA attributes.
WAI-ARIA type | HTML 5 | XML Schema |
---|---|---|
true/false | Keyword and enumerated attributes with allowed values of "true" and "false" | boolean |
true/false/undefined | Keyword and enumerated attributes with allowed values oftrue ,false , andundefined | NMTOKEN with anenumeration constraint allowing values oftrue ,false , andundefined |
tristate | Keyword and enumerated attributes with allowed values of "true", "false", and "mixed" | NMTOKEN with anenumeration constraint allowing values of "true", "false", and "mixed" |
number | Floating-point numbers | decimal |
integer | Non-negative integer | integer |
token | Keyword and enumerated attributes | NMTOKEN with anenumeration constraint allowing values listed in the state or property definition |
token list | Space-separated tokens | NMTOKENS with anenumeration constraintallowing values listed in the state or property definition |
ID reference | The value of a definedid attribute on another element | IDREF |
ID reference list | The value of one or more definedid attributes on other element(s), represented asSpace-separated tokens | IDREFS |
string | No value constraints | string |
aria-describedat
after much group deliberation.aria-orientation
now defaults to undefined, and is allowed on more roles with implicit defaults defined per role.radio
no longer inherits fromoption
, just fromcheckbox
.radio
now addsaria-posinset
andaria-setsize
.aria-posinset
andaria-setsize
totab
.none
role.aria-selected
from "supported" to "required" attribute list foroption
role.rowgroup
to subclassstructure
instead ofgroup
.aria-modal
attribute.text
role.searchbox
role.switch
role.aria-current
attribute.region
a type oflandmark
. Add requirement that authorsMUST give aregion
a brief label that describes the purpose of the content it contains. Remove theaccessible name property from thesection
role. Change the superclass role fromregion
tosection
for the following roles:alert
,grid
,landmark
,list
,log
,status
, andtabpanel
. Removeregion
as a superclass role ofarticle
, makingdocument
the only superclass role ofarticle
.aria-placeholder
attribute.aria-colcount
,aria-rowcount
,aria-colindex
,aria-rowindex
,aria-colspan
, andaria-rowspan
.cell
andtable
roles for non-interactive tables. Madegridcell
andgrid
subclasses ofcell
andtable
respectively. Removedwidget
as one of the immediate superclasses ofcolumnheader
androwheader
. Headers that subclassgridcell
will still inherit the supported properties ofwidget
.aria-kbdshortcuts
. Note that his has subsequently been replaced byaria-keyshortcuts
.aria-roledescription
attribute.aria-readonly
as a supported property ofcheckbox
,menuitemcheckbox
,menuitemradio
, andswitch
. Because this property should not apply toradio
,radio
was made a subclass ofinput
.aria-valuemin
,aria-valuemax
, andaria-valuenow
when they are required for rolesscrollbar
,slider
, andspinbutton
.aria-level
a required attribute forheading
with an implicit value of 2.aria-readonly
as a supported property of:combobox
,listbox
,radiogroup
,slider
, andspinbutton
.aria-errormessage
attribute.-1
as a valid value foraria-setsize
as a means to indicate that the set size is unknown and should not be calculated by user agents.term
role.aria-readonly
andaria-required
SHOULD NOT be used or exposed oncolumnheader
orrowheader
when those headers descend from a non-interactivetable
.figure
role.feed
role; madearia-posinset
andaria-setsize
supported properties ofarticle
; changedaria-busy
so that it could be applied to all elements rather than limited tolive regions; added normative requirement that authorsMUST setaria-busy
totrue
if changes to a renderedwidget
would result in thatwidget
missing required owned elements during the update process.application
fromlandmark
tostructure
; removed the accessible name requirement fromdocument
.list
as a superclass ofmenu
andlistbox
, making it a related concept of each. Removeddirectory
as a superclass oftablist
.input
as a superclass ofscrollbar
andselect
.aria-grabbed
andaria-dropeffect
as planned for deprecation.aria-orientation
oncombobox
.aria-details
attribute.aria-describedat
which has been made obsolete byaria-details
.aria-errormessage
content is not hidden and is included in a container that exposes the content to the user.spinbutton
: Default foraria-valuenow
is0
. There is no minimum value foraria-valuemin
and no maximum value foraria-valuemax
.true
fromspinbutton
; makespinbutton
a subclass ofcomposite
.widget
as a (possible) superclass ofseparator
. Addaria-valuemax
,aria-valuemin
,aria-valuenow
, andaria-valuetext
as supported properties ofseparator
.true
frommenuitem
andtreeitem
.password
. The ARIA Working Group agreed tomove the password role to ARIA 2.0. Note that the content is currently only commented out until we branch for ARIA 1.1.aria-valuenow
a required property, and removearia-expanded
as a supported state, of focusableseparator
elements.aria-roledescription
. Add several normative requirements for authors, user agents, and assistive technologies.aria-details
regarding exposure of content from aMUST to aSHOULD.aria-keyshortcuts
(as a replacement for thearia-kbdshortcuts
which was introduced on 12-Jun-2015.password
role.aria-haspopup
from boolean to token. Supported values are:true
,false
,menu
,listbox
,tree
,grid
, anddialog
.combobox
to includetree
,grid
, anddialog
. In addition, the implicit value foraria-haspopup
for rolecombobox
was changed fromtrue
tolistbox
.aria-describedby
,aria-label
,aria-labelledby
.aria-posinset
andaria-setsize
as supported properties ofmenuitem
.aria-activedescendant
as a supported property ofapplication
.text
. The ARIA Working Group agreed tomove the text role to ARIA 2.0. Note that the content is currently only commented out until we branch for ARIA 1.1.true
tocheckbox
,menuitem
,menuitemcheckbox
,menuitemradio
,option
,radio
,spinbutton
,switch
,tab
, andtreeitem
. (N.B. See subsequent items as some of this is being undone as the result of further discussions within the working group.)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.