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 current
W3C publications and the latest revision of this technical report can be
found in the W3C technical reports index at http://www.w3.org/TR/.
This document is a Last Call Working Draft by the Protocols & Formats Working
Group of the Web
Accessibility Initiative. This version includes minor changes to the WAI-ARIA taxonomy since the previous version.
In order to make user agent response to WAI-ARIA clear, this document is supported by the new companion document, WAI-ARIA User Agent Implementation Guide [ARIA-IMPLEMENTATION], and some content has been moved into this document. The authoring guide, WAI-ARIA Best Practices [ARIA-PRACTICES], has also been updated. Refer to the history of changes to WAI-ARIA for details.
Feedback on the model set out here is important to the success of the Web community in creating accessible Rich Internet Applications. The PFWG would like to know:
- Does the role ontology provide the information and operations that people with disabilities need in order to access and operate richly interactive Web applications?
- Is the usage of roles, states, and properties clear?
- Is it clear how to create Rich Internet Applications with this added capability?
- Are conformance requirements clear, and sufficient but not excessive?
When addressing these questions, please consider them in the context of the companion documents. Comments on this document may be sent to public-pfwg-comments@w3.org (Archive). Comments requiring discussion should be copied to wai-xtech@w3.org (Archive). Comments should be made by 24 March 2009. In-progress updates to the document may be viewed in the publicly visible editors' draft.
Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group operating under the 5 February 2004
W3C Patent Policy. W3C maintains a public list of any
patent disclosures made in connection with the deliverables of the group;
that page also includes instructions for disclosing a patent. An individual
who has actual knowledge of a patent which the individual believes contains Essential
Claim(s) must disclose the information in accordance with section
6 of the W3C Patent Policy.
The disclosure obligations of the Participants of this group are described
in the charter.
1. Introduction
This section is informative.
The domain of web accessibility defines how to make web content usable by persons with disabilities. Persons with certain types of disabilities use assistive technology (AT) to interact with content. Assistive technology software can transform the presentation into a format more suitable to the user, and can allow the user to interact in different ways than the author designed. In order to accomplish this effectively, the software must understand the semantics of the content. "Semantics" is the knowledge of roles, states, and properties that apply to content elements as a person would understand them. For instance, if a paragraph is semantically identified as such, assistive technology can interact with it as a unit separable from the rest of the content, knowing the exact boundaries of that paragraph. A range slider or collapsible tree widget are more complex examples, in which various parts of the widget have semantics that must be properly identified for the assistive technology to support effective interaction.
New technologies often overlook the 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 in HTML using CSS and JavaScript even though HTML lacks an appropriate semantic 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 be perceivable to or operable by a person with a disability because the assistive technology does not recognize it as such.
The incorporation of WAI-ARIA is a way for an author to provide proper semantics for custom widgets to make these widgets accessible, usable, and interoperable with assistive technology. This specification identifies the types of widgets and structures that are commonly recognized by accessibility products, by providing an ontology of corresponding roles 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 semantic inherited from the implementing technology. Roles are a common property of platform accessibility APIs which assistive technology uses to provide the user with effective presentation and interaction.
This role taxonomy includes interaction widgets and elements denoting document structure. The role taxonomy describes inheritance and details what additional attributes each role supports. Information about mapping of roles to accessibility APIs is provided by the WAI-ARIA User Agent Implementation Guide [ARIA-IMPLEMENTATION].
Roles are element types and should not change with time or user actions. Changing the role on an element from its initial value will likely be treated by accessibility API events as the removal of the old element and insertion of a new element with the new role.
States and properties are used to declare important attributes of an element that affect and describe interaction. They enable the user agent or 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, speech dictation software, and on-screen keyboards must be able to recognize and effectively communicate various states (disabled, checked, etc.) to the user.
While it is possible for assistive technology to access these properties directly through the Document Object Model [DOM], the preferred mechanism is for the user agent to map the states and properties to the accessibility API of the operating system. See the WAI-ARIA User Agent Implementation Guide. [ARIA-IMPLEMENTATION]
Figure 1.0 illustrates a typical Document Object Model (DOM) [DOM] node. Placed within the DOM node and the assistive technology is a box containing the "contract" provided by the user agent to the assistive technology. This data includes typical accessibility information found in the accessibility API for many of our accessible platforms for GUIs (role, state, selection, event notification, relationship information, and descriptions).
Figure 1: The contract model with accessibility APIs
For more information see the WAI-ARIA Primer [ARIA-PRIMER] for the use of roles in making interactive content accessible.
In addition to the prose documentation, the role taxonomy is provided in Web Ontology Language (OWL) [OWL], which is an implementation of Resource Description Framework (RDF) [RDF]. 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 specific state or property that another role does not support.
Note: The use of RDF/OWL as a formal representation of roles may be used to support future extensibility. Standard RDF/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. A future version of ARIA is expected to define how to extend roles.
1.1. Scope
The goals of this specification include:
- defining what information may be controlled by the author;
- supporting device independence for new devices such as telephones, PDAs, and televisions;
- improving the accessibility of dynamic content generated by scripts; and
- providing for interoperability with assistive technology.
This draft currently handles two aspects of roles: user interface functionality and structural relationships. For more information, see the WAI-ARIA Primer [ARIA-PRIMER] for the use of roles in making interactive content accessible.
The role taxonomy is designed in part to support the common roles found in platform accessibility APIs. Reference to roles found in this taxonomy by dynamic web content may be used to support interoperability with assistive technology.
The schema to support this standard has been designed to be extensible so that custom roles can be created by extending base roles. This allows user 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 XML Schema [XSD]. However, being able to define similarities between roles, such as baseConcepts and more descriptive definitions, would not be available in XSD. While this extensibility is possible, this version of the specification does not define how this extension is to be achieved.
WAI-ARIA is supported by a set of informative resources. In addition to the WAI-ARIA Roadmap [ARIA-ROADMAP], the WAI-ARIA Primer [ARIA-PRIMER] provides a basic introduction to the concepts behind and reason for ARIA, and the WAI-ARIA Best Practices [ARIA-PRACTICES] describe recommended usage patterns for web content developers. The WAI-ARIA User Agent Implementation Guide [ARIA-IMPLEMENTATION] describes how user agents should expose ARIA features to platform accessibility APIs. These documents are intended to help authors learn the practice of putting WAI-ARIA to use.
1.2. Use Cases
Keyboard accessible content helps users of alternate input devices. The new semantics, when combined with the recommended keyboard interactions provided in WAI-ARIA Best Practices [ARIA-PRACTICES], work will allow alternate input solutions to facilitate command and control via an alternate input solution.
ARIA introduces navigation landmarks through its taxonomy and the XHTML role landmarks, which helps persons with dexterity and vision impairments by providing for improved keyboard navigation. 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 technology needs the ability to support alternative inputs by getting and setting the current value of widgets. Assistive technology also needs to determine what objects are selected and manage widgets that allow multiple selections, such as list boxes and grids.
ARIA is intended to be used as a supplement for native language semantics, not a replacement. When the host language provides a feature that is equivalent to the ARIA feature, use the host language feature. ARIA should only be used in cases where the host language lacks the needed role, state, or property indicator. First use a host language feature that is as similar as possible to the ARIA feature, then refine the meaning by adding ARIA. For instance, a multi-selectable grid could be implemented as a table, and then ARIA used to clarify that it is a grid, not just a table. This allows for the best possible fallback for user agents that do not support ARIA and preserves the integrity of the host language semantics.
2. Using WAI-ARIA
This section is informative.
Complex web applications become inaccessible when assistive technology cannot determine the semantics behind portions of a document or when the user is unable to effectively navigate to all parts of it in a usable way (see the WAI-ARIA Primer [ARIA-PRIMER]). ARIA divides the semantics into roles (the type defining a user interface element) and states and properties supported by the roles.
Authors must associate elements in the document to an ARIA role and the appropriate states and properties (aria-* attributes) during its life-cycle.
2.1. WAI-ARIA Roles
An ARIA role is set on an element using a role
attribute, similar to the role
attribute defined in the XHTML Role Attribute Module [XHTML-ROLES].
<li role="menuitem">Open file…</li>
The roles defined in this specification include a collection of document landmarks and the ARIA role taxonomy.
The roles in this taxonomy were modeled using RDF/OWL [OWL] to document expected behaviors of each role. Features of the role taxonomy provide the following information for each role:
- an informative description of the role;
- hierarchical information about related roles (e.g., a
directory
is a type of list
); - context of the role (e.g., a
listitem
should be inside a list
); - references to related concepts in other specifications;
- use of OWL to provide a type hierarchy allowing for semantic inheritance (similar to a class hierarchy); and
- supported states and properties for each role (e.g., a
checkbox
supports being checked via the aria-checked
attribute).
Attaching a role gives assistive technology information about how to handle each element.
2.2. WAI-ARIA States and Properties
ARIA provides a collection of accessibility states and properties which are used to support platform accessibility APIs on the various operating system platforms. Assistive technology may access this information through an exposed user agent DOM or through a mapping to the platform accessibility API. When combined with roles, the user agent can supply the assistive technology with information to render the information to the user at any instance in time. Changes in states or properties will result in a notification to the assistive technology, which may 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 JavaScript events will capture mouse and keyboard events to toggle value of aria-checked
. A role is used to make the behavior of this simple widget known to the user agent. attributes that change with user actions (such as aria-checked
) are defined in the states and properties section.
<li role="menuitemcheckbox" aria-checked="true">Sort by Last Modified</li>
Some accessibility states, called managed states, are controlled by the user agent. Examples of managed state include keyboard focus and selection. Managed states often have corresponding CSS 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 called unmanaged states. Some states managed by the user agent, such as aria-posinset
and aria-setsize
, can be overridden by web application authors, but the author should only override them if the DOM is incomplete and would cause the user agent calculation to be incorrect. User agents map both managed and unmanaged states to the platform accessibility APIs.
Most modern user agents support CSS attribute selectors ([CSS], Section 5.8), and can allow the author to create UI changes based on ARIA attribute information, reducing the amount of scripts necessary to achieve equivalent functionality. In the following example, a CSS selector is used to determine whether or not an image of a check mark is shown, based on the value of the aria-checked
attribute.
[aria-checked="true"]:before { background-image: url(checked.gif); }
Note: At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise to force the browser to redraw the styles properly.
2.3. Managing Focus
An application
should always have an element with focus when in use, as applications require users to have a place to provide user input. The element with focus should not be destroyed, hidden, or scrolled off screen. All interactive elements should be focusable. There should be an obvious, discoverable way, either through tabbing or other standard navigation techniques, for keyboard users to move the focus to any interactive element. See User Agent Accessibility Guidelines, Guideline 9 ([UAAG], Guideline 9).
When using standard (X)HTML and basic WAI-ARIA widgets, 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.
WAI-ARIA includes a number of "managing container" widgets, also known as "composite" widgets. Typically, the container is responsible for tracking the last descendant which was active (the default is usually the first item in the container). When a previously focused container is refocused, the new active descendant should be the same element as the active descendant when the container was last focused. 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 something in the container has focus, the user may navigate through the container by pressing additional keys such as the arrow keys to move relative to the current item. Any additional press of the main navigation key (generally the Tab key) will move out of the container to the next widget.
For example, a grid
may be used as a spreadsheet with thousands of gridcell
elements, all of which may not be present in the document at one time. This requires their focus to be managed by the container using the aria-activedescendant
attribute, on the managing container element, or by the container managing the tabindex
of its child elements and setting focus on the appropriate child. For more information, see Providing Keyboard Focus in WAI-ARIA Best Practices ([ARIA-PRACTICES], section 3.2).
Containers that manage focus in this way are:
More information on managing focus can be found in the Using Tabindex to Manage Focus Among Widgets section of the WAI-ARIA Best Practices [ARIA-PRACTICES].
2.4. Building Accessible Applications with WAI-ARIA
This section provides a brief introduction to the process of making applications accessible using ARIA. The choice and usage of roles can be complex and context dependent. It is beyond the scope of this document to explain implementations for all the possible ARIA use cases. ARIA Best Practices [ARIA-PRACTICES] provides detailed guidance on ARIA implementation methodology as well as references to sample code.
First steps to making an application accessible:
- Each element or widget has correct and complete semantics that fully describe its behavior (using element names or roles);
- The relationships between elements and groups are defined;
- States, properties, and container relationships are valid for each element's behavior and are accessible via the Document Object Model [DOM] and the platform accessibility API; and
- Keyboard focus should be maintained for the duration of the user's interaction with the application.
- All interactive components should be keyboard operable.
ARIA provides authors with the means to make the different elements in a web application semantically rich. User agents use the role semantics to understand how to handle each element. Roles convey additional information that the assistive technology needs to anticipate the behavior of the elements inside the application such as how to present the corresponding ARIA states and properties to the user. The user agent will use the accessibility semantics from the host language and ARIA accessibility semantics (which may augment or override those of the host language) and present them to an assistive technology through the Document Object Model or the platform accessibility API. The user agent will create an accessible representation of each element in the web page, and will use the appropriate accessibility API to notify assistive technology of changes to the semantics of those elements.
The following steps are recommended as ARIA is applied to content:
-
Use native markup when possible.
Use the semantic elements that are defined in the host markup language. For example, with HTML or XHTML, it is better to use the native checkbox than to use a div element with role checkbox
as these should already be accessible through your browser. There may also be cases where ARIA can augment an existing element in the host language. For example, a grid
and gridcell
elements can reuse the functionality of a table when overlaying it. ARIA roles, states, and properties are best used when the markup language does not support all the semantics required. When a role attribute is added to an element, the semantics and behavior of the element are augmented or overridden by the role behavior.
-
Apply the appropriate roles.
Set roles to make sure elements behave predictably and correctly describe the behavior of each element within the application, unless element behaviors are fully described by the native markup language. Roles for interactive elements should support all the attributes that the element could use. Once a role attribute is set it should not be changed as this may confuse the end user. This does not preclude an element being removed which has the role attribute set, but only states and properties (aria-* attributes) should be changed for a given element.
-
Preserve semantic structure.
Structural information is critical to providing context to persons with disabilities. Preserve DOM hierarchy within structural elements and widgets. Form logical groups within user interface widgets, such as treeitem
elements in a group
. Look for groups within a page, and mark them using the most appropriate role that best describes their usage. For example, a region of the page that contains a group of elements that are likely to change through an Ajax application could be specified as a live region, through the use of the aria-live
attribute. Facilitate keyboard navigation through the use of document landmarks; full keyboard access and document semantics help everyone, including vision-impaired users, dexterity-impaired users, and even users with cognitive or learning impairments.
-
Build relationships.
Look for relationships between elements, and mark them using the most appropriate property or attribute. For example, if a page contains both a search form and search results region, mark each container as a region
and set the aria-controls
attribute of the search form to reference the search results. See relationships in WAI-ARIA.
Some relationships are determined automatically from the host language, like label
elements associated with input
elements in HTML.
-
Set states and properties in response to events.
Once the role for an element has been set, change states and properties as appropriate during the element's life cycle, usually in response to user input events. Only use attributes supported for the chosen role or element.
User agents should notify assistive technology of state changes. Conversely, assistive technology notification of property changes depends on the method by which an assistive technology communicates with the user agent. For example, the aria-multiline
attribute (a property) is not something that changes frequently, whereas the aria-checked
attribute (a state) changes frequently in response to user input.
-
Support full, usable keyboard navigation.
Usable keyboard navigation in a rich internet application is different from the tabbing paradigm in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant widgets and uses the arrow keys to navigate within a complex widget, such as a menu or spreadsheet. The changes that ARIA introduces in keyboard navigation make this enhanced accessibility possible. Tabbing in the document should follow a logical navigation structure. Authors implementing arrow key navigation should, where possible, follow the design patterns in the WAI-ARIA Best Practices Guide [ARIA-PRACTICES]. When using these features, it is important as always to ensure keyboard navigation is logical.
-
Synchronize the visual interface with the accessible interface.
This will allow the state of your UI to be perceivable to the user as well as the assistive technology. For example, the author should have an associated selector that responds to a required form element (using aria-required
) or a selected gridcell (using aria-selected
). Authors may choose to achieve visual synchronization of these interface elements by using a script or by the use CSS attribute selectors. Refer to the WAI-ARIA Best Practices [ARIA-PRACTICES] for techniques for proper UI synchronization with the accessible state of the document.
2.5. Example: Building a Tree Widget
A basic tree view allows the user to select different list items and expand and collapse embedded lists. Arrow keys are used to navigate through a tree, including left/right to collapse/expand sub trees. Double clicking with the mouse also toggles expansion.
To make this feature accessible we need to:
- Inform assistive technology about the role of each element;
- Inform assistive technology about the relationships between tree items;
- Give a clear keyboard focus that will not confuse users with disabilities; and
- Expose the changing states (expanded and collapsed) of the the tree items.
Following the steps below:
-
Look at the native markup language
Although standard list behavior is supported by the native ul
and li
elements in HTML, there is no element that natively supports list expansion and selection. Since there is not, we will need to use roles.
-
Finding the right roles
Since there is no native tree element in HTML, we need to add roles from this taxonomy that support the additional states and properties needed. The roles that support tree behavior are:
tree
: A tree is the main container element for our tree. It is a form of a select
where sub-level groups of treeitems may be collapsed and expanded.treeitem
: A treeitem is an option item of a tree. This is an element within a tree; sub-level groups of treeitems may be expanded or collapsed.group
: A group encloses a set of sub-level treeitems.
-
Look for groups and build relationships
Tree relationships can be made simply via the DOM and logical structure of the page. A tree element will be the main container encompassing all other elements in the tree. Each selectable item in the tree will be a treeitem.
When a treeitem contains an embedded list of treeitems they will be all embedded in a group. A group should be contained inside the tree item that is the parent item.
<h1 id="treelabel">ARIA Tree Example</h1>
<ul role="tree" aria-labelledby="treelabel" aria-activedescendant="example_id" tabindex="0">
<li role="treeitem" aria-expanded="true">Animals
<ul role="group">
<li role="treeitem">Birds</li>
<li role="treeitem" aria-expanded="false">Cats
<ul role="group">
<li role="treeitem">Siamese</li>
<li role="treeitem">Tabby</li>
</ul>
</li>
<li role="treeitem" aria-expanded="true">Dogs
<ul role="group">
<li role="treeitem" aria-expanded="true">Small Breeds
<ul role="group">
<li role="treeitem">Chihuahua</li>
<li role="treeitem" id="example_id">Italian Greyhound</li>
<li role="treeitem">Japanese Chin</li>
</ul>
</li>
<li role="treeitem" aria-expanded="false">Medium Breeds
<ul role="group">
<li role="treeitem">Beagle</li>
<li role="treeitem">Cocker Spaniel</li>
<li role="treeitem">Pit Bull</li>
</ul>
</li>
<li role="treeitem" aria-expanded="false">Large Breeds
<ul role="group">
<li role="treeitem">Afghan</li>
<li role="treeitem">Great Dane</li>
<li role="treeitem">Mastiff</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li role="treeitem" aria-expanded="true">Minerals
<ul role="group">
<li role="treeitem">Zinc</li>
<li role="treeitem" aria-expanded="false">Gold
<ul role="group">
<li role="treeitem">Yellow Gold</li>
<li role="treeitem">White Gold</li>
</ul>
</li>
<li role="treeitem">Silver</li>
</ul>
</li>
<li role="treeitem" aria-expanded="true">Vegetables
<ul role="group">
<li role="treeitem">Carrot</li>
<li role="treeitem">Tomato</li>
<li role="treeitem">Lettuce</li>
</ul>
</li>
</ul>
The use of aria-expanded
should mirror that which is visibly expanded on screen, so authors may wish to use CSS attribute selectors to toggle visibility or style of an item based on the value of an ARIA state or property. The following example would hide the sub-level groups of a collapsed tree node.
[aria-expanded="false"] [role="group"] { display: none; }
Note: At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise to force the browser to redraw the styles properly.
Sometimes a tree structure is not explicit via the DOM and logical structure of a page. In such cases the relationships must still be made explicit using the states and properties. In the following example, the aria-owns
attribute indicates that the div
with id "external_listitem" should be considered a child of the ul
element with the property, even though it is not a child in the DOM.
<h3 id="header">Vegetables</h3>
<ul role="list" aria-labelledby="header" aria-owns="external_listitem">
<li role="listitem">Carrot</li>
<li role="listitem">Tomato</li>
<li role="listitem">Lettuce</li>
</ul>
…
<div role="listitem" id="external_listitem">Asparagus</div>
If the tree is not completely represented in the DOM at all times, don't use either the structured or aria-owns
methods. Instead use aria-level
, aria-posinset
and aria-setsize
.
-
Use states and properties in response to events
Control the behavior of the element in response to user input events such as from the keyboard and the mouse. For example, a tree control will need to respond to click events on the expand/collapse triggers, and key events on the currently active descendant. Use device-independent events with supporting JavaScript to handle user interaction.
3. Normative Requirements
This section is normative.
This specification indicates whether a section is normative or informative.
Normative sections provide requirements that must be followed for an implementation to conform to this specification. The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Keywords for use in RFCs to indicate requirement levels [RFC2119].
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.
4. The Roles Model
This section is normative.
This section defines the WAI-ARIA role taxonomy and describes the characteristics and properties of all roles. A formal RDF/OWL representation of all the information presented here is available in Appendix 8.1: Implementation.
4.1. Relationships Between Concepts
The role taxonomy uses the following relationships to relate ARIA roles to each other and to concepts from other specifications, such as HTML and XForms.
4.1.1. Parent Roles
- RDF Property
- rdfs:subClassOf
The role that this role extends in the taxonomy. This extension causes all the properties and constraints of the parent role to propagate to the child role. Other than well known stable specifications, inheritance may be restricted to items defined inside this specification so that items cannot be changed and affect inherited classes.
For example: the checkbox
role is a subclass or type of the option
role. If we change the properties and expected behavior of an option
then the properties and behavior of checkbox
will also change.
Inheritance is expressed in RDF using the RDF Schema subClassOf ([RDFS], section 3.4) property.
4.1.2. Child Roles
- RDF Property
- <none>
Informative list of roles for which this role is the parent. This is provided to facilitate reading of the specification but adds no new information.
4.1.4. Base Concept
- RDF Property
- role:baseConcept
Informative data about objects that are considered prototypes for the role. 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 a relatedConcept except that base concepts are almost identical to each other.
For example: the checkbox
defined in this document has similar functionality and the same anticipated behavior as a checkbox defined in HTML.
Therefore, a checkbox
has an HTML checkbox
as a baseConcept
. However, if the HTML checkbox is modified, the definition of a checkbox
in this document will not be not affected, because there is no actual inheritance of type.
4.2. Characteristics 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, what instances of the role can or must contain. In the case of widgets this also includes how it interacts with the user agent based on mapping to HTML forms and XForms. States and properties from WAI-ARIA that are supported by the role are also indicated.
The Roles Taxonomy defines the following characteristics. These characteristics are implemented in RDF as properties of the OWL classes that describe the roles.
4.2.1. Abstract Roles
- RDF Property
- N/A
- Values
- Boolean
Abstract roles are the foundation upon which all other ARIA roles are built. They SHOULD NOT be used by authors because they are not implemented in the API binding. Abstract roles are provided to help with the following:
- Organize the role taxonomy and provide roles with a meaning in the context of known concepts.
- Streamline the addition of roles that include necessary features.
4.2.2. Required States and Properties
- RDF Property
- role:supportedState
- Values
- Any valid RDF object reference, such as a URI or an RDF ID reference.
States and properties specifically required for the role and child roles. Content authors SHOULD provide values for required states and properties.
When an object 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.
4.2.3. Supported States and Properties
- RDF Property
- role:supportedState
- Values
- Any valid RDF object reference, such as a URI or an RDF ID reference.
States and properties specifically applicable to the role and child roles. User agents MUST implement all supported states and properties for the role. Content authors MAY provide values for supported states and properties, but may not in all cases because default values are sufficient.
4.2.4. Inherited States and Properties
Informative list of properties that are inherited onto a role from ancestor roles. States and properties are inherited from ancestor roles in the role taxonomy, not from ancestor elements in the DOM 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. Inherited states and properties that are required are indicated as such in this field as well. 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.
4.2.5. Required Child Elements
- RDF Property
- role:mustContain
- Values
- Any valid RDF object reference, such as a URI or an RDF ID reference.
Any element that must be owned by the element with this role. For example, an element with the role list
must own an element with the role listitem
.
Note: When multiple roles are specified as "Required Child Elements" for a role, at least one instance of one required child element is required. This specification does not require an instance of each of the listed child roles. For example, a menu
should have at least one instance of a menuitem
, menuitemcheckbox
, or menuitemradio
. The menu
role does not require one instance of each.
Note: There may be times that required child elements are missing, for example, while editing or while loading a data set.
4.2.6. Parent Element
- RDF Property
- role:scope
- Values
- Any valid RDF object reference, such as a URI or an RDF ID reference.
The parent element defines the context where this role is allowed, in other words, roles for elements in which the present role SHOULD appear.
For example an element with role listitem
SHOULD be contained inside (or owned by) an element with role list
.
4.2.7. Accessible Name Calculation
- RDF Property
- role:nameFrom
- Values
- One of the following values:
- author: name comes from values provided by the author in explicit markup features such as the
aria-label
attribute, aria-labelledby
attribute, or the HTML title
attribute. - contents: name comes from the text value of the element node. Although this may be allowed in addition to "author" in some roles, this is used in content only if "author" features are not provided.
4.2.7.1. Name Computation
An accessible name may be computed by a number of methods, listed here in order of preference:
- By concatenating the text equivalents for nodes pointed to by an
aria-labelledby
on the current node. This is not not recursive: any aria-labelledby
within a subtree being used from another aria-labelledby
should be ignored by the implementation. See the text equivalent computation described below. - The results of the text equivalent computation for the current node.
4.2.7.2. Description Computation
An accessible description may be computed by concatenating the text equivalents for nodes pointed to by an aria-describedby
attribute on the current node.
4.2.7.3. Text Equivalent Computation
The text equivalent is reused in both the name and description computation, as described above. There are different rules provided for several different types of nodes and combinations of markup. Text equivalents are built up, when appropriate, from all the relevant content contained within an element. This is accomplished via rule 2C (which is recursive), using the full set of rules to retrieve text from its own children.
The text equivalent for a given node is computed as follows:
- Skip hidden elements unless the author specifies to use them via an
aria-labelledby
or aria-describedby
being used in the current computation. By default, assistive technology users won't receive the hidden information, but an author should to be able to explicitly override that and include the hidden information. - For any non-skipped elements:
- Elements may specify their text equivalent in DOM attributes, used in this order of preference:
- The aria-labelledby attribute is used unless this computation is already occurring as the result of another aria-labelledby (in other words, aria-labelledby is not recursive, so it will not cause loops). The text equivalents for all the nodes pointed to will be concatenated, using this same set of rules.
- The aria-label attribute, which is just a text string, is used next
- Any non-tooltip native markup (such as an
img
element's alt
attribute in HTML), or the subtree for a label pointing to this element (such as label
element's for
attribute in HTML) contributes according to rules defined by the appropriate specification for that markup.
- Additional contribution of user-entered data: in addition to any text from rule A, form controls contribute user-entered data be part of the final computed name, if they are in a position which provides meaningful information in the context of a larger label. The user-entered data should should be appended after any other labeling markup used for that form control. For example, an ARIA
slider
element's user-entered value would be the aria-valuetext
or string equivalent of the aria-valuenow
. For text fields, the user-entered data would be the text in the field. - Otherwise, if the DOM attributes checked in rules A and B didn't provide results, text is collected from descendant content if the current element's role allows "Name From: contents." The text equivalents for child nodes will be concatenated, using this same set of rules. This same rule may apply to a child, which means the computation becomes recursive and can result in text being collected in all the nodes in this subtree, no matter how deep they are. However, any given descendant subtree may instead collect their part of the text equivalent from the preferred markup described in A and B above. These author-specified attributes are assumed to provide the correct text equivalent for the entire subtree. All in all, the node rules are applied consistently as text equivalents are collected from descendants, and each containing element in those descendants may or may not allow their contents to be used.
- The last resort is to use text from tooltip markup (such as the
title
attribute in HTML). This is used only if nothing else, including subtree content, has provided results.
- Text nodes are often visited because they are children of an element that uses rule 2C to collect text from its children. For text nodes, rendered text is used rather than DOM text contents. This helps remove superfluous whitespace from the original source, and to include CSS-generated text such as list item bullets.
Note: The purpose of the flat text equivalent string is to create something readable in alternative presentations. An implementation should insert whitespace characters when visually separate elements would be "jammed" together in the same string. For example, a space character may be inserted between the text of two paragraphs used one after the other in a description.
More information can be found in accessible name computation in the WAI-ARIA User Agent Implementation Guide [ARIA-IMPLEMENTATION].
4.2.8. Presentational Children
- RDF Property
- role:childrenArePresentational
- Values
-
Boolean (true | false)
The DOM descendants are presentational. User agents SHOULD NOT expose descendants of this element through the platform accessibility API. If user agents do not hide the descendant nodes, some information may be read twice.
4.3. Categorization of Roles
To support the current user scenario, this specification categorizes roles that define user interface widgets (sliders, tree controls, etc.) and those that define page structure (sections, navigation, etc.).
Roles are categorized as follows:
- Base Types
- User Input Widgets
- User Interface Elements
- Document Structure
- Specialized Regions
- Landmark Roles
4.3.1. Base Types
The following roles are used as base types for applied roles. Base classes are used to describe the highest level of the role taxonomy class hierarchy. Note that while all roles in this section are abstract, not all abstract roles are in this section. This section includes only the most high-level abstractions in the taxonomy.
Note: Abstract roles are used for the ontology. Authors SHOULD NOT use abstract roles in content.
4.3.3. User Interface Elements
The following roles are used as part of the graphical user interface.
4.3.4. Document Structure
The following roles describe structures that organize content in a page. Document structures are not usually interactive.
4.3.5. Application Structure
The following roles are special, self-contained areas of application user interfaces.
4.3.6. Landmark Roles
The following roles are regions of the page intended as navigational landmarks. All of these roles inherit from the landmark
base type and, with the exception of application
, all are imported from the XHTML Role Attribute Module [XHTML-ROLES, Section 4]. The roles are included here in order to make them clearly part of the ARIA Role taxonomy.
4.4. Definition of Roles
Below is an alphabetical list of ARIA roles to be used by rich internet application authors.
Note: Abstract roles are used for the ontology. Authors SHOULD NOT use abstract roles in content.
alert
- A message with important, and usually time-sensitive, information. Also see alertdialog and status.
alertdialog
- A type of dialog that contains an alert message, where initial focus goes to the dialog or an element within it. Also see alert and dialog.
application
- A region declared as a web application, as opposed to a web document.
article
- A section of a page consisting of an independent part of a document, page, or site.
banner
- A region that contains the primary heading or web site title.
button
- An input that allows for user-triggered actions when clicked or pressed.
checkbox
- An checkable input that has three possible values: true, false, or mixed.
columnheader
- A cell containing header information for a column.
combobox
- A presentation of a select; usually similar to a textbox where users can type ahead to select an option, or type to enter arbitrary text as a new item in the list.
complementary
- A supporting section of the document that remains meaningful even when separated from the main content.
composite
(abstract role)- A widget that may contain navigable descendants or owned children.
contentinfo
- Metadata that applies to the parent document.
definition
- A definition of a term or concept.
dialog
- A dialog is an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. Also see alertdialog.
directory
- A list of references to members of a group, such as a static table of contents.
document
- A region containing related information that is declared as document content, as opposed to a web application.
grid
- A grid contains cells of tabular data arranged in rows and columns, like a table.
gridcell
- A cell in a grid or treegrid.
group
- A set of user interface objects which would not be included in a page summary or table of contents by an assistive technology.
heading
- A heading for a section of the page.
img
- A container for a collection of elements that form an image.
input
(abstract role)- A generic type of widget that allows user input.
landmark
(abstract role)- A region of the page intended as a navigational landmark.
link
- An interactive reference to an internal or external resource.
list
- A group of non-interactive list items.
listbox
- A widget that allows the user to select one or more items from a list of choices.
listitem
- A single item in a list, listbox, or directory.
log
- A type of live region where new information is added in meaningful order and old information may disappear. Also see marquee.
main
- The main content of a document.
marquee
- A type of live region where non-essential information changes frequently. Also see log.
math
- An element that represents a mathematical expression.
menu
- A type of widget that offers a list of choices to the user.
menubar
- A presentation of menu that usually remains visible and is usually presented horizontally.
menuitem
- An option in a group of choices contained by a menu or menubar.
menuitemcheckbox
- A checkable menuitem that has three possible values: true, false, or mixed.
menuitemradio
- A checkable menuitem in a group of menuitemradio roles, only one of which can be checked at a time.
navigation
- A collection of navigational elements (usually links) for navigating the document or related documents.
note
- A section whose content is parenthetic or ancillary to the main content of the resource.
option
- A selectable item in a select list.
presentation
- An element whose role is presentational and does not need to be mapped to the accessibility API.
progressbar
- An element that displays the progress status for tasks that take a long time.
radio
- A checkable input in a group of radio roles, only one of which can be checked at a time.
radiogroup
- A group of radio buttons.
range
(abstract role)- An input representing a range of values that can be set by the user.
region
- A large perceivable section of a web page or document, that the author feels should be included in a summary of page features.
roletype
(abstract role)- The base role from which all other roles in this taxonomy inherit.
row
- A row of cells in a grid.
rowheader
- A cell containing header information for a row in a grid.
search
- The search tool of a web document.
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 of range that expects a user to select from amongst discrete choices.
status
- A container whose content is advisory information for the user but is not important enough to justify an alert. Also see alert.
structure
(abstract role)- A document structural element.
tab
- A header for a tabpanel.
tablist
- A list of tab elements, which are references to tabpanel elements.
tabpanel
- A container for the resources associated with a tab.
textbox
- Input that allows free-form text as their value.
timer
- 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 represented in compact visual form.
tooltip
- A contextual popup that displays a description for an element in a mouse hover or keyboard focused state. Supplement to the normal tooltip processing of the user agent.
tree
- A type of list that may contain sub-level nested groups that can be collapsed and expanded.
treegrid
- A grid whose rows can be expanded and collapsed in the same manner as for a tree.
treeitem
- An option item of a tree. This is an element within a tree that may be expanded or collapsed if it contains a sub-level group of treeitems.
widget
(abstract role)- An interactive component of a graphical user interface (GUI).
window
(abstract role)- A browser or application window.
alert
(role)
A message with important, and usually time-sensitive, information. Also see alertdialog
and status
.
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. The alert
role goes on the node containing the alert message. Alerts are specialized forms of the status
role, which should be processed as an atomic live region.
Alerts do not require user input and therefore should not receive focus. Since alerts do not receive focus, users SHOULD NOT be required to close an alert. If the operating system allows, the user agent MAY fire a system alert event when the ARIA alert is created. If an alert requires focus to close the alert, then an alertdialog
SHOULD be used instead.
Note: Elements with the role alert
have an implicit aria-live
value of assertive
.
Characteristics of alertCharacteristic | Value |
---|
Parent Roles: | region |
Child Roles: | |
Related Concepts: | XForms alert |
Inherited States and Properties: | |
Name From: | author |
Implicit Value for Role: | Default for aria-live is assertive . |
alertdialog
(role)
A type of dialog that contains an alert message, where initial focus goes to the dialog or an element within it. Also see alert
and dialog
.
Alert dialogs are used to convey messages to alert the user. The alertdialog
role goes on the node containing both the alert message and the rest of the dialog. Authors SHOULD make alert dialogs modal by ensuring that, while the alertdialog
is shown, keyboard and mouse interactions only operate within the dialog.
Unlike alert
, 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, authors SHOULD set focus to an active element within the alert dialog, such as a form edit field or an OK button. The user agent MAY fire an accessibility alert event, when the alert is created, provided one is specified by the intended accessibility API.
Authors SHOULD use aria-describedby
on an alertdialog
to point to the alert message element in the dialog. If they do not, assistive technology will resort to their internal recovery mechanism to determine the contents of an alert message.
Note: Elements with the role alertdialog
have an implicit aria-live
value of assertive
.
Characteristics of alertdialogCharacteristic | Value |
---|
Parent Roles: |
|
Related Concepts: | XForms alert |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default for aria-live is assertive . |
application
(role)
A region declared as a web application, as opposed to a web document
.
The intent is to hint to the assistive technology to switch its normal browsing mode functionality to one in which they would for an application. User agents have a browse navigation mode where keys, such as up and down arrows, are used to browse the document. This native behavior prevents the use of these keys by a web application.
An author should set the role of application
on the element that encompasses the entire application. If the application role applies to the entire web page, it should be set on the root node for content, such as the body
element in HTML or svg
element in SVG.
For example, an email application has a document and an application in it. The author would want to use typical application navigation mode to cycle through the list of emails, and much of this navigation would be defined by the application author. However, when reading an email message the content should appear in a region with a document
role in order to use browsing navigation.
All non-decorative static text or image content inside the application SHOULD be either associated with a form widget or group
via aria-label
, aria-labelledby
, or aria-describedby
, or separated out into an element with role of document
or article
.
Applications SHOULD have an application title or label. This should be suitable for use as a navigation preview or table-of-contents entry for the page section in question. The label SHOULD come from one of the following sources:
- If the application includes the entire contents of the web page, use the host language feature for title or label, such as the
title
element in HTML, which labels the entire file. - Otherwise, provide a visible label referenced by the application using
aria-labelledby
.
article
(role)
A section of a page consisting of an independent part of a document, page, or site.
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 is independent in that its contents could stand alone, for example in syndication. However, the element 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.
Assistive technology must treat an article like a document in that article must be processed like an application. Unlike a document, the use of articles allows the user to identify and follow related articles based on the nesting.
Characteristics of articleCharacteristic | Value |
---|
Parent Roles: |
|
Related Concepts: | HTML 5 article |
Inherited States and Properties: | |
Name From: | author |
banner
(role)
A region that contains the primary heading or web site title.
Most of the content of a banner is site-oriented, rather than being page-specific. Site-oriented content typically includes things such as the logo of the site sponsor, the main heading for the page, and site-specific search tool. Typically this appears at the top of the page spanning the full width.
Within any document
or application
, the author SHOULD mark no more than one element with the banner
role.
Note: Because document
and application
elements can be nested in the DOM, they may have multiple banner
elements as DOM descendants, assuming each of those is associated with different document nodes, either by a DOM nesting (e.g., document
within document
) or by use of the aria-owns
attribute.
Characteristics of bannerCharacteristic | Value |
---|
Parent Roles: | landmark |
Inherited States and Properties: | |
Name From: | author |
checkbox
(role)
An checkable input that has three possible values: true
, false
, or mixed
.
The aria-checked
attribute of a checkbox
indicates whether the input is checked (true
), unchecked (false
), or represents a group of elements that have a mixture of checked and unchecked values (mixed
). Many checkboxes do not use the mixed
value, and thus are effectively boolean checkboxes.
Characteristics of checkboxCharacteristic | Value |
---|
Parent Roles: | input |
Child Roles: | |
Related Concepts: |
|
Required States and Properties: | aria-checked |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
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 similar relationship in the data.
The columnheader
establishes a relationship between it and all cells in the corresponding column. It is the structural equivalent to an HTML th
element with a column scope.
Note: Because cells are organized into rows, there is not a single container element for the column. The column is the set of gridcell
elements in a particular position within their respective row
containers.
Characteristics of columnheaderCharacteristic | Value |
---|
Parent Roles: |
|
Base Concept: | HTML th with scope=col |
Parent Element: | row |
Supported States and Properties: | aria-sort |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
combobox
(role)
A presentation of a select
; usually similar to a textbox
where users can type ahead to select an option, or type to enter arbitrary text as a new item in the list.
combobox
is the combined presentation of a single line text box with a list box popup. The combobox
may be editable. Typically editable combo boxes are used for autocomplete behavior, and the aria-autocomplete
property may be used on the child textbox.
Note: In XForms [XFORMS] the same select
can have one of 3 appearances: combo-box, drop-down box, or group of radio-buttons. Many browsers allow users to type in a drop-down select as well. This specification does not constrain the presentation of the combo box.
To be keyboard accessible, instances of this role SHOULD manage focus of descendants, as described in Managing Focus.
Note: Elements with the role combobox
have an implicit aria-haspopup
value of true
.
Characteristics of comboboxCharacteristic | Value |
---|
Parent Roles: | select |
Related Concepts: |
|
Required Child Elements: | listbox |
Required States and Properties: | aria-expanded |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default for aria-haspopup is true . |
complementary
(role)
A supporting section of the document that remains meaningful even when separated from the main content.
There are various types of content that would appropriately have this role. 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 content should be relevant to the main content; if it is completely separable, a more general role should be used instead.
Characteristics of complementaryCharacteristic | Value |
---|
Parent Roles: | landmark |
Inherited States and Properties: | |
Name From: | author |
composite
(abstract role)
A widget that may contain navigable descendants or owned children.
The composite widget SHOULD exist as a single navigation stop within the larger navigation system of the web page. Once the composite widget has focus, it SHOULD provide a separate navigation mechanism for users to document elements 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 of compositeCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | widget |
Child Roles: | |
Supported States and Properties: | aria-activedescendant |
Inherited States and Properties: | |
Name From: | author |
Children Presentational: | False |
contentinfo
(role)
Metadata that applies to the parent document.
For example, footnotes, copyrights, and links to privacy statements would belong here.
Characteristics of contentinfoCharacteristic | Value |
---|
Parent Roles: | landmark |
Inherited States and Properties: | |
Name From: | author |
definition
(role)
A definition of a term or concept.
The ARIA specification does not provide a role to specify the definition term, but host languages may provide such an element. If a host language has an appropriate element for the term (e.g. dfn
or dt
in HTML), the term should be included in that element. Elements with a role of definition
SHOULD have an aria-labelledby
attribute identifying the definition term element.
Characteristics of definitionCharacteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Name From: | author |
dialog
(role)
A dialog is an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. Also see alertdialog
.
Dialog boxes SHOULD have a title, which may be provided with the aria-label
or aria-labelledby
attribute if other mechanisms are not available. They SHOULD have a focused descendant element that has keyboard focus.
Characteristics of dialogCharacteristic | Value |
---|
Parent Roles: | window |
Child 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.
Authors SHOULD use this role 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 a tree
role instead.
Characteristics of directoryCharacteristic | Value |
---|
Parent Roles: | list |
Child Roles: | |
Related Concepts: | DAISY Guide |
Inherited States and Properties: | |
Name From: |
|
document
(role)
A region containing related information that is declared as document content, as opposed to a web application
.
The document
role informs user agents of the need to augment browser keyboard support in order to allow users to visit and read any content within the document region. In contrast, additional commands are not necessary for screen reader users to read text within a region with role="application"
, where all text should be semantically associated with focusable elements. An important trait of documents is that they have some text which is not associated with widgets or groups thereof.
An author should set the role of document
on the element that encompasses the entire document. If the document role applies to the entire web page, it should be set on the root node for content, such as the body
element in HTML or svg
element in SVG.
For example, an email application has a document and an application in it. The author would want to use typical application navigation mode to cycle through the list of emails, and much of this navigation would be defined by the application author. However, when reading an email message, the content should appear in a region with a document
role in order to use browsing navigation.
Documents SHOULD have a document title or label. This should be suitable for use as a navigation preview or table-of-contents entry for the page section in question. The label SHOULD come from one of the following sources:
- If the document includes the entire contents of the web page, use the host language feature for title or label, such as the
title
element in HTML, which labels the entire file. - Otherwise, provide a visible label referenced by the document using
aria-labelledby
.
grid
(role)
A grid
contains cells of tabular data arranged in rows and columns, like a table.
Grids do not necessarily imply presentation. The grid
construct describes relationships between data such that it may be used for different presentations. Grids allow the user to move focus between cells using two dimensional navigation. For example, grid
might be used as the invisible data model (hidden with CSS but still operable by assistive technology) for a presentational chart.
Cells with role gridcell
, SHOULD be contained in rows with role row
, which in turn SHOULD be contained in a grid
. Cells may be focusable. Grids may be empty, containing no rows or cells. Grids MAY have row and column headers, provided with rowheader
and columnheader
roles, which also assist the user agent in supporting navigation. gridcell
elements MAY have contents determined by a calculation.
gridcell
elements with the aria-selected
attribute set can be selected for user interaction, and if the aria-multiselectable
attribute of the grid
is set to true
, multiple cells in the grid may be selected. Grids may be used for spreadsheets like those in desktop spreadsheet applications.
To be keyboard accessible, instances of this role SHOULD manage focus of descendants, as described in Managing Focus.
Characteristics of gridCharacteristic | Value |
---|
Parent Roles: |
|
Child Roles: | |
Base Concept: | HTML table |
Required Child Elements: | row |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
gridcell
(role)
A cell in a grid or treegrid.
Cells may be active, editable, and selectable. Cells may have relationships such as aria-controls
to address the application of functional relationships.
If headers cannot be determined from the DOM structure, cells SHOULD explicitly indicate which header cells are relevant to them. They do this by referencing elements with role rowheader
or columnheader
using the aria-describedby
attribute.
In a treegrid
, cells MAY be expandable and use the aria-expanded
attribute. If the aria-expanded
attribute is provided, it applies only to the individual cell. It is not a proxy for the container row, which also can be expanded. The main use case for providing this attribute on a cell is pivot table behavior.
Characteristics of gridcellCharacteristic | Value |
---|
Parent Roles: |
|
Child Roles: | |
Base Concept: | HTML td |
Parent Element: | row |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
group
(role)
A set of user interface objects which would not be included in a page summary or table of contents by an assistive technology.
Contrast with region
which is sections of user interface objects that should be included in a page summary or table of contents.
Authors should use a group
to form logical collection of items in a widget 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. Therefore, proper handling of group by assistive technology must be determined by the context in which it is provided.
Groups may also be nested. If the author believes a section is significant enough in terms of the entire delivery unit web page then the author should assign the section a role of region
or a standard landmark role.
Group members that are not a DOM descendant of the group would need to have explicit relationships assigned to participate in the group using the aria-owns
attribute.
Characteristics of groupCharacteristic | Value |
---|
Parent Roles: | section |
Child Roles: | |
Related Concepts: | HTML fieldset |
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 the aria-labelledby
attribute of the section for which they serve as a heading. If headings are organized into a logical outline, the aria-level
attribute may be used to indicate the nesting level.
Characteristics of headingCharacteristic | Value |
---|
Parent Roles: | sectionhead |
Related Concepts: |
|
Supported States and Properties: | aria-level |
Inherited States and Properties: | |
Accessible Name Required: | True |
img
(role)
A container for a collection of elements that form an image.
An img
can contain captions and descriptive text, as well as multiple image files that when viewed together give the impression of a single image. An img
represents a single graphic within a document, whether or not it is formed by a collection of drawing objects. In order to be perceivable, elements with a role of img
SHOULD have alternative text or a label associated by the accessible name calculation.
Characteristics of imgCharacteristic | Value |
---|
Parent Roles: | section |
Related Concepts: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
landmark
(abstract role)
A region of the page intended as a navigational landmark.
User agents or assistive technology MAY allow the user to quickly navigate to these regions.
Note: landmark
is an abstract role used for the ontology. Authors SHOULD NOT use this role in content.
Characteristics of landmarkCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | region |
Child Roles: | |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | False |
link
(role)
An interactive reference to an internal or external resource.
If this is a native link in the host language (such as an HTML anchor with an href
value), activating the link causes the user agent to navigate to that resource. If this is a simulated link, the web application is responsible for managing navigation.
Characteristics of linkCharacteristic | Value |
---|
Parent Roles: | widget |
Related Concepts: | HTML link |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
list
(role)
A group of non-interactive list items.
Lists contain children whose role is listitem
, or elements whose role is group
which in turn contains children whose role is listitem
.
Characteristics of listCharacteristic | Value |
---|
Parent Roles: | region |
Child Roles: | |
Base Concept: |
|
Required Child Elements: |
|
Inherited States and Properties: | |
Name From: | author |
listbox
(role)
A widget that allows the user to select one or more items from a list of choices.
Items within the list are static and, unlike in standard HTML select
elements, may contain images. List boxes contain children whose role is option
.
To be keyboard accessible, instances of this role SHOULD manage focus of descendants, as described in Managing Focus.
Although listbox
inherits the aria-expanded
attribute, if there is a valid reason to expand the listbox
, authors should consider using a combobox
instead.
Characteristics of listboxCharacteristic | Value |
---|
Parent Roles: |
|
Related Concepts: |
|
Required Child Elements: | option |
Supported States and Properties: | aria-multiselectable |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
listitem
(role)
A single item in a list, listbox, or directory.
Characteristics of listitemCharacteristic | Value |
---|
Parent Roles: | section |
Child Roles: | |
Base Concept: | HTML li |
Related Concepts: | XForms item |
Parent Element: | list |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
log
(role)
A type of live region where new information is added in meaningful order and old information may disappear. Also see marquee
.
Examples include chat logs, messaging history, game log, or an error log. In contrast to other live regions, in this role there is a relationship 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.
Note: Elements with the role log
have an implicit aria-live
value of polite
.
Characteristics of logCharacteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Implicit Value for Role: | Default for aria-live is polite . |
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. The main
role is a non-obtrusive alternative for "skip to main content" links, where the navigation option to go to the main content (or other landmarks) is provided by the user agent through a dialog or by an assistive technology.
Within any document
or application
, the author SHOULD mark no more than one element with the main
role.
Note: Because document
and application
elements can be nested in the DOM, they may have multiple main
elements as DOM descendants, assuming each of those is associated with different document nodes, either by a DOM nesting (e.g., document
within document
) or by use of the aria-owns
attribute.
Characteristics of mainCharacteristic | Value |
---|
Parent Roles: | landmark |
Inherited States and Properties: | |
Name From: | author |
marquee
(role)
A type of live region where non-essential information changes frequently. Also see log
.
Common usages of marquee
include stock tickers and ad banners. An example of a marquee is a stock ticker. The primary difference between a marquee
and a log
is that logs usually have a meaningful sequence of more important content changes.
Characteristics of marqueeCharacteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Accessible Name Required: | True |
math
(role)
An element that represents a mathematical expression.
The math role is used to indicate sections that represent math. Such sections SHOULD use a formal mathematical language such as MathML to express mathematical concepts. However, since there exists significant amounts of legacy content that use images and ASCII art to represent mathematical expressions, the math role also allows assistive technology to deliver to the user the text equivalent provided for the image, which can be converted, for example, to Braille or text to speech. The text equivalent used in such situations SHOULD be valid MathML or TeX. In order to be perceivable, images SHOULD also be labeled by text that describes the math formula as it should be spoken, using the aria-describedby
attribute. The text description should have no special markup used to control a speech device.
Characteristics of mathCharacteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Name From: | author |
Children Presentational: | True |
navigation
(role)
A collection of navigational elements (usually links) for navigating the document or related documents.
Characteristics of navigationCharacteristic | Value |
---|
Parent Roles: | landmark |
Inherited States and Properties: | |
Name From: | author |
note
(role)
A section whose content is parenthetic or ancillary to the main content of the resource.
Characteristics of noteCharacteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Name From: | author |
option
(role)
Characteristics of optionCharacteristic | Value |
---|
Parent Roles: | input |
Child Roles: | |
Base Concept: | HTML option |
Related Concepts: |
|
Parent Element: | select |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
presentation
(role)
An element whose role is presentational and does not need to be mapped to the accessibility API.
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.
Example use cases:
- An element whose content is presentational (like a spacer image, decorative graphic, or clearing element);
- An image that is in a container having the same role and where the full equivalent is available in text that is marked up with Labelledby and (if needed)
aria-describedby
; - An element used as an additional markup "hook" for CSS; or
- A layout table and/or any of its associated cells, rows, etc.
The user agent MAY choose not to present all structural aspects of the element being repurposed. For example, for a table marked as presentation
, the user agent would remove the table
, td
, th
, tr
, etc. elements from the accessibility API mapping, while preserving the individual text elements within them. Because the user agent knows to ignore the structural aspects implied in a table, no harm is done by using a table for layout.
User agents should ignore elements with the presentation role for the purpose of determining the containment of items with ARIA roles.
For example, in the following code sample:
<div role="img" aria-labelledby="caption">
<img src="example.png" role="presentation" alt="">
<p id="caption">A visible text caption labeling the image.</p>
</div>
The containing div
element has an ARIA role of img
and is appropriately labeled by the caption paragraph. In this example the img
element can be marked as presentation because the role and the text equivalents are provided by the containing element.
In the following code sample:
<ul role="tree">
<li role="presentation">
<a role="treeitem" aria-expanded="true">An expanded tree node</a>
</li>
…
</ul>
Because the anchor (HTML a
element) is acting as the treeitem, the list item (HTML li
element) is assigned an explicit ARIA role of presentation to override the user agent's default behavior for list item.
Characteristics of presentationCharacteristic | Value |
---|
Parent Roles: | structure |
Inherited States and Properties: | |
progressbar
(role)
An element 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 author SHOULD supply values for aria-valuenow
, aria-valuemin
, and aria-valuemax
, unless the value is indeterminate, in which case the aria-valuenow
attribute should be omitted. These values should be updated when the visual progress indicator is updated. If the progressbar
is describing the loading progress of a particular region of a page, the author SHOULD use aria-describedby
to point to the status, and set the aria-busy
attribute to true
on the region until it is finished loading.
Characteristics of progressbarCharacteristic | Value |
---|
Parent Roles: | widget |
Related Concepts: | status |
Supported States and Properties: |
aria-valuetext |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
radio
(role)
A checkable input in a group of radio
roles, only one of which can be checked at a time.
Elements with role radio
SHOULD be be explicitly grouped in order to indicate which ones affect the same value. This should be done by enclosing them in an element with role radiogroup
. If it is not possible to make the radio buttons DOM children of the radiogroup
, use the aria-owns
attribute on the radiogroup
element to indicate the relationship to its children.
Characteristics of radioCharacteristic | Value |
---|
Parent Roles: | |
Child Roles: | |
Related Concepts: | HTML input[type="radio"] |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
radiogroup
(role)
A group of radio
buttons.
A radiogroup
is a type of select
list that can only have a single entry checked at any one time. Authors SHOULD 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 (its aria-checked
attribute becomes false
).
Characteristics of radiogroupCharacteristic | Value |
---|
Parent Roles: | select |
Related Concepts: | list |
Required Child Elements: | radio |
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 of rangeCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | input |
Child Roles: | |
Supported States and Properties: |
aria-valuetext |
Inherited States and Properties: | |
Name From: | author |
region
(role)
A large perceivable section of a web page or document, that the author feels should be included in a summary of page features.
This role defines a group of elements that together form a large perceivable section that the author feels should be included in a summary of page features. A region
SHOULD have a heading, provided via an instance of the heading
role or by using the standard accessible name calculation. A region does not necessarily follow the logical structure of the content, but follows the perceivable structure of the page.
When defining regions of a web page, authors should consider using standard document landmark
roles. If the definitions of these regions are inadequate, authors should use the region
role and provide the appropriate accessible name.
Characteristics of regionCharacteristic | Value |
---|
Parent Roles: | section |
Child Roles: | |
Related Concepts: |
|
Inherited States and Properties: | |
Name From: | author |
roletype
(abstract role)
The base role from which all other roles in this taxonomy inherit.
Properties of this role describe the structural and functional purpose of objects that are assigned this role (known in RDF terms as "instances"). A role is a concept that can be used to understand and operate instances.
Note: roletype
is an abstract role used for the ontology. Authors SHOULD NOT use this role in content.
Characteristics of roletypeCharacteristic | Value |
---|
Is Abstract: | True |
Child Roles: | |
Related Concepts: |
|
Supported States and Properties: | Placeholder for global properties |
Inherited States and Properties: | |
row
(role)
Characteristics of rowCharacteristic | Value |
---|
Parent Roles: | group |
Base Concept: | HTML tr |
Parent Element: |
|
Required Child Elements: | gridcell |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
search
(role)
The search tool of a web document.
This is typically a form used to submit search requests about the site or to a more general Internet search service.
Characteristics of searchCharacteristic | Value |
---|
Parent Roles: | landmark |
Inherited States and Properties: | |
Name From: | author |
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 of sectionCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | structure |
Child Roles: | |
Related Concepts: |
|
Inherited States and Properties: | |
Name From: |
|
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 of sectionheadCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | structure |
Child Roles: | |
Inherited States and Properties: | |
Name From: |
|
select
(abstract role)
A form widget that allows the user to make selections from a set of choices.
Elements with role option
, SHOULD be contained in elements using one of the non-abstract child roles of select
. Selects may be empty, containing no rows or cells.
Note: select
is an abstract role used for the ontology. Authors SHOULD NOT use this role in content.
Characteristics of selectCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: |
|
Child Roles: | |
Inherited States and Properties: | |
Name From: | author |
separator
(role)
A divider that separates and distinguishes sections of content or groups of menuitems.
This is a visual separator between sections of content. For example, separators are found between groups of menu items in a menu or as the moveable separator between two regions in a split pane.
Characteristics of separatorCharacteristic | Value |
---|
Parent Roles: | structure |
Related Concepts: | HTML hr |
Inherited States and Properties: | |
Name From: | author |
Children Presentational: | True |
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.
Characteristics of sliderCharacteristic | Value |
---|
Parent Roles: | range |
Required States and Properties: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
status
(role)
A container whose content is advisory information for the user but is not important enough to justify an alert. Also see alert
.
A status
object must have content within it to provide the actual status information. This object SHOULD NOT receive focus.
Status is a form of live region. If another part of the page controls what appears in the status, the relationship should be made explicit with the aria-controls
attribute.
Assistive technology devices MAY reserved some cells of a Braille display to render the status.
Note: Elements with the role status
have an implicit aria-live
value of polite
.
Characteristics of statusCharacteristic | Value |
---|
Parent Roles: |
|
Child Roles: | |
Inherited States and Properties: | |
Implicit Value for Role: | Default for aria-live is polite . |
structure
(abstract role)
A document structural element.
Roles for document structure support the accessibility of dynamic web content by helping assistive technology to determine active content vs. static document content. Structural roles by themselves do not all map to accessibility APIs, but are used to create widget roles or assist content adaptation.
Note: structure
is an abstract role used for the ontology. Authors SHOULD NOT use this role in content.
Characteristics of structureCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | roletype |
Child Roles: | |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: | |
tab
(role)
A header for a tabpanel
.
The tab
role is used as a grouping label, providing a link for selecting the tab content to be rendered to the user. If a tabpanel
or item in a tabpanel
has focus, the associated tab
is the currently active tab
in the tablist
, as defined by aria-activedescendant
.
The tabpanel
associated with the currently active tab SHOULD be perceivable to the user:
- For a single-selectable
tablist
, other tabpanel
elements SHOULD be hidden from the user until the user selects the tab associated with that tabpanel. - For a multi-selectable
tablist
, each tabpanel
element that is visible SHOULD have its aria-expanded
attribute set to true
, and the remaining tabpanel
elements SHOULD be hidden and their aria-expanded
attributes SHOULD be set to false
.
In either case, authors SHOULD ensure the currently active tab has its aria-selected
attribute set to true
while other tab elements SHOULD have aria-selected
set to false
, and the currently selected tab SHOULD provide visual indication that it is selected. In the absence of an aria-selected
attribute on the current tab, user agents SHOULD indicate the currently active tab to assistive technology through the platform accessibility API.
Characteristics of tabCharacteristic | Value |
---|
Parent Roles: |
|
Parent Element: | tablist |
Supported States and Properties: | aria-selected |
Inherited States and Properties: | |
Name From: |
|
tabpanel
(role)
Characteristics of tabpanelCharacteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
tablist
(role)
Characteristics of tablistCharacteristic | Value |
---|
Parent Roles: |
|
Related Concepts: | DAISY Guide |
Required Child Elements: | tab |
Inherited States and Properties: | |
Name From: |
|
textbox
(role)
Input that allows free-form text as their value.
If the aria-multiline
attribute is true
, the widget accepts line breaks within the input, as in an HTML textarea. Otherwise this is a simple text box.
The intended use is for languages that do not have a text input
element (such as
SVG), or cases in which an element with different semantics is repurposed as an text field.
Characteristics of textboxCharacteristic | Value |
---|
Parent Roles: | input |
Related Concepts: |
|
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
timer
(role)
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 timer object indicate the current time measurement, and are updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents SHOULD be updated at fixed intervals, except when the timer is paused or reaches an end-point.
A timer is a form of live region. The default value of aria-live
for timer
is off
.
Characteristics of timerCharacteristic | Value |
---|
Parent Roles: | status |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
tree
(role)
A type of list
that may contain sub-level nested groups that can be collapsed and expanded.
To be keyboard accessible, instances of this role SHOULD manage focus of descendants, as described in Managing Focus.
Characteristics of treeCharacteristic | Value |
---|
Parent Roles: | select |
Child Roles: | |
Required Child Elements: | treeitem |
Supported States and Properties: | aria-multiselectable |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
treegrid
(role)
Characteristics of treegridCharacteristic | Value |
---|
Parent Roles: |
|
Required Child Elements: | row |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
treeitem
(role)
An option item of a tree
. This is an element within a tree that may be expanded or collapsed if it contains a sub-level group of treeitem
s.
A collection of treeitem
s to be expanded and collapsed are enclosed in an element with the group
role.
Characteristics of treeitemCharacteristic | Value |
---|
Parent Roles: |
|
Parent Element: | tree |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
window
(abstract role)
A browser or application window.
Elements with this role 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.
Note: window
is an abstract role used for the ontology. Authors SHOULD NOT use this role in content.
Characteristics of windowCharacteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | roletype |
Child Roles: | |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: | |
Name From: | author |
5. Supported States and Properties
This section is normative.
5.1. Clarification of States versus Properties
This section is informative.
The terms "states" and "properties" refer to similar features. Both provide specific information about an object, and both form part of the definition of the nature of roles. In this document, states and properties are both treated as aria-prefixed markup attributes. However, they are maintained conceptually distinct to clarify subtle differences in their meaning. One major difference is that the values of properties (such as aria-labelledby
) are less likely to change throughout the application life-cycle than the values of states (such as aria-checked
) which may change frequently due to user interaction. See the definitions of state and property for more information.
5.2. Characteristics of States and Properties
States and properties have the following characteristics:
5.2.2. Used in Roles
Advisory information about roles that use this state or property. 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.
5.2.3. Inherits into Roles
Advisory information about roles that inherit the state or property from an ancestor role.
5.2.4. Value
Value restrictions for the state or property. These restrictions are expressed in terms of XML Schema Datatypes [XSD]. The following XSD Datatypes are used in this specification.
Values of type boolean, NMTOKEN, and NMTOKENS are further explained by listing the allowed values and their meanings below the table of characteristics. When a value is indicated as the default, the behavior prescribed by this value MUST be followed when the state or property is not provided. Some roles also define what behavior to use when certain states or properties, that do not have default values, are not provided.
The value undefined
, when allowed on a state or property, is an explicit indication that the state or property is not set. For processing purposes, the value undefined
is equivalent to the state or property attribute being not present in the DOM. States and properties that support the undefined
value may also provide a zero-length string ("") as the value; this is also equivalent to the state or property attribute being not present in the DOM. States and properties of types boolean, decimal, integer, NMTOKEN, and NMTOKENS may support this value.
Note: In the XHTML module, value restrictions are necessarily expressed in DTD notation, not XSD. DTD notation does not provide the precise value restrictions supported by XSD, and therefore the values in the DTD often have a wider scope of allowed values than what is actually allowed by this specification. Implementers MUST be sure to observe the value restrictions defined here and not rely simply on DTD validation.
5.3. Values for States and Properties
Many states and properties accept a specific set of tokens as values. The allowed values and explanation of their meaning is shown after the table of characteristics. The default value, if defined, is shown in strong type.
5.4. Global States and Properties
Some states and properties are applicable to all host language elements regardless of whether a role 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 role roletype
, 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.
5.5. Taxonomy of ARIA States and Properties
States and properties are categorized as follows:
- Widget Attributes
- Live Region Attributes
- Drag-and-Drop Attributes
- Relationship Attributes
5.5.2. Live Region Attributes
This section contains attributes specific to live regions in rich internet applications. These attributes may be applied to any element. The purpose of these attributes is to indicate that content changes may occur without the element having focus, and to provide the assistive technology information on how to process those content updates. Some roles specify a default value for the aria-live
attribute specific to that role. An example of a live region is a ticker section that lists updating stock quotes.
5.5.4. Relationship Attributes
This section lists attributes that indicate relationships or associations between elements which cannot be readily determined from the document structure.
5.6. Definitions of States and Properties (all aria-* attributes)
Below is an alphabetical list of ARIA states and properties to be used by rich internet application authors. A detailed definition of each ARIA state and property follows this compact list.
aria-activedescendant
- Identifies the currently active descendant of a composite widget.
aria-atomic
- Indicates if the assistive technology should present all or part of the changed region to the user when the region is updated. Also see aria-relevant.
aria-autocomplete
- Indicates whether user input completion suggestions are provided.
aria-busy
(state)- Indicates whether a live region is finished updating.
aria-checked
(state)- Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. Also see aria-pressed and aria-selected.
aria-controls
- Identifies the element (or elements) whose contents or presence are controlled by the current element. Also see aria-owns.
aria-describedby
- Identifies the element (or elements) that describes the object. Also see aria-labelledby.
aria-disabled
(state)- Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. Also see aria-hidden and aria-readonly.
aria-dropeffect
(state)- Indicates the effect of a drag-and-drop operation when the dragged object is released on the drop target.
aria-expanded
(state)- Indicates whether an expandable/collapsible group of elements is currently expanded or collapsed.
aria-flowto
- Identifies the next element (or elements) in the recommended reading order of content, overriding the general default to read in document source order.
aria-grabbed
(state)- Indicates an element's "grabbed" state in a drag-and-drop operation.
aria-haspopup
- Indicates that the element has a popup context menu or sub-level menu.
aria-hidden
(state)- Indicates that the element is not visible or perceivable to the user. Also see aria-disabled.
aria-invalid
(state)- Indicates the entered value does not conform to the format expected by the application.
aria-label
- Defines a string value that labels the current element. Also see aria-labelledby.
aria-labelledby
- Identifies the element (or elements) that labels the current element. Also see aria-label and aria-describedby.
aria-level
- Defines the hierarchical level of an element within a structure.
aria-live
- Indicates that an element will be updated, and describes the types of updates the user agent, assistive technology, and user can expect from the live region.
aria-multiline
- Indicates whether a text box accepts only a single line, or if it can accept multiline input.
aria-multiselectable
- Indicates that the user may select more than one item from the current selectable descendants.
aria-owns
- Identifies an element (or elements) in order to define a visual or functional, contextual parent/child relationship among DOM elements where the DOM hierarchy cannot be used to represent the relationship.
aria-posinset
- Defines an element's number or position in the current set of listitems or treeitems. Not required if inferred by the DOM. Also see aria-setsize.
aria-pressed
(state)- Indicates the current "pressed" state of toggle buttons. Also see aria-checked and aria-selected.
aria-readonly
- Indicates that the element is not editable, but is otherwise operable. Also see aria-disabled.
aria-relevant
- Indicates the nature of changes within a live region. Also see aria-atomic.
aria-required
- Indicates that user input is required on the element before a form may be submitted.
aria-selected
(state)- Indicates the current "selected" state of various widgets. Also see aria-checked and aria-pressed.
aria-setsize
- Defines the number of items in the current set of listitems or treeitems. Not required if inferred by the DOM. Also see aria-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 range widget.
aria-valuemin
- Defines the minimum allowed value for a range widget.
aria-valuenow
- Defines the current value for a range widget. Also see aria-valuetext.
aria-valuetext
- Defines the human readable text equivalent of aria-valuenow for a range widget.
aria-activedescendant
(property)
Identifies the currently active descendant of a composite
widget.
This is used when a composite widget is responsible for managing its current active child to reduce the overhead of having all children be focusable. Examples include: multi-level lists, trees, and grids. In some implementations the user agent may use aria-activedescendant
to tell an assistive technology that the active descendant has focus.
Authors SHOULD ensure that the element targeted by the activedescendant
attribute is either a descendant of the container in the DOM, or is a logical descendant as indicated by the aria-owns
attribute. The user agent is not expected to check that the active descendant is an actual descendant of the container. Authors SHOULD ensure that the currently active descendant remains visible and in view. Authors SHOULD capture changes to the activedescendant
attribute, which can occur if the assistive technology or user agent sets focus directly.
Characteristics of aria-activedescendantCharacteristic | Value |
---|
Related Concepts: | SVG [SVG] and DOM [DOM] active |
Used in Roles: |
|
Value: | IDREF |
aria-atomic
(property)
Indicates if the assistive technology should present all or part of the changed region to the user when the region is updated. Also see aria-relevant
.
Both accessibility APIs and the Document Object Model [DOM] provide events to allow the assistive technology to determine changed areas of the document.
When a node changes, the assistive technology SHOULD look at the changed element and then traverse the ancestors to find the first element with aria-atomic
set, and apply the appropriate behavior for the cases below.
- If none of the ancestors have explicitly set
aria-atomic
, the default is that aria-atomic
is false
, and the assistive technology only needs to present the changed node to the user. - If
aria-atomic
is explicitly set to false
, then the assistive technology can stop searching up the ancestor chain, and should present only the changed node to the user. - If
aria-atomic
is explicitly set to true
, then the assistive technology should present the entire contents of the element.
When aria-atomic
is true
, the assistive technology MAY choose to combine several changes and present the entire changed region at once.
Characteristics of aria-atomicCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | boolean |
Values of aria-atomicValue | Description |
---|
true: | The assistive technology should present the entire region as a whole. |
false: | A change within the region may be processed by the assistive technology on its own. |
aria-autocomplete
(property)
Indicates whether user input completion suggestions are provided.
For a textbox with the aria-autocomplete
attribute set to either inline
or both
, the completion text should be selected and come after the cursor, so the user can type over it. The aria-haspopup
attribute can be used in conjunction with this to indicate that a popup containing choices appears, notwithstanding the fact that it is a simple text box.
For an element which already has a drop-down (i.e., a combobox
), it is assumed that the dropdown behavior is still present. This means that if autocomplete
is true
, aria-haspopup
should also be true on a combobox.
Characteristics of aria-autocompleteCharacteristic | Value |
---|
Related Concepts: | XForms selection attribute in select |
Used in Roles: | textbox |
Value: | NMTOKEN |
Values of aria-autocompleteValue | Description |
---|
inline: | The system provides text after the caret as a suggestion for how to complete the field. |
list: | A list of choices appears from which the user can choose, but the edit box retains focus. |
both: | A list of choices appears and the currently selected suggestion also appears inline. |
none: | Only values from the value list can be selected. |
aria-busy
(state)
Indicates whether a live region is finished updating.
The default is that aria-busy
is false
. If authors know that multiple parts of the same live region need to be loaded, they can set aria-busy
to true
when the first part is loaded, and then set aria-busy
to false
or remove the attribute when the last part is loaded. If there is an error updating the live region, set the aria-invalid
attribute to true
.
Characteristics of aria-busyCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | boolean |
Values of aria-busyValue | Description |
---|
true: | The live region is still being updated. |
false: | There are no more expected updates for that live region. |
aria-checked
(state)
Characteristics of aria-checkedCharacteristic | Value |
---|
Used in Roles: | option |
Value: | NMTOKEN |
Values of aria-checkedValue | Description |
---|
true: | The element is checked. |
false: | The element supports being checked but is not currently checked. |
mixed: | Indicates a mixed mode value for a tri-state checkbox or menuitemcheckbox. |
undefined: | The element does not support being checked. |
aria-controls
(property)
Identifies the element (or elements) whose contents or presence are controlled by the current element. Also see aria-owns
.
For example:
- A tree view table of contents may control the contents of a neighboring help contents 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 of aria-controlsCharacteristic | Value |
---|
Related Concepts: | XML Events [XML-EVENTS] object hyperlink target in HTML [HTML] |
Used in Roles: | All elements of the base markup |
Value: | IDREFS |
aria-describedby
(property)
Identifies the element (or elements) that describes the object. Also see aria-labelledby
.
This is very similar to labeling an object with aria-labelledby
. A label should provide the user with the essence of what the object does, whereas a description is intended to provide detail that some users might need.
The element or elements referenced by the aria-describedby must entirely comprise the 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 of aria-describedbyCharacteristic | Value |
---|
Related Concepts: | Related concepts:
- Hint or Help in XForms [XForms]
- Label in XForms
- Label in HTML [HTML]
- online help
- HTML table cell headers
HTML label element, and HTML table cell headers are de facto describedby values.
|
Used in Roles: | All elements of the base markup |
Value: | IDREFS |
aria-disabled
(state)
Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. Also see aria-hidden
and aria-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. There SHOULD be a change of appearance (grayed out, etc.) to indicate that the item has been disabled.
The state of being disabled applies to the current element and all focusable descendant elements of the element on which the aria-disabled
attribute is applied.
Characteristics of aria-disabledCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | boolean |
Values of aria-disabledValue | Description |
---|
true: | The element and all focusable descendants are disabled and its value cannot be changed by the user. |
false: | The element is enabled. |
aria-dropeffect
(state)
Indicates the effect of a drag-and-drop operation when the dragged object is released on the drop target.
More than one drop effect may be supported for a given element. Therefore, the value of this attribute is a space-delimited set of tokens indicating the possible effects, or none
if there is no supported operation. In addition to setting the aria-dropeffect
attribute, authors SHOULD show a visual indication of potential drop targets.
Characteristics of aria-dropeffectCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | NMTOKENS |
Values of aria-dropeffectValue | Description |
---|
copy: | A duplicate of the source object will be dropped into the target. |
move: | The source object will be removed from its original location and dropped into the target. |
reference: | A reference or short cut to the dragged object will be created in the target object. |
execute: | A function supported by the drop target is executed, using the drag source as an input. |
popup: | There is a popup menu or dialog that allows the user to choose one of the drag operations (copy, move, reference, execute) and any other drag functionality, such as cancel. |
none: | No operation can be performed; effectively cancels the drag operation if an attempt is made to drop on this object. |
aria-expanded
(state)
Indicates whether an expandable/collapsible group of elements is currently expanded or collapsed.
For example, this indicates whether a portion of a tree is expanded or collapsed.
Characteristics of aria-expandedCharacteristic | Value |
---|
Related Concepts: | Tapered prompts in voice browsing. Switch in SMIL [SMIL]. |
Used in Roles: |
|
Value: | NMTOKEN |
Values of aria-expandedValue | Description |
---|
true: | The group is expanded. |
false: | The group is collapsed. |
undefined: | The group is neither expandable nor collapsible; all its child elements are shown or there are no child elements. |
aria-flowto
(property)
Identifies the next element (or elements) in the recommended reading order of content, overriding the general default to read in document source order.
When aria-flowto
has a single IDREF, it allows assistive technology to, at the user's request, forego normal document reading order and go to the targeted object. aria-flowto
in subsequent elements would follow a process similar to next focus in XHTML2 ([XHTML], Section 13). However, when aria-flowto
is provided with multiple IDREFS, they should be processed as path choices by the assistive technology, such as in a model based authoring tool.
In the case of one or more IDREFS, the user SHOULD be given the option, by a user agent or assistive technology, of navigating to any of the elements targeted. The name of the path can be determined by the name of the target element of the aria-flowto
attribute. accessibility APIs can provide named path relationships.
Characteristics of aria-flowtoCharacteristic | Value |
---|
Related Concepts: | XHTML 2 [XHTML2] :nextfocus :prevfocus |
Used in Roles: | All elements of the base markup |
Value: | IDREFS |
aria-grabbed
(state)
Indicates an element's "grabbed" state in a drag-and-drop operation.
When it is set to true
it has been selected for dragging, false
indicates that the element can be grabbed for a drag-and-drop operation, but is not currently grabbed, and undefined
(or no value) indicates the element cannot be grabbed (default).
When aria-grabbed
is set to true
, all potential drop targets should have their aria-dropeffect
attribute set appropriately. When an object is not grabbed (the value is set to false
, undefined
, or the attribute is removed), the aria-dropeffect
attributes of the associated drop targets SHOULD revert to none
.
Characteristics of aria-grabbedCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | NMTOKEN |
Values of aria-grabbedValue | Description |
---|
true: | Indicates that the element has been "grabbed" for dragging. |
false: | Indicates that the element supports being dragged. |
undefined: | Indicates that the element does not support being dragged. |
aria-hidden
(state)
Indicates that the element is not visible or perceivable to the user. Also see aria-disabled
.
If a menu is only visible after some user action, the aria-hidden
attribute should be set to true
until the menu is presented and the aria-hidden
attribute is removed, indicating that the menu is visible. This allows the assistive technology to properly skip hidden elements in the document.
It is recommended that authors key visibility of objects off this attribute, rather than change visibility and separately have to remember to update this property. CSS 2 provides a way to select on attribute values ([CSS], Section 5.8.1). The following CSS declaration makes content visible unless the aria-hidden
attribute is true
; scripts need only update the value of this attribute to change visibility:
[aria-hidden="true"] { visibility: hidden; }
Note: At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise to force the browser to redraw the styles properly.
Note: Authors are reminded that visibility:hidden and display:none apply to all CSS media types; therefore, use of either will hide the content from all renderers, regardless of modality. Authors using other techniques (for example, opacity or off-screen positioning) to visibly 'hide' content should ensure the aria-hidden
attribute is updated accordingly.
Characteristics of aria-hiddenCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | boolean |
Values of aria-hiddenValue | Description |
---|
true: | Indicates that this section of the document and its children are hidden from the rendered view. |
false: | Indicates that this section of the document is rendered. |
aria-invalid
(state)
Indicates the entered value does not conform to the format expected by the application.
If the value is computed to be invalid or out-of-range, the application SHOULD set this attribute to true
. User agents SHOULD inform the user of the error. Applications SHOULD provide suggestions for correction where they are known. User agents may refuse to submit the form as long as there is an element for which aria-invalid
is true
.
When the user attempts to submit data involving a field for which aria-required
is true
, the application may use the aria-invalid
attribute to signal there is an error. However, if the user has not attempted to submit the form, the aria-invalid
attribute should not be set on required widgets simply because the user has not yet entered data.
For future expansion, the aria-invalid
attribute is an enumerated type. Any value not recognized in the list of allowed values MUST be treated as if the value true
had been provided. If the attribute is not present, or its value is false
, or its value is an empty string, the default value of false
applies.
The aria-invalid
attribute applies only to the element on which it is applied, and does not inherit to descendant elements.
Characteristics of aria-invalidCharacteristic | Value |
---|
Related Concepts: | XForms [XForms] 'invalid' event http://www.w3.org/TR/2006/REC-xforms-20060314/slice4.html#evt-revalidate. Note: This state is true if a form field is required but empty. However, the XForms valid property would be set to false . |
Used in Roles: | All elements of the base markup |
Value: | NMTOKEN |
Values of aria-invalidValue | Description |
---|
grammar: | A grammatical error was detected. |
false: | There are no detected errors in the value. |
spelling: | A spelling error was detected. |
true: | The value entered by the user has failed validation. |
aria-label
(property)
Defines a string value that labels the current element. Also see aria-labelledby
.
A label should provide the user with the essence of what the object does. The most common accessibility API mapping for label is the accessible name property.
This is similar in concept to the aria-labelledby
attribute, which references a second element that labels the first. If the label text is visible on screen, authors SHOULD use aria-labelledby
and SHOULD NOT use aria-label
. Use aria-label
only if the interface is such that it is not possible to have a visible label on the screen
Characteristics of aria-labelCharacteristic | Value |
---|
Related Concepts: | A related concept is title in HTML [HTML]. |
Used in Roles: | All elements of the base markup |
Value: | string |
aria-labelledby
(property)
Identifies the element (or elements) that labels the current element. Also see aria-label
and aria-describedby
.
This is very similar to describing an object with aria-describedby
. A label should provide the user with the essence of what the object does, whereas a description is intended to provide additional information that some users might need.
Note: The expected spelling of this property in U.S. English is "labeledby." However, the accessibility API 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 of aria-labelledbyCharacteristic | Value |
---|
Related Concepts: | A related concept is label in XForms [XForms] and HTML [HTML]. |
Used in Roles: | All elements of the base markup |
Value: | IDREFS |
aria-level
(property)
Defines the hierarchical level of an element within a structure.
This can be applied inside trees to tree items, to headings inside a document, to nested grids, and to other structural items that may appear inside a container or participate in an ownership hierarchy. The value for aria-level
is an integer greater than or equal to 1.
Levels should increase with depth. If the DOM ancestry does not accurately represent the level, the aria-level
attribute should be maintained by the author.
This attribute is applied to leaf nodes (elements that would receive focus), not to the parent grouping element, even when all siblings are at the same level. 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, it is not always possible for authors to do so. Restricting this to leaf nodes ensures that there is a single way for assistive technology to use the attribute.
If the DOM ancestry accurately represents the level, the user 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 the aria-owns
attribute. User agent support for automatic calculation of level may vary; authors should test with user agents and assistive technology to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, they SHOULD omit this attribute.
Characteristics of aria-levelCharacteristic | Value |
---|
Used in Roles: |
|
Value: | integer |
aria-live
(property)
Indicates that an element will be updated, and describes the types of updates the user agent, assistive technology, and user can expect from the live region.
The values of this attribute are expressed in terms of politeness levels. Regions specified as polite
will notify users of updates but generally do not interrupt the current task, and updates take low priority. Use the assertive
value when the update needs to be communicated to the user more urgently, for example, warning or error messages in a form that does immediate validation for each form field.
Politeness levels are essentially an ordering mechanism for updates and serve as a strong suggestion to the user agent or assistive technology. The value may be overridden by the user agent, assistive technology, or user. For example, if the assistive technology can determine that a change occurred in response to a key press or a mouse click then the assistive technology may present that change immediately even if the value of the aria-live
attribute states otherwise.
Since different users have different needs, it is up to the user to tweak his or her assistive technology's response to a live region with a certain politeness level from the commonly defined baseline. Assistive technology may choose to implement increasing and decreasing levels of granularity so that the user can exercise control over queues and interruptions.
When the property is not set on an object that needs to send updates, the politeness level is the value of the nearest ancestor that sets the aria-live
attribute.
The aria-live
attribute is the primary determination for the order of presentation of changes to live regions. Implementations must also consider the default level of politeness in a role when the aria-live
attribute is not set in the ancestor chain (e.g. log
changes are polite
by default). Items which are assertive
should be presented immediately, followed by polite
items. Implementations may choose to clear queued changes when an "assertive" change occurs (e.g. changes in an assertive region may remove all currently queued changes).
Characteristics of aria-liveCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | NMTOKEN |
Values of aria-liveValue | Description |
---|
off: | Updates to the region should not be presented to the user. |
polite: | (Background change) This SHOULD be the default behavior for most live regions. Updates should be announced at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses their input typing. |
assertive: | This information has the highest priority and user agents SHOULD notify the user immediately. This may disorientate users causing them not to continue in their current task and as such should be used sparingly. |
aria-multiline
(property)
Indicates whether a text box accepts only a single line, or if it can accept multiline input.
There is very little difference in ARIA between single-line and multi-line text boxes, as both allow arbitrary text input. The main reason to indicate this is to warn of different behaviors of the enter key. In a multi-line text box, the enter key adds a new line; in a single-line text box, it does not and may activate a function outside the text box such as submitting the form.
Characteristics of aria-multilineCharacteristic | Value |
---|
Used in Roles: | textbox |
Value: | boolean |
Values of aria-multilineValue | Description |
---|
true: | This is a multi-line text box. |
false: | This is a single-line text box. |
aria-multiselectable
(property)
Indicates that the user may select more than one item from the current selectable descendants.
Lists, trees, and grids may allow users to select more than one item at a time.
Descendants that are selected SHOULD have the aria-selected
attribute set to true
. Descendants that are selectable but not selected SHOULD have the aria-selected
attribute set to false
. Descendants that are not selectable SHOULD NOT use the aria-selected
attribute.
Characteristics of aria-multiselectableCharacteristic | Value |
---|
Used in Roles: |
|
Value: | boolean |
Values of aria-multiselectableValue | Description |
---|
true: | More than one item in the widget may be selected at a time. |
false: | Only one item can be selected. |
aria-owns
(property)
Identifies an element (or elements) in order to define a visual or functional, contextual parent/child relationship among DOM elements where the DOM hierarchy cannot be used to represent the relationship.
The value of the aria-owns
attribute is a space-separated list of IDREFS that reference one or more elements in the document by ID. The reason for adding aria-owns
is to expose a parent/child contextual relationship to assistive technology that is otherwise impossible to infer from the DOM.
Authors SHOULD NOT use aria-owns
as a replacement for the DOM hierarchy. That is, if the relationship is captured by the DOM, then do not use aria-owns
.
Characteristics of aria-ownsCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | IDREFS |
aria-posinset
(property)
Defines an element's number or position in the current set of listitems or treeitems. Not required if inferred by the DOM. Also see aria-setsize
.
For example, if this element is the third item in a group then posinset
is 3
. The value for aria-posinset
is an integer greater than or equal to 1, and less than or equal to the size of the set.
If all items in a set are present in the document structure, it is not necessary to set this attribute, as the user 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, this property is needed to provide an explicit indication.
aria-posinset
SHOULD be used with aria-setsize
.
Characteristics of aria-posinsetCharacteristic | Value |
---|
Used in Roles: |
|
Value: | integer |
aria-pressed
(state)
Indicates the current "pressed" state of toggle buttons. Also see aria-checked
and aria-selected
.
Toggle buttons require a full press-and-release cycle to change their value. Activating it once changes the value to true
, and activating it another time changes the value back to false
. A value of mixed
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 in WAI-ARIA Best Practices [ARIA-PRACTICES]. If the attribute is not present, the button is not a toggle button.
The aria-pressed
attribute is similar but not identical to the aria-checked
attribute. Operating systems support pressed
on buttons and checked
on checkboxes.
Characteristics of aria-pressedCharacteristic | Value |
---|
Used in Roles: | button |
Value: | NMTOKEN |
Values of aria-pressedValue | Description |
---|
true: | The element is pressed. |
false: | The element supports being pressed but is not currently pressed. |
mixed: | Indicates a mixed mode value for a tri-state toggle button. |
undefined: | The element does not support being pressed. |
aria-readonly
(property)
Indicates that the element is not editable, but is otherwise operable. Also see aria-disabled
.
This means the user can read but not set the value of the widget. Readonly elements are relevant to the user, and applications SHOULD NOT restrict navigation to 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 of aria-readonlyCharacteristic | Value |
---|
Related Concepts: | XForms [XForms] Readonly |
Used in Roles: |
|
Value: | boolean |
Values of aria-readonlyValue | Description |
---|
true: | The user cannot change the value of the element. |
false: | The user can set the value of the element. |
aria-relevant
(property)
Indicates the nature of changes within a live region. Also see aria-atomic
.
The attribute is represented as a space delimited list of the following values: additions
, removals
, text
; or a single catch-all value all
.
This is used to describe semantically 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 meaningful event. In that case relevant should be set to all
. When the aria-relevant
attribute is not provided, the default is to assume that text and node additions are relevant, and that node removals are irrelevant.
Note: aria-relevant values of removals or all should be used sparingly. Assistive technology only wants to know of content going away if that it important such as a buddy leaving a chat room.
aria-relevant
is an optional attribute of live regions. This is a suggestion to the assistive technology, but the assistive technology is not required to present changes of all the relevant types.
Both accessibility APIs and the Document Object Model [DOM] provide events to allow the assistive technology to determine changed areas of the document.
When this value is not set, the value inherits from an object's nearest ancestor. It is not additive, meaning the set of values provided and omitted on an object completely override any inheritance of values.
Characteristics of aria-relevantCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | NMTOKENS |
Values of aria-relevantValue | Description |
---|
additions: | Nodes are added to the DOM within the region. |
removals: | Nodes are removed from the DOM. |
text: | Text is added or removed from the DOM. |
all: | Equivalent to the value "additions removals text". |
additions text: | Nodes are added or text is added to or removed from the DOM. |
aria-required
(property)
Indicates that user input is required on the element before a form may be submitted.
For example, if a user must fill in an address field, then aria-required
should be set to true
.
Note: The fact that the element is required is often presented visually (such as a sign or symbol after the widget). Using the aria-required
attribute allows the author to explicitly convey to an assistive technology that an element is required as opposed to using styling which is not deterministic.
The aria-required
attribute applies only to the element on which it is applied, and does not inherit to descendant elements.
Characteristics of aria-requiredCharacteristic | Value |
---|
Used in Roles: | All elements of the base markup |
Value: | boolean |
Values of aria-requiredValue | Description |
---|
true: | Users must provide input on an element before a form is submitted. |
false: | User input is not necessary to submit the form. |
aria-selected
(state)
Indicates the current "selected" state of various widgets. Also see aria-checked
and aria-pressed
.
This attribute is used single-selection and multiselectable widgets:
- Single selection containers where the currently focused item is not selected. The selection normally follows the focus, and is managed by the user agent. The author should only use
aria-selected
when the focused item is not in fact selected. The only useful value is false
because otherwise the currently focused item is considered to be selected. - Multi-selectable containers. Any selectable descendant of a container in which the
aria-multiselectable
attribute is true
must actively specify a value of either false
or true
for the aria-selected
attribute.
Characteristics of aria-selectedCharacteristic | Value |
---|
Used in Roles: |
|
Value: | NMTOKEN |
Values of aria-selectedValue | Description |
---|
true: | The selectable element is selected. |
false: | The selectable element is not selected. |
undefined: | The element is not selectable. |
aria-setsize
(property)
Defines the number of items in the current set of listitems or treeitems. Not required if inferred by the DOM. Also see aria-posinset
.
For example, if this element is in a group of six items at the same level then aria-setsize
is equal to 6. The value for aria-setsize
is an integer greater than or equal to 1.
This property is marked on the members of a set, not the container element that collects the members of the set. To orient a user by saying an element is "item X out of Y," the assistive technology would use X equal to the aria-posinset
attribute and Y equal to the aria-setsize
attribute.
If all items in a set are present in the document structure, it is not necessary to set this property, as the user 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.
aria-setsize
SHOULD be used with aria-posinset
.
Characteristics of aria-setsizeCharacteristic | Value |
---|
Used in Roles: | listitem |
Value: | integer |
aria-sort
(property)
Indicates if items in a table or grid are sorted in ascending or descending order.
This property should only be applied to table headers or grid headers. If the property is not provided, there is no defined sort order. For each table or grid, authors SHOULD apply aria-sort
to one only header at a time.
Characteristics of aria-sortCharacteristic | Value |
---|
Used in Roles: |
|
Value: | NMTOKEN |
Values of aria-sortValue | Description |
---|
ascending: | Items are sorted in ascending order by this column. |
descending: | Items are sorted in descending order by this column. |
none: | There is no defined sort applied to the column. |
other: | A sort algorithm other than ascending or descending has been applied. |
aria-valuemax
(property)
Defines the maximum allowed value for a range widget.
A range widget may start with a given value, which can be increased until a maximum value, defined by this property, is reached.
Declaring the minimum and maximum values allows alternate devices to react to arrow keys, validate the current value, or simply let the user know the size of the range. If the aria-valuenow
has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax
and aria-valuemin
.
Characteristics of aria-valuemaxCharacteristic | Value |
---|
Related Concepts: | XForms [XForms] range |
Used in Roles: |
|
Value: | decimal |
aria-valuemin
(property)
Defines the minimum allowed value for a range widget.
A range widget may start with a given value, which can be decreased until a minimum value, defined by this property, is reached.
Declaring the minimum and maximum values allows alternate devices to react to arrow keys, validate the current value, or simply let the user know the size of the range. If the aria-valuenow
has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax
and aria-valuemin
.
Characteristics of aria-valueminCharacteristic | Value |
---|
Related Concepts: | XForms [XForms] range |
Used in Roles: |
|
Value: | decimal |
aria-valuenow
(property)
Defines the current value for a range widget. Also see aria-valuetext
.
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 author SHOULD NOT set the aria-valuenow
attribute. If the aria-valuenow
attribute is absent, no information is implied about the current value. If the aria-valuenow
has a known maximum and minimum, the author SHOULD provide properties for aria-valuemax
and aria-valuemin
.
The value of aria-valuenow
is a decimal number. If the range is a set of numeric values, then aria-valuenow
is one of those values. For example, if the range is [0, 1], a valid aria-valuenow
is 0.5. A value outside the range, such as -2.5 or 1.1, is invalid.
If the range is a set of qualitative string values, such as "small", "medium", and "large", then aria-valuenow
is an index that chooses one of the set. The aria-valuetext
property should be used in conjunction with aria-valuenow
to provide a user friendly representation of the range's current value. In the current example, this would be one of the strings "small", "medium", or "large".
Characteristics of aria-valuenowCharacteristic | Value |
---|
Related Concepts: | XForms [XForms] range, start |
Used in Roles: |
|
Value: | decimal |
aria-valuetext
(property)
Defines the human readable text equivalent of aria-valuenow
for a range widget.
Used, for example, on a range widget such as a slider or progress bar.
If the aria-valuetext
attribute is set, authors SHOULD also set the aria-valuenow
attribute, unless that value is unknown (for example, on an indeterminate progressbar
).
The aria-valuetext
should only be set by authors when the rendered slider value cannot be completely represented in the form of a number. For example, a slider may have rendered values of "small", "medium", and "large". In this instance the values of aria-valuenow
range from 1 through 3, which indicate the position of each value in the value space, but the aria-valuetext
would be one of the strings: small
, medium
, or large
. If the aria-valuetext
attribute is absent, the assistive technology will rely solely on the aria-valuenow
attribute for the current value.
Characteristics of aria-valuetextCharacteristic | Value |
---|
Related Concepts: | XForms [XForms] range, start |
Used in Roles: |
|
Value: | string |
6. Implementation in Host Languages
This section is normative.
The roles, states, and properties defined in this specification do not form a whole web language or format. They are intended to be used in the context of a host language. This section discusses what host languages should do to implement WAI-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, we believe we have maintained consistency in how the WAI-ARIA information looks to authors and how it is manipulated in the DOM by scripts.
ARIA roles, states, and properties are implemented as attributes of elements. Roles are applied by placing their names among the tokens appearing in the value of a host-language-provided role
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.
6.1. General Requirements for Implementation in Host Languages
6.1.1. Role Attribute
An implementing host language will provide an attribute with the following characteristics:
- The attribute name MUST be
role
; - The attribute value MUST allow a space-separated sequence of whitespace-free substrings;
- The appearance of the name literal of any concrete ARIA role (see section 7.3.2) as one of these substrings MUST NOT in and of itself make the attribute value illegal in the host-language syntax; and
- If the name literal of a concrete ARIA role appears as one of the substrings in the space-separated list in the
role
attribute, the role MUST be processed in accordance with this specification.
6.1.2. State and Property Attributes
An implementing host language MUST allow attributes with the following characteristics:
- The attribute name is the name of any state or property identified in the Supported States and Properties section, such as
aria-busy
, aria-selected
, aria-activedescendant
, aria-valuetext
; - The syntax MUST NOT prevent the attribute from appearing anywhere that it is applicable, as specified in this specification;
- When these attributes appear in a document instance, the attributes MUST be processed as defined in this specification.
Following the Namespaces Recommendation [XML-NAMES], 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 the DOM interface getAttributeNS
for example, treats an empty string (""
) as representing this condition, so that both getAttribute("aria-busy")
and getAttributeNS("", "aria-busy")
access the same aria-busy
attribute in the DOM.
6.1.3. Focus Navigation
An implementing host language MUST provide support for the author to make arbitrary elements focusable, such as the tabindex
attribute in HTML.
- The user to have device-independent capability and, in particular, keyboard capability to navigate the focus to all focusable elements.
6.1.4. Resolving Conflicts with Host Languages
If the host language incorporates ARIA support and there is a conflict between a host language feature and an ARIA feature, assistive technology should assign preference to the ARIA feature.
6.2. Implementation Using the Modularization Recommendation
Host languages can be constructed using the methods of XHTML™ 1.1 Modularization [XHTMLMOD].
Host languages that are constructed following this recommendation MUST implement the abstract module comprising the attributes defined in section 5 above using a module implementation provided by this specification.
Appendix 8.1.2 below provides an implementation of this module as a DTD module. Appendix 8.1.4 below provides an implementation of this module as a Schema module.
Appendix 8.1.3 below is a sample DTD integrating a language profile that implements WAI-ARIA by including the DTD module. Note how the applicability of the tabindex
attribute has been extended to ensure all elements can be made focusable.
8. Quality Assurance
This section is informative.
This section sets out normative conditions for conforming document instances and user agent processors, along with informative remarks about the role of other processors such as authoring tools and assistive technology.
8.1. Applicable WAI-ARIA Role
8.1.1. Requirement is Functional
As discussed above in section 6.1.1, an implementing host language will provide a role attribute with a value which will be a space-separated sequence of tokens. If the element does not have a role attribute, or if the role attribute contains no tokens matching the name of a concrete ARIA role, zero ARIA roles will be applied.
8.1.2. Overview
The applicable ARIA role is the concrete ARIA role whose name is matched by the first token in the sequence of tokens in the role
attribute value which matches, on case-sensitive comparison, the name of any concrete ARIA role.
A concrete ARIA role is any of the role types described above except abstract roles (roles for which isAbstract
is true) and the roles imported from the Role Module, that is those that are introduced in sections 4.4.6 and 4.4.7.
8.1.3. Step-by-Step
The following steps will correctly identify the applicable ARIA role.
- The rules of the host language are used to detect that an element has an attribute with attribute name of
role
and to identify the attribute value string for that attribute. - The attribute value string for that attribute is broken into a sequence of whitespace-free substrings by separating on whitespace.
- The substrings are compared in a case-sensitive comparison with all the names of concrete ARIA roles as defined above.
- The first such substring in textual order that matches the name of a concrete ARIA role is the name of the applicable ARIA role.
8.1.4. Explicit WAI-ARIA Role Rules
The applicable ARIA role, if there is one, MUST be the role value which is mapped to the value of a role property in any accessibility API which accepts only one role value. User agents MUST use an explicit applicable ARIA role as overriding any implicit role inferred from the host language markup in performing this mapping. Note that, in conformance with section 7.3.1 above, this overriding does not result in any changes in the DOM, only in the accessibility API representation of the document.
8.2. Accessibility API Mapping
User agents SHOULD expose role, state, and property information provided by the author to accessibility APIs available in their operating system. Refer to Mapping States and Properties to Accessibility APIs ([ARIA-PRACTICES], Section 3.5) for guidance about how to expose this information. This requirement parallels User Agent Accessibility Guidelines 1.0 Section 6.3: Programmatic Access to non-HTML/XML Content ([UAAG], Section 6.3), except that it applies even to HTML and XML content.
Note: Not all platforms provide interfaces that map to all the roles, states, and properties defined in this specification. User agents should expose those roles, states, and properties that are supported. The remaining roles, states, and properties are available to assistive technology via the DOM, for those that provide explicit support for this specification.
8.3. Authoring Practices
8.3.2. Testing 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 to the operations of the widgets and applications, and display and API visibility into all changes of the widgets and applications during user interaction.