Movatterモバイル変換


[0]ホーム

URL:


W3C

Accessible Rich Internet Applications (WAI-ARIA) 1.1

W3C Recommendation

This version:
https://www.w3.org/TR/2017/REC-wai-aria-1.1-20171214/
Latest published version:
https://www.w3.org/TR/wai-aria-1.1/
Latest editor's draft:
https://w3c.github.io/aria/
Implementation report:
https://w3c.github.io/test-results/wai-aria/
Previous version:
https://www.w3.org/TR/2017/PR-wai-aria-1.1-20171102/
Previous Recommendation:
https://www.w3.org/TR/wai-aria-1.0/
Editors:
Joanmarie Diggs, Igalia, S.L.,jdiggs@igalia.com
Shane McCarron, Spec-Ops,shane@spec-ops.io
Michael Cooper,W3C,cooper@w3.org
Richard Schwerdtfeger, IBM Corporation,schwer@us.ibm.com (until October 2017)
James Craig, Apple Inc.,jcraig@apple.com (until May 2016)

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.


Abstract

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.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of 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.

1.Introduction§

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.

1.1Rich Internet Application Accessibility§

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.

The contract model with accessibility APIs

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.

Note

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.

1.2Target Audience§

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:

1.3User Agent Support§

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.

1.4Co-Evolution ofWAI-ARIA and Host Languages§

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.

1.5Authoring Practices§

1.5.1Authoring Tools§

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.

1.5.2Testing Practices and Tools§

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.

1.6Assistive Technologies§

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.

2.UsingWAI-ARIA§

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.

2.1WAI-ARIA Roles§

AWAI-ARIArole is set on anelement using aroleattribute, similar to therole attribute defined inRole Attribute [role-attribute].

Example 1
<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:

Attaching a role givesassistive technologies information about how to handle each element.

2.2WAI-ARIA States and Properties§

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.

Example 2
<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.

Example 3
[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.

Example 4
<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>

2.3Managing Focus§

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.

WAI-ARIA includes a number of "managing container" widgets, also known as "composite" widgets. When appropriate, the container is responsible for tracking the last descendant that was active (the default is usually the first item in the container). It is essential that a container maintain a usable and consistent strategy when focus leaves a container and is then later refocused. While there may be exceptions, it is recommended that when a previously focused container is refocused, the active descendant be the same element as the active descendant when the container was last focused. Exceptions include cases where the contents of a container widget have changed, and widgets like a menubar where the user expects to always return to the first item when focus leaves the menu bar. For example, if the second item of a tree group was the active descendant when the user tabbed out of the tree group, then the second item of the tree group remains the active descendant when the tree group gets focus again. The user may also activate the container by clicking on one of the descendants within it.

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-activedescendantattribute 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].

3.Conformance§

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

The key 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.

3.1Non-interference with the Host Language§

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.

3.2AllWAI-ARIA inDOM§

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.

3.3Assistive Technology Notifications Communicated to Web Applications§

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.

Note

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.

3.4Conformance Checkers§

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.

3.5Deprecated Requirements§

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.

4.Important Terms§

This section is non-normative.

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

AccessibilityAPI

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

Accessible Description

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.

Accessible Name

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.

Assistive 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:

Attribute

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.

Class

A set of instanceobjects that share similar characteristics.

Deprecated

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.

Element

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

Event

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.

Graphical Document

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

Hidden

Indicates that 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.

Informative

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

Keyboard Accessible

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

Landmark

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

Live Region

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

Managed State

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.

Nemeth Braille

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

Normative

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

Object

In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or 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.
Ontology

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

Operable

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.

Owned Element

An 'owned element' is anyDOM descendant of theelement, any element specified as a child viaaria-owns, or anyDOM descendant of the owned child.

Perceivable

Presentable to users in ways they can sense. References in this document relate toWCAG 2.0 Principle 1: Content must be perceivable [WCAG20].

Property

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.

Relationship

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

Role

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.

Semantics

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.

State

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.

Taxonomy

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.

Understandable

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

User Agent

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

Widget

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

5.The Roles Model§

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.

5.1Relationships Between Concepts§

Theroletaxonomy uses the following relationships to relateWAI-ARIA roles to each other and to concepts from other specifications, such asHTML and XForms.

5.1.1Superclass Role§

Inheritance is expressed inRDF using theRDF Schema 1.1subClassOf ([rdf-schema]) property.

RDF Property
rdfs:subClassOf

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.

5.1.2Subclass Roles§

RDF Property
<none>

Informative list ofroles for which this role is the superclass. This is provided to facilitate reading of the specification but adds no new information.

5.1.3Related Concepts§

RDF Property
role:relatedConcept

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, theprogressbarwidget has arelatedConcept value which includesstatus. However, if the definition ofstatus is modified, the definition of aprogressbar is not affected.

5.1.4Base Concept§

RDF Property
role:baseConcept

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.

5.2Characteristics of Roles§

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.

5.2.1Abstract Roles§

RDF Property
N/A
Values
Boolean

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:

  1. Organize the roletaxonomy and provide roles with a meaning in the context of known concepts.
  2. Streamline the addition of roles that include necessary features.

5.2.2Required States and Properties§

RDF Property
role:requiredState
Values
Any validRDF object reference, such as aURI.

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.

Note

A host language attribute with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.

5.2.3Supported States and Properties§

RDF Property
role:supportedState
Values
Any validRDF object reference, such as aURI.

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.

Note

A host language attribute with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.

5.2.4Inherited States and Properties§

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.

5.2.5Required Owned Elements§

RDF Property
role:mustContain
Values
Any validRDF object reference, such as aURI.

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.

Note

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.

Note

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.

Note

An element with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.

5.2.6Required Context Role§

RDF Property
role:scope
Values
Any validRDF object reference, such as aURI.

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.

Note

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.

Note

An element with the appropriateimplicitWAI-ARIA semantic fulfills this requirement.

5.2.7Accessible Name Calculation§

RDF Property
role:nameFrom
Values
One of the following values:
  1. author: name comes from values provided by the author in explicit markup features such as thearia-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.
  2. contents: name comes from the text value of theelement node. Although this may be allowed in addition to "author" in someroles, this is used in content only if higher priority "author" features are not provided. Priority is defined by thetext alternative computation algorithm.
5.2.7.1Name Computation§

Name Computation is defined in the Accessible Name and Description specification [accname-aam-1.1].

5.2.7.2Description Computation§

Description Computation is defined in the Accessible Name and Description specification [accname-aam-1.1].

5.2.7.3Text Alternative Computation§

Text Alternative Computation is defined in the Accessible Name and Description specification [accname-aam-1.1].

5.2.7.4Roles Supporting Name from Author§

All roles support name from author with two exceptions. The roles that do not support name from author arepresentation andnone.

5.2.7.5Roles Supporting Name from Content§

5.2.8Presentational Children§

RDF Property
role:childrenArePresentational
Values

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.

5.2.9Implicit Value for Role§

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.

5.3Categorization of Roles§

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

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:

  1. Abstract Roles
  2. Widget Roles
  3. Document Structure Roles
  4. Landmark Roles
  5. Live Region Roles
  6. Window Roles

5.3.1Abstract Roles§

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.

5.3.2Widget Roles§

The following roles act as standalone user interface widgets or as part of larger, composite widgets.

The following roles act as composite user interface widgets. These roles typically act as containers that manage other, contained widgets.

5.3.3Document Structure§

The followingroles describe structures that organize content in a page. Document structures are not usually interactive.

5.3.4Landmark Roles§

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.

5.3.5Live Region Roles§

The followingroles arelive regions and may be modified bylive region attributes.

5.3.6Window Roles§

The followingroles act as windows within the browser or application.

5.4Definition of Roles§

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
A type oflive region with important, and usually time-sensitive, information. See relatedalertdialog andstatus.
alertdialog
A type of dialog that contains an alert message, where initial focus goes to anelement within the dialog. See relatedalert anddialog.
application
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.
article
A section of a page that consists of a composition that forms an independent part of a document, page, or site.
banner
A region that contains mostly site-oriented content, rather than page-specific content.
button
An input that allows for user-triggered actions when clicked or pressed. See relatedlink.
cell
A cell in a tabular container. See relatedgridcell.
checkbox
A checkable input that has three possiblevalues:true,false, ormixed.
columnheader
A cell containing header information for a column.
combobox
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.
command (abstract role)
A form of widget that performs an action but does not receive input data.
complementary
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.
composite (abstract role)
Awidget that may contain navigable descendants or owned children.
contentinfo
A large perceivable region that contains information about the parent document.
definition
A definition of a term or concept. See relatedterm.
dialog
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.
directory
A list of references to members of a group, such as a static table of contents.
document
Anelement containing content thatassistive technology users may want to browse in a reading mode.
feed
A scrollablelist ofarticles where scrolling may causearticles to be added to or removed from either end of the list.
figure
A perceivablesection of content that typically contains agraphical document, images, code snippets, or example text. The parts of afigureMAY be user-navigable.
form
Alandmark region that contains a collection of items and objects that, as a whole, combine to create a form. See relatedsearch.
grid
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.
gridcell
Acell in agrid ortreegrid.
group
A set of user interfaceobjects which are not intended to be included in a page summary or table of contents byassistive technologies.
heading
A heading for a section of the page.
img
A container for a collection ofelements that form an image.
input (abstract role)
A generic type ofwidget that allows user input.
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.
link
An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See relatedbutton.
list
Asection containinglistitem elements. See relatedlistbox.
listbox
Awidget that allows the user to select one or more items from a list of choices. See relatedcombobox andlist.
listitem
A single item in a list or directory.
log
A type oflive region where new information is added in meaningful order and old information may disappear. See relatedmarquee.
main
The main content of a document.
marquee
A type oflive region where non-essential information changes frequently. See relatedlog.
math
Content that represents a mathematical expression.
menu
A type ofwidget that offers a list of choices to the user.
menubar
A presentation ofmenu that usually remains visible and is usually presented horizontally.
menuitem
An option in a set of choices contained by amenu ormenubar.
menuitemcheckbox
Amenuitem with a checkable state whose possiblevalues aretrue,false, ormixed.
menuitemradio
A checkablemenuitem in a set of elements with the same role, only one of which can be checked at a time.
navigation
A collection of navigationalelements (usually links) for navigating the document or related documents.
none
Anelement whose implicit native role semantics will not be mapped to theaccessibilityAPI. See synonympresentation.
note
A section whose content is parenthetic or ancillary to the main content of the resource.
option
A selectable item in aselect list.
presentation
Anelement whose implicit native role semantics will not be mapped to theaccessibilityAPI. See synonymnone.
progressbar
Anelement that displays the progress status for tasks that take a long time.
radio
A checkable input in a group of elements with the same role, only one of which can be checked at a time.
radiogroup
A group ofradio buttons.
range (abstract role)
An input representing a range of values that can be set by the user.
region
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.
roletype (abstract role)
The baserole from which all other roles in thistaxonomy inherit.
row
A row of cells in a tabular container.
rowgroup
A structure containing one or more row elements in a tabular container.
rowheader
A cell containing header information for a row in a grid.
scrollbar
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.
search
Alandmark region that contains a collection of items and objects that, as a whole, combine to create a search facility. See relatedform andsearchbox.
searchbox
A type of textbox intended for specifying search criteria. See relatedtextbox andsearch.
section (abstract role)
A renderable structural containment unit in a document or application.
sectionhead (abstract role)
A structure that labels or summarizes the topic of its related section.
select (abstract role)
A form widget that allows the user to make selections from a set of choices.
separator
A divider that separates and distinguishes sections of content or groups of menuitems.
slider
A user input where the user selects a value from within a given range.
spinbutton
A form ofrange that expects the user to select from among discrete choices.
status
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.
structure (abstract role)
A document structuralelement.
switch
A type of checkbox that represents on/off values, as opposed to checked/unchecked values. See relatedcheckbox.
tab
A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.
table
Asection containing data arranged in rows and columns. See relatedgrid.
tablist
A list oftabelements, which are references totabpanel elements.
tabpanel
A container for the resources associated with atab, where eachtab is contained in atablist.
term
A word or phrase with a corresponding definition. See relateddefinition.
textbox
A type of input that allows free-form text as its value.
timer
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.
toolbar
A collection of commonly used function buttons or controls represented in compact visual form.
tooltip
A contextual popup that displays a description for an element.
tree
A type oflist that may contain sub-level nested groups that can be collapsed and expanded.
treegrid
Agrid whose rows can be expanded and collapsed in the same manner as for atree.
treeitem
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.
widget (abstract role)
An interactive component of a graphical user interface (GUI).
window (abstract role)
A browser or application window.

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

Characteristics:
CharacteristicValue
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 foraria-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. Thealertdialogrole 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.

Characteristics:
CharacteristicValue
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:

  1. Associate the content with a focusable element usingaria-labelledby oraria-describedby.
  2. Place the content in a focusable element that has roledocument orarticle.
  3. Manage focus of descendants as described inManaging Focus, updating the value ofaria-activedescendant to reference theelement containing the focused content.
Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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 thebannerrole.

Note

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

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Superclass Role:command
Base Concept:HTMLbutton
Related Concepts:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
Superclass Role:section
Subclass Roles:
Base Concept:HTMLtd
Required Context Role:row
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author

checkbox(role)§

A checkable input that has three possiblevalues:true,false, ormixed.

Thearia-checkedattribute 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.

Characteristics:
CharacteristicValue
Superclass Role:input
Subclass Roles:
Related Concepts:
Required States and Properties:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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 anHTMLthelement 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.

Note

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.

Characteristics:
CharacteristicValue
Superclass Role:
Base Concept:HTMLth[scope="col"]
Required Context Role:row
Supported States and Properties:aria-sort
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Example 5
<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.

Characteristics:
CharacteristicValue
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 foraria-haspopup islistbox.

command(abstract role)§

A form of widget that performs an action but does not receive input data.

Note

command is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Note

composite is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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.

Note

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.

Characteristics:
CharacteristicValue
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-labelledbyattribute.

Characteristics:
CharacteristicValue
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.

Note

In the description of this role, the term "web application" does not refer to theapplication role, which specifies specific assistive technology behaviors.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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 afigureMAY 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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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 orcolumnheaderrole 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:

  • If agridcell 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.
  • Otherwise, authorsSHOULD ensure the element that receives focus is agridcell,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:

  • a widget that requires arrow keys to operate, e.g., acombobox orradiogroup
  • multiple interactive elements
  • editable content

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

Characteristics:
CharacteristicValue
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)§

Acell in agrid ortreegrid.

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.

Characteristics:
CharacteristicValue
Superclass Role:
Subclass Roles:
Base Concept:HTMLtd
Required Context Role:row
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
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-labelledbyattribute 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.

Characteristics:
CharacteristicValue
Superclass Role:sectionhead
Related Concepts:HTMLh1,h2,h3,h4,h5, andh6
Required States and Properties:aria-level
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Note

landmark is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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.

Note

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.

Characteristics:
CharacteristicValue
Superclass Role:command
Related Concepts:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
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 standardHTMLselectelements, 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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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. Themainrole 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.

Note

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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Note

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.

MathML Example with Embedded TeX Annotation§

Example 6
<!--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>&#x2062;<!-- &InvisibleTimes; --></mo><mi>a</mi><mo>&#x2062;<!-- &InvisibleTimes; --></mo><mi>c</mi></msqrt></mrow><mrow><mn>2</mn><mo>&#x2062;<!-- &InvisibleTimes; --></mo><mi>a</mi></mrow></mfrac></mrow><annotationencoding="TeX">    x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}</annotation></math>

PlainHTML or PolyfillDOM Result of theMathML Quadratic Formula§

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">
Characteristics:
CharacteristicValue
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. Themenurole 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.

Characteristics:
CharacteristicValue
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.

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

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Superclass Role:
Subclass Roles:
Related Concepts:
Required Context Role:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
Accessible Name Required:True

menuitemcheckbox(role)§

Amenuitem with a checkable state whose possiblevalues aretrue,false, ormixed.

Thearia-checkedattribute 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.

Characteristics:
CharacteristicValue
Superclass Role:
Subclass Roles:
Related Concepts:menuitem
Required Context Role:
Inherited States and Properties:
Name From:
  • contents
  • author
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-checkedattribute 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.

Characteristics:
CharacteristicValue
Superclass Role:
Related Concepts:menuitem
Required Context Role:
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
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.

Note

Note regarding the ARIA 1.1none 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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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:
  • contents
  • author
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.

Note

Note regarding the ARIA 1.1none 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:

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 (therowrole), 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, theimgelement 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 oriframeelement, 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>

There are otherWAI-ARIA roles with required children for which this situation is applicable (e.g., radiogroups and listboxes), but tables and lists are the most common real-world cases in which the presentation inheritance is likely to apply.

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>
Presentational Roles Conflict Resolution§

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.

Example 12
<!-- 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.

Characteristics:
CharacteristicValue
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.

Note

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.

Characteristics:
CharacteristicValue
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-ownsattribute on theradiogroup element to indicate therelationship to its children.

Characteristics:
CharacteristicValue
Superclass Role:
Subclass Roles:
Related Concepts:HTMLinput[type="radio"]
Required States and Properties:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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-checkedattribute becomesfalse).

Characteristics:
CharacteristicValue
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.

Note

range is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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 orgridcellelements, and thus serve to organize thetable orgrid.

In atreegrid, authorsMAY mark rows as expandable, using thearia-expandedattribute 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.

Characteristics:
CharacteristicValue
Superclass Role:
Base Concept:HTMLtr
Required Context Role:
Required Owned Elements:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author

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

AuthorsMUST ensureelements withrolerowgroup are contained in, orowned by, an element with the roletable orgrid.

Note

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.

Characteristics:
CharacteristicValue
Superclass Role:structure
Base Concept:
Required Context Role:
Required Owned Elements:row
Inherited States and Properties:
Name From:
  • contents
  • author

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

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.

Characteristics:
CharacteristicValue
Superclass Role:
Base Concept:HTMLth[scope="row"]
Required Context Role:row
Supported States and Properties:aria-sort
Inherited States and Properties:
Name From:
  • contents
  • author
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:

  • Ifaria-valuemin is missing or not anumber, it defaults to 0 (zero).
  • Ifaria-valuemax is missing or not anumber, it defaults to 100.
  • Ifaria-valuenow is missing or not anumber, it defaults to the value half way betweenaria-valuemin andaria-valuemax.
  • Ifaria-valuenow is present but less thanaria-valuemin, it defaults to the value ofaria-valuemin.
  • Ifaria-valuenow is present but greater thanaria-valuemax, it defaults to the value ofaria-valuemax.

Elements with the rolescrollbar have an implicitaria-orientation value ofvertical.

Note

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.

Characteristics:
CharacteristicValue
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 foraria-valuemin is0.
Default foraria-valuemax is100.
Default foraria-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.

Characteristics:
CharacteristicValue
Superclass Role:landmark
Inherited States and Properties:
Name From:author

searchbox(role)§

A type of textbox intended for specifying search criteria. See relatedtextbox andsearch.

Characteristics:
CharacteristicValue
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.

Note

section is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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.

Note

sectionhead is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
Is Abstract:True
Superclass Role:structure
Subclass Roles:
Supported States and Properties:aria-expanded
Inherited States and Properties:
Name From:
  • contents
  • author

select(abstract role)§

A form widget that allows the user to make selections from a set of choices.

Note

select is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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:

  • The implicit value ofaria-valuemin is0.
  • The implicit value ofaria-valuemax is100.
  • The implicit value ofaria-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.

Characteristics:
CharacteristicValue
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 foraria-valuemin is0.
Default foraria-valuemax is100.
Default foraria-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:

  • Ifaria-valuemin is missing or not anumber, it defaults to 0 (zero).
  • Ifaria-valuemax is missing or not anumber, it defaults to 100.
  • Ifaria-valuenow is missing or not anumber, it defaults to the value half way betweenaria-valuemin andaria-valuemax.
  • Ifaria-valuenow is present but less thanaria-valuemin, it defaults to the value ofaria-valuemin.
  • Ifaria-valuenow is present but greater thanaria-valuemax, it defaults to the value ofaria-valuemax.

Elements with the roleslider have an implicitaria-orientation value ofhorizontal.

Characteristics:
CharacteristicValue
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 foraria-valuemin is0.
Default foraria-valuemax is100.
Default foraria-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 aselectwidget 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:

  • The implicit value ofaria-valuemin is that there is no minimum value.
  • The implicit value ofaria-valuemax is that there is no maximum value.
  • The implicit value ofaria-valuenow is0.
Characteristics:
CharacteristicValue
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 foraria-valuemax is that there is no maximum value.
Default foraria-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-controlsattribute.

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.

Characteristics:
CharacteristicValue
Superclass Role:section
Subclass Roles:
Inherited States and Properties:
Name From:author
Implicit Value for Role:Default foraria-live ispolite.
Default foraria-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.

Note

structure is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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-checkedattribute 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.

Note

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.

Characteristics:
CharacteristicValue
Superclass Role:checkbox
Related Concepts:button
Required States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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 othertabpanelelements from the user until the user selects the tab associated with that tabpanel. For a multi-selectabletablist, authorsSHOULD ensure each visibletabpanel has itsaria-expandedattribute 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.

Characteristics:
CharacteristicValue
Superclass Role:
Required Context Role:tablist
Supported States and Properties:
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
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 oftabelements, 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 othertabpanelelements from the user until the user selects the tab associated with that tabpanel. For a multi-selectabletablist, authorsSHOULD ensure each visibletabpanel has itsaria-expandedattribute 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.

Characteristics:
CharacteristicValue
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 atabpanelelement 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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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-multilineattribute 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.

Note

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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Superclass Role:section
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Characteristics:
CharacteristicValue
Superclass Role:select
Subclass Roles:
Required Owned Elements:
Supported States and Properties:
Inherited States and Properties:
Name From:
  • author
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.

Characteristics:
CharacteristicValue
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 thegrouprole.

AuthorsMUST ensureelements withroletreeitem are contained in, orowned by, an element with the rolegroup ortree.

Characteristics:
CharacteristicValue
Superclass Role:
Required Context Role:
Inherited States and Properties:
Name From:
  • contents
  • author
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.

Note

widget is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
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.

Note

window is an abstract role used for the ontology. Authors should not use this role in content.

Characteristics:
CharacteristicValue
Is Abstract:True
Superclass Role:roletype
Subclass Roles:
Supported States and Properties:
Inherited States and Properties:
Name From:author

6.Supported States and Properties§

6.1Clarification of States versus Properties§

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.

6.2Characteristics of States and Properties§

States and properties have the characteristics described in the following sections.

6.2.1Related Concepts§

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.

6.2.2Used in Roles§

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.

6.2.3Inherits into Roles§

Advisory information aboutroles that inherit thestate orproperty from an ancestor role.

6.2.4Value§

Value type of thestate orproperty. The value may be one of the following types:

true/false
Value representing either true or false. The default value for this value type isfalse unless otherwise specified.
tristate
Value representing true or false, with an intermediate "mixed" value. The default value for this value type isfalse unless otherwise specified.
true/false/undefined
Value representing true, false, or not applicable. For example, an element witharia-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.
ID reference
Reference to the ID of anotherelement in the same document
ID reference list
A list of one or more ID references.
integer
A numerical value without a fractional component.
number
Any real numerical value.
string
Unconstrained value type.
token
One of a limited set of allowed values. An explicit value ofundefined for this type is the equivalent of providing no value.
token list
A list of one or more tokens.
URI
A Uniform Resource Identifier as defined byRFC 3986 [RFC3986]. It may reference a separate document, or a content fragment identifier in a separate document, or a content fragment identifier within the same document.

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.

6.3Values for States and Properties§

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.

6.4Global States and Properties§

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.

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.

6.5Taxonomy ofWAI-ARIA States and Properties§

States and properties are categorized as follows:

  1. Widget Attributes
  2. Live Region Attributes
  3. Drag-and-Drop Attributes
  4. Relationship Attributes

6.5.1Widget Attributes§

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.

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.

6.5.2Live Region Attributes§

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.

6.5.3Drag-and-Drop Attributes§

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.

6.5.4Relationship Attributes§

This section listsattributes that indicaterelationships or associations betweenelements which cannot be readily determined from the document structure.

6.6Definitions of States and Properties (all aria-* attributes)§

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.

aria-activedescendant
Identifies the currently active element whenDOM focus is on acomposite widget,textbox,group, orapplication.
aria-atomic
Indicates whetherassistive technologies will present all, or only parts of, the changed region based on the change notifications defined by thearia-relevant attribute.
aria-autocomplete
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.
aria-busy
Indicates an element is being modified and that assistive technologiesMAY want to wait until the modifications are complete before exposing them to the user.
aria-checked
Indicates the current "checked"state of checkboxes, radio buttons, and otherwidgets. See relatedaria-pressed andaria-selected.
aria-colcount
Defines the total number of columns in atable,grid, ortreegrid. See relatedaria-colindex.
aria-colindex
Defines anelement's column index or position with respect to the total number of columns within atable,grid, ortreegrid. See relatedaria-colcount andaria-colspan.
aria-colspan
Defines the number of columns spanned by a cell or gridcell within atable,grid, ortreegrid. See relatedaria-colindex andaria-rowspan.
aria-controls
Identifies theelement (or elements) whose contents or presence are controlled by the current element. See relatedaria-owns.
aria-current
Indicates theelement that represents the current item within a container or set of related elements.
aria-describedby
Identifies theelement (or elements) that describes theobject. See relatedaria-labelledby.
aria-details
Identifies theelement that provides a detailed, extended description for theobject. See relatedaria-describedby.
aria-disabled
Indicates that theelement isperceivable but disabled, so it is not editable or otherwiseoperable. See relatedaria-hidden andaria-readonly.
aria-dropeffect
[Deprecated in ARIA 1.1] Indicates what functions can be performed when a dragged object is released on the drop target.
aria-errormessage
Identifies theelement that provides an error message for theobject. See relatedaria-invalid andaria-describedby.
aria-expanded
Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-flowto
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.
aria-grabbed
[Deprecated in ARIA 1.1] Indicates an element's "grabbed"state in a drag-and-drop operation.
aria-haspopup
Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by anelement.
aria-hidden
Indicates whether theelement is exposed to an accessibilityAPI. See relatedaria-disabled.
aria-invalid
Indicates the entered value does not conform to the format expected by the application. See relatedaria-errormessage.
aria-keyshortcuts
Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.
aria-label
Defines a string value that labels the current element. See relatedaria-labelledby.
aria-labelledby
Identifies theelement (or elements) that labels the current element. See relatedaria-describedby.
aria-level
Defines the hierarchical level of anelement within a structure.
aria-live
Indicates that anelement will be updated, and describes the types of updates theuser agents,assistive technologies, and user can expect from thelive region.
aria-modal
Indicates whether anelement is modal when displayed.
aria-multiline
Indicates whether a text box accepts multiple lines of input or only a single line.
aria-multiselectable
Indicates that the user may select more than one item from the current selectable descendants.
aria-orientation
Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
aria-owns
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.
aria-placeholder
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.
aria-posinset
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.
aria-pressed
Indicates the current "pressed"state of toggle buttons. See relatedaria-checked andaria-selected.
aria-readonly
Indicates that theelement is not editable, but is otherwiseoperable. See relatedaria-disabled.
aria-relevant
Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. See relatedaria-atomic.
aria-required
Indicates that user input is required on theelement before a form may be submitted.
aria-roledescription
Defines a human-readable, author-localized description for therole of anelement.
aria-rowcount
Defines the total number of rows in atable,grid, ortreegrid. See relatedaria-rowindex.
aria-rowindex
Defines anelement's row index or position with respect to the total number of rows within atable,grid, ortreegrid. See relatedaria-rowcount andaria-rowspan.
aria-rowspan
Defines the number of rows spanned by a cell or gridcell within atable,grid, ortreegrid. See relatedaria-rowindex andaria-colspan.
aria-selected
Indicates the current "selected"state of variouswidgets. See relatedaria-checked andaria-pressed.
aria-setsize
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.
aria-sort
Indicates if items in a table or grid are sorted in ascending or descending order.
aria-valuemax
Defines the maximum allowed value for a rangewidget.
aria-valuemin
Defines the minimum allowed value for a rangewidget.
aria-valuenow
Defines the current value for a rangewidget. See relatedaria-valuetext.
aria-valuetext
Defines the human readable text alternative ofaria-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:

  1. The value ofaria-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.
  2. The element withDOM focus is atextbox 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.

Characteristics:
CharacteristicValue
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.

  1. If none of the ancestors have explicitly setaria-atomic, the default is thataria-atomic isfalse, and assistive technologies will only present the changed node to the user.
  2. Ifaria-atomic is explicitly set tofalse, assistive technologies will stop searching up the ancestor chain and present only the changed node to the user.
  3. Ifaria-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.

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values:
ValueDescription
false (default)Assistive technologies will present only the changed node or nodes.
trueAssistive 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:

  1. The element has a value specified foraria-controls that refers to the element that contains the collection of suggested values.
  2. Either the element or a containing element with rolecombobox 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:

  1. The collection of suggestions is presented in an element with a role that supportsaria-activedescendant.
  2. The value ofaria-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.
  3. DOM focus remains on the text input while the suggestions are displayed.

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.

Characteristics:
CharacteristicValue
Related Concepts:XForms selection attribute inselect
Used in Roles:
Inherits into Roles:
Value:token
Values:
ValueDescription
inlineWhen a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret.
listWhen a user is providing input, an element containing a collection of values that could complete the provided input may be displayed.
bothWhen 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.

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values:
ValueDescription
false (default):There are no expected updates for the element.
trueThe element is being updated.

aria-checked(state)§

Indicates the current "checked"state of checkboxes, radio buttons, and otherwidgets. See relatedaria-pressed andaria-selected.

Thearia-checkedattribute 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]

Characteristics:
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:tristate
Values:
ValueDescription
falseThe element supports being checked but is not currently checked.
mixedIndicates a mixed mode value for a tri-state checkbox or menuitemcheckbox.
trueThe 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.

Example 13
<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>
Characteristics:
CharacteristicValue
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.

Example 14
<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.

Example 15
<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.

Example 16
<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>
Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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:

  • A table of contents tree view may control the content of a neighboring document pane.
  • A group of checkboxes may control what commodity prices are tracked live in a table or graph.
  • A tab controls the display of its associated tab panel.
Characteristics:
CharacteristicValue
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-currentattribute 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-currentstateMUST 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:

  • Apage token used to indicate a link within a set of pagination links, where the link is visually styled to represent the currently-displayed page.
  • Astep 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.
  • Alocation token used to indicate the image that is visually highlighted as the current component of a flow chart.
  • Adate token used to indicate the current date within a calendar.
  • Atime 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.

Note

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

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token
Values:
ValueDescription
pageRepresents the current page within a set of pages.
stepRepresents the current step within a process.
locationRepresents the current location within an environment or context.
dateRepresents the current date within a collection of dates.
timeRepresents the current time within a set of times.
trueRepresents 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.

Characteristics:
CharacteristicValue
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>
Characteristics:
CharacteristicValue
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-disabledattribute is applied.

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false
Values:
ValueDescription
false (default)The element is enabled.
trueThe 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.

Note

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.

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token list
Values:
ValueDescription
copyA duplicate of the source object will be dropped into the target.
executeA function supported by the drop target is executed, using the drag source as an input.
linkA reference or shortcut to the dragged object will be created in the target object.
moveThe 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.
popupThere 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:

Example 19
<!-- 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>
Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Related Concepts:Tapered prompts in voice browsing. Switch inSMIL [SMIL3].
Used in Roles:
Inherits into Roles:
Value:true/false/undefined
Values:
ValueDescription
falseThe element, or another grouping element it controls, is collapsed.
trueThe 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-flowtoattribute.AccessibilityAPIs can provide named pathrelationships.

Characteristics:
CharacteristicValue
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.

Note

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

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false/undefined
Values:
ValueDescription
falseIndicates that the element supports being dragged.
trueIndicates 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.

Note

Atooltip is not considered to be a popup in this context.

Characteristics:
CharacteristicValue
Related Concepts:
Used in Roles:All elements of the base markup
Value:token
Values:
ValueDescription
false (default)Indicates the element does not have a popup.
trueIndicates the popup is amenu.
menuIndicates the popup is amenu.
listboxIndicates the popup is alistbox.
treeIndicates the popup is atree.
gridIndicates the popup is agrid.
dialogIndicates 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.

Example 20
[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.

Note

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,aria-hidden="false" is known to work inconsistently in browsers. As future implementations improve, use caution and test thoroughly before relying on this approach.

Note

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; }
Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:true/false/undefined
Values:
ValueDescription
falseThe element is exposed to the accessibilityAPI as if it was rendered.
trueThe 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.

Characteristics:
CharacteristicValue
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
Values:
ValueDescription
grammarA grammatical error was detected.
false (default)There are no detected errors in the value.
spellingA spelling error was detected.
trueThe 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+&#39;" 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].

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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.

Note

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.

Characteristics:
CharacteristicValue
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-levelattribute.

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.

Note

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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token
Values:
ValueDescription
assertiveIndicates 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.
politeIndicates 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-modalattribute 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.

Characteristics:
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:true/false
Values:
ValueDescription
false (default)Element is not modal.
trueElement is modal.

aria-multiline(property)§

Indicates whether a text box accepts multiple lines of input or only a single line.

Note

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.

Characteristics:
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:true/false
Values:
ValueDescription
false (default)This is a single-line text box.
trueThis 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-selectedattribute set totrue, and selectable descendant have thearia-selected attribute set tofalse. AuthorsSHOULD NOT use thearia-selected attribute on descendants that are not selectable.

Note

Lists and trees are examples of roles that might allow users to select more than one item at a time.

Characteristics:
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:true/false
Values:
ValueDescription
false (default)Only one item can be selected.
trueMore 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.

Note

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

Characteristics:
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:token
Values:
ValueDescription
horizontalThe element is oriented horizontally.
undefined (default)The element's orientation is unknown/ambiguous.
verticalThe 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-ownsattribute 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.

Characteristics:
CharacteristicValue
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.

Note

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:

Example 22
<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:

Example 23
<spanid="label">Birthday:</span><divcontenteditablerole="searchbox"aria-labelledby="label"aria-placeholder="MM-DD-YYYY">MM-DD-YYYY</div>
Characteristics:
CharacteristicValue
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.

Example 24
<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.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Used in Roles:
Value:tristate
Values:
ValueDescription
falseThe element supports being pressed but is not currently pressed.
mixedIndicates a mixed mode value for a tri-state toggle button.
trueThe 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:

  • A form element which represents a constant.
  • Row or column headers in a spreadsheet grid.
  • The result of a calculation such as a shopping cart total.
Characteristics:
CharacteristicValue
Related Concepts:XForms [XFORMS10] Readonly
Used in Roles:
Inherits into Roles:
Value:true/false
Values:
ValueDescription
false (default)The user can set the value of the element.
trueThe 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.

Note

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.

Note

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.

Characteristics:
CharacteristicValue
Used in Roles:All elements of the base markup
Value:token list
Values:
ValueDescription
additionsElement nodes are added to the accessibility tree within the live region.
additions textEquivalent to the combination of values, "additions text".
allEquivalent to the combination of all values, "additions removals text".
removalsText content, a text alternative, or an element node within the live region is removed from the accessibility tree.
textText 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.

Note

The fact that the element is required is often presented visually (such as a sign or symbol after thewidget). Using thearia-requiredattribute 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.

Characteristics:
CharacteristicValue
Related Concepts:HTMLrequired
Used in Roles:
Inherits into Roles:
Value:true/false
Values:
ValueDescription
false (default)User input is not necessary to submit the form.
trueUsers 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:

  1. The element to whicharia-roledescription is applied has a validWAI-ARIA role or has an implicitWAI-ARIA role semantic.
  2. The value ofaria-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:

  1. The element to whicharia-roledescription is applied does not have a validWAI-ARIA role or does not have an implicitWAI-ARIA role semantic.
  2. The value of aria-roledescription is empty or contains only whitespace characters.

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

Example 25
<divrole="region"aria-roledescription="slide"id="slide42"aria-labelledby="slide42heading"><h1id="slide42heading">Quarterly Report</h1><!-- remaining slide contents --></div>
Example 26
<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."

Example 27
<divrole="button"tabindex="0"aria-roledescription="attachment button">family_reunion.jpg</div>
Example 28
<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.

Characteristics:
CharacteristicValue
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.

Example 29
<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>
Characteristics:
CharacteristicValue
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.

Example 30
<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.

Example 31
<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>
Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
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:

  1. Single-selection containers where the currently focused item is not selected. The selection normally follows the focus, and is managed by theuser agent.
  2. Multiple-selection containers. AuthorsSHOULD ensure that any selectable descendant of a container in which thearia-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.

Characteristics:
CharacteristicValue
Used in Roles:
Inherits into Roles:
Value:true/false/undefined
Values:
ValueDescription
falseThe selectable element is not selected.
trueThe 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-posinsetattribute 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.

Example 32
<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.

Example 33
<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>
Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Used in Roles:
Value:token
Values:
ValueDescription
ascendingItems are sorted in ascending order by this column.
descendingItems are sorted in descending order by this column.
none (default)There is no defined sort applied to the column.
otherA 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.

Note

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.

Characteristics:
CharacteristicValue
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.

Note

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.

Characteristics:
CharacteristicValue
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-valuenowattribute. 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.

Note

Ifaria-valuetext is specified, assistive technologies render that instead of the value ofaria-valuenow.

Characteristics:
CharacteristicValue
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.

Characteristics:
CharacteristicValue
Related Concepts:XForms [XFORMS10] range, start
Used in Roles:
Inherits into Roles:
Value:string

7.Implementation in Host Languages§

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.

7.1Role Attribute§

An implementing host language will provide anattribute with the following characteristics:

7.2State and Property Attributes§

An implementing host languageMUST allowattributes with the following characteristics:

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

Note

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.

Note

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.

7.3Focus Navigation§

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. Thetabindexattribute inHTML 5 is an example of one implementation.

7.4ImplicitWAI-ARIA Semantics§

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

7.5Conflicts with Host Language Semantics§

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:

7.6State and Property Attribute Processing§

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.

A.Schemata§

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.

A.1Roles Implementation§

The taxonomy forWAI-ARIA expressed inRDF is available fromhttp://www.w3.org/WAI/ARIA/schemata/aria-1.rdf.

A.2WAI-ARIA Attributes Module§

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.

A.3XHTML plusWAI-ARIADTD§

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., &copy;). 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.

A.4SGML Open Catalog Entry forXHTML+ARIA§

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

A.5WAI-ARIA AttributesXML Schema Module§

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.

A.6HTML 4.01 plus WAI-ARIA DTD§

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., &copy;). 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.

B.MappingWAI-ARIA Value types to languages§

This section is non-normative.

Note

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

Note

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 typeHTML 5XML Schema
true/falseKeyword and enumerated attributes with allowed values of "true" and "false"boolean
true/false/undefinedKeyword and enumerated attributes with allowed values oftrue,false, andundefinedNMTOKEN with anenumeration constraint allowing values oftrue,false, andundefined
tristateKeyword and enumerated attributes with allowed values of "true", "false", and "mixed"NMTOKEN with anenumeration constraint allowing values of "true", "false", and "mixed"
numberFloating-point numbersdecimal
integerNon-negative integerinteger
tokenKeyword and enumerated attributesNMTOKEN with anenumeration constraint allowing values listed in the state or property definition
token listSpace-separated tokensNMTOKENS with anenumeration constraintallowing values listed in the state or property definition
ID referenceThe value of a definedid attribute on another elementIDREF
ID reference listThe value of one or more definedid attributes on other element(s), represented asSpace-separated tokensIDREFS
stringNo value constraintsstring

C.Change Log: substantive changes since theWAI-ARIA 1.0 Recommendation§

D.Acknowledgments§

This section is non-normative.

The following people contributed to the development of this document.

D.1Participants active in the ARIA WG at the time of publication§

D.2Other ARIA contributors, commenters, and previously active participants§

D.3Enabling funders§

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

E.References§

E.1Normative references§

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:https://tools.ietf.org/html/rfc2119
[uievents-key]
UI Events KeyboardEvent key Values. Gary Kacmarcik; Travis Leithead. W3C. 1 June 2017. W3C Candidate Recommendation. URL:https://www.w3.org/TR/uievents-key/

E.2Informative references§

[accname-aam-1.1]
Accessible Name and Description: Computation and API Mappings 1.1. Joseph Scheuhammer; James Craig; Andi Snow-Weaver; Aaron Leventhal. W3C. 17 March 2016. W3C Working Draft. URL:https://www.w3.org/TR/accname-aam-1.1/
[AT-SPI]
Assistive Technology Service Provider Interface. The GNOME Project. URL:https://developer.gnome.org/libatspi/stable/
[ATK]
ATK - Accessibility Toolkit. The GNOME Project. URL:https://developer.gnome.org/atk/stable/
[AXAPI]
The NSAccessibility Protocol for macOS. Apple, Inc. URL:https://developer.apple.com/documentation/appkit/nsaccessibility
[core-aam-1.1]
Core Accessibility API Mappings 1.1. Joanmarie Diggs; Joseph Scheuhammer; Richard Schwerdtfeger; Michael Cooper; Andi Snow-Weaver; Aaron Leventhal. W3C. 14 December 2017. W3C Recommendation. URL:https://www.w3.org/TR/core-aam-1.1/
[css3-selectors]
Selectors Level 3. Tantek Çelik; Elika Etemad; Daniel Glazman; Ian Hickson; Peter Linss; John Williams et al. W3C. 29 September 2011. W3C Recommendation. URL:https://www.w3.org/TR/css3-selectors/
[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL:https://dom.spec.whatwg.org/
[html5]
HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 28 October 2014. W3C Recommendation. URL:https://www.w3.org/TR/html5/
[html51]
HTML 5.1 2nd Edition. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo. W3C. 3 October 2017. W3C Recommendation. URL:https://www.w3.org/TR/html51/
[IAccessible2]
IAccessible2. Linux Foundation. URL:https://www.linuxfoundation.org/collaborate/workgroups/accessibility/iaccessible2
[MathML3]
Mathematical Markup Language (MathML) Version 3.0 2nd Edition. David Carlisle; Patrick D F Ion; Robert R Miner. W3C. 10 April 2014. W3C Recommendation. URL:https://www.w3.org/TR/MathML3/
[MSAA]
Microsoft Active Accessibility (MSAA) 2.0. Microsoft Corporation. URL:https://msdn.microsoft.com/en-us/library/ms697707.aspx
[owl-features]
OWL Web Ontology Language Overview. Deborah McGuinness; Frank van Harmelen. W3C. 10 February 2004. W3C Recommendation. URL:https://www.w3.org/TR/owl-features/
[rdf-concepts]
Resource Description Framework (RDF): Concepts and Abstract Syntax. Graham Klyne; Jeremy Carroll. W3C. 10 February 2004. W3C Recommendation. URL:https://www.w3.org/TR/rdf-concepts/
[rdf-schema]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL:https://www.w3.org/TR/rdf-schema/
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL:https://tools.ietf.org/html/rfc3986
[role-attribute]
Role Attribute 1.0. Shane McCarron et al. W3C. 28 March 2013. W3C Recommendation. URL:https://www.w3.org/TR/role-attribute/
[SGML-CATALOG]
Entity Management: OASIS Technical Resolution 9401:1997 (Amendment 2 to TR 9401). Paul Grosso. Entity Management Subcommittee, SGML Open. 10 September 2007. URL:https://www.oasis-open.org/specs/tr9401.html
[SMIL3]
Synchronized Multimedia Integration Language (SMIL 3.0). Dick Bulterman. W3C. 1 December 2008. W3C Recommendation. URL:https://www.w3.org/TR/SMIL3/
[SVG2]
Scalable Vector Graphics (SVG) 2. Nikos Andronikos; Rossen Atanassov; Tavmjong Bah; Amelia Bellamy-Royds; Brian Birtles; Cyril Concolato; Erik Dahlström; Chris Lilley; Cameron McCormack; Doug Schepers; Dirk Schulze; Richard Schwerdtfeger; Satoru Takagi; Jonathan Watt et al. W3C. W3C Working Draft. URL:http://www.w3.org/TR/2015/WD-SVG2-20150915/
[UAAG10]
User Agent Accessibility Guidelines 1.0. Ian Jacobs; Jon Gunderson; Eric Hansen. W3C. 17 December 2002. W3C Recommendation. URL:https://www.w3.org/TR/UAAG10/
[UI-AUTOMATION]
UI Automation. Microsoft Corporation. URL:https://msdn.microsoft.com/en-us/library/ee684009%28v=vs.85%29.aspx
[UIA-EXPRESS]
The IAccessibleEx Interface. Microsoft Corporation. URL:https://msdn.microsoft.com/en-us/library/windows/desktop/dd561898%28v=vs.85%29.aspx
[wai-aria-1.0]
Accessible Rich Internet Applications (WAI-ARIA) 1.0. James Craig; Michael Cooper et al. W3C. 20 March 2014. W3C Recommendation. URL:https://www.w3.org/TR/wai-aria/
[wai-aria-practices-1.1]
WAI-ARIA Authoring Practices 1.1. Matthew King; James Nurthen; Zoë Bijl; Michael Cooper; Joseph Scheuhammer; Lisa Pappas; Richard Schwerdtfeger. W3C. 14 December 2017. W3C Note. URL:https://www.w3.org/TR/wai-aria-practices-1.1/
[WCAG20]
Web Content Accessibility Guidelines (WCAG) 2.0. Ben Caldwell; Michael Cooper; Loretta Guarino Reid; Gregg Vanderheiden et al. W3C. 11 December 2008. W3C Recommendation. URL:https://www.w3.org/TR/WCAG20/
[XFORMS10]
XForms 1.0 (Third Edition). John Boyer. W3C. 29 October 2007. W3C Recommendation. URL:https://www.w3.org/TR/xforms/
[XFORMS11]
XForms 1.1. John Boyer. W3C. 20 October 2009. W3C Recommendation. URL:https://www.w3.org/TR/xforms11/
[xhtml11]
XHTML™ 1.1 - Module-based XHTML - Second Edition. Shane McCarron; Masayasu Ishikawa. W3C. 23 November 2010. W3C Recommendation. URL:https://www.w3.org/TR/xhtml11/
[xml-names]
Namespaces in XML 1.0 (Third Edition). Tim Bray; Dave Hollander; Andrew Layman; Richard Tobin; Henry Thompson et al. W3C. 8 December 2009. W3C Recommendation. URL:https://www.w3.org/TR/xml-names/
[xml11]
Extensible Markup Language (XML) 1.1 (Second Edition). Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau; John Cowan et al. W3C. 16 August 2006. W3C Recommendation. URL:https://www.w3.org/TR/xml11/
[xmlschema-2]
XML Schema Part 2: Datatypes Second Edition. Paul V. Biron; Ashok Malhotra. W3C. 28 October 2004. W3C Recommendation. URL:https://www.w3.org/TR/xmlschema-2/


[8]ページ先頭

©2009-2025 Movatter.jp