1.
Introduction
This section is non-normative.
The goals of this specification include:
expanding the accessibility information that may be supplied by the author;
requiring that supporting host languages provide full keyboard support that may be implemented in a device-independent way, for example, by telephones, handheld devices, e-book readers, and televisions;
improving the accessibility of dynamic content generated by scripts; and
providing for interoperability with
assistive technologies
WAI-ARIA
is a technical specification that provides a framework to improve the accessibility and interoperability of web content and applications. This document is primarily for developers creating custom widgets and other web application components. Please see the
WAI-ARIA
Overview
for links to related documents for other audiences, such as
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] that introduces developers to the accessibility problems that
WAI-ARIA
is intended to solve, the fundamental concepts, and the technical approach of
WAI-ARIA
This draft currently handles two aspects of
roles
: user interface functionality and structural
relationships
. For more information and use cases, see [
wai-aria-practices-1.1
] 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
APIs
. Reference to roles found in this taxonomy by dynamic web content may be used to support interoperability with assistive technologies.
The schema to support this standard has been designed to be extensible so that custom roles can be created by extending base roles. This 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 [
xmlschema-2
]. However, being able to define similarities between roles, such as
baseConcepts
and more descriptive definitions, would not be available in
XSD
WAI-ARIA
1.1 is a member of the
WAI-ARIA
1.1 suite
that defines how to expose semantics of
WAI-ARIA
and other web content languages to
APIs
1.1
Rich Internet Application Accessibility
The domain of web accessibility defines how to make web content usable by persons with disabilities. Persons with certain types of disabilities use
assistive technologies
AT
) to interact with content. Assistive technologies can transform the presentation of content into a format more suitable to the user, and can allow the user to interact in different ways. For example, the user may need to, or choose to, interact with a slider widget via arrow keys, instead of dragging and dropping with a mouse. In order to accomplish this effectively, the software needs to understand the
semantics
of the content. Semantics is the science of meaning; in this case, used to assign roles, states, and properties that apply to user interface and content elements as a human would understand. For instance, if a paragraph is semantically identified as such, assistive technologies can interact with it as a unit separable from the rest of the content, knowing the exact boundaries of that paragraph. An adjustable range slider or collapsible list (a.k.a. a tree
widget
) are more complex examples, in which various parts of the widget have semantics that need to be properly identified for assistive technologies to support effective interaction.
New technologies often overlook semantics required for accessibility, and new authoring practices often misuse the intended semantics of those technologies.
Elements
that have one defined meaning in the language are used with a different meaning intended to be understood by the user.
For example, web application developers create collapsible tree widgets in
HTML
using
CSS
and JavaScript even though
HTML
has no semantic
tree
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 assistive technologies may not recognize the role. Similarly, web application developers create interactive button widgets in
SVG
using JavaScript even though
SVG
has no semantic
button
element. To a non-disabled user, it may look and act like a button widget, but without appropriate semantics, the button widget may not be
perceivable
to, or
operable
by, a person with a disability because assistive technologies may not recognize the role.
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 technologies. 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 semantics inherited from the implementing host language. Roles are a common property of platform
APIs
which assistive technologies use 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 the
attributes
each role supports. Information about mapping of roles to accessibility
APIs
is provided by the
Core Accessibility
API
Mappings 1.1
core-aam-1.1
].
Roles are element types and will not change with time or user actions. Role information is used by assistive technologies, through interaction with the user agent, to provide normal processing of the specified element type.
States and properties are used to declare important attributes of an element that affect and describe interaction. They enable the
user agent
and operating system to properly handle the element even when the attributes are dynamically changed by client-side scripts. For example, alternative input and output technology, such as screen readers and speech dictation software, need to be able to recognize and effectively manipulate and communicate various interaction states (e.g., disabled, checked) to the user.
While it is possible for assistive technologies to access these properties directly through 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
Core Accessibility
API
Mappings 1.1
core-aam-1.1
] and the
Accessible Name and Description: Computation and
API
Mappings 1.1
accname-aam-1.1
] for details.
Figure 1.0 illustrates the relationship between user agents (e.g., browsers), accessibility
APIs
, and assistive technologies. It describes the "contract" provided by the user agent to assistive technologies, which 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). The
DOM
, usually
HTML
, acts as the data model and view in a typical model-view-controller relationship, and JavaScript acts as the controller by manipulating the style and content of the displayed data. The user agent conveys relevant information to the operating system's accessibility
API
, which can be used by any assistive technologies, such as screen readers.
Figure 1: The contract model with accessibility
APIs
For more information see
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for the use of roles in making interactive content accessible.
In addition to the prose documentation, the role taxonomy is provided in
Web Ontology Language (
OWL
owl-features
], which is expressed in
Resource Description Framework (
RDF
rdf-concepts
]. Tools can use these to validate the implementation of roles in a given content document. For example, instances of some roles are expected to be children of a specific parent role. Also, some roles may support a 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, and
RDF
OWL
processing is not essential to interoperable implementation of this specification. A future version of
WAI-ARIA
is expected to define how to extend roles.
Users of alternate input devices need
keyboard accessible
content. The new semantics, when combined with the recommended keyboard interactions provided in
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
], will allow alternate input solutions to facilitate command and control via an alternate input solution.
WAI-ARIA
introduces navigational
landmarks
through its taxonomy and the
XHTML
role landmarks, which can help persons with dexterity and vision impairments by providing for improved keyboard navigation.
WAI-ARIA
may also be used to assist persons with cognitive learning disabilities. The additional semantics allow authors to restructure and substitute alternative content as needed.
Assistive technologies
need the ability to support alternative inputs by getting and setting the current value of
widget
states and properties. Assistive technologies also need to determine what
objects
are selected and manage widgets that allow multiple selections, such as list boxes and grids.
Speech-based command and control systems can benefit from
WAI-ARIA
semantics like the
role
attribute to assist in conveying audio information to the user. For example, upon encountering an element with a role of
with child elements of role
menuitem
each containing text content representing a different flavor, a speech system might state to the user, "Select one of three choices: chocolate, strawberry, or vanilla."
WAI-ARIA
is intended to be used as a supplement for native language semantics, not a replacement. When the host language provides a feature that provides equivalent accessibility to the
WAI-ARIA
feature, use the host language feature.
WAI-ARIA
should only be used in cases where the host language lacks the needed
role
state
, and
property
indicators. Use a host language feature that is as similar as possible to the
WAI-ARIA
feature, then refine the meaning by adding
WAI-ARIA
. For instance, a multi-selectable grid could be implemented as a table, and then
WAI-ARIA
used to clarify that it is an interactive grid, not just a static data table. This allows for the best possible fallback for user agents that do not support
WAI-ARIA
and preserves the integrity of the host language semantics.
1.2
Target Audience
This specification defines the basic model for
WAI-ARIA
, including roles, states, properties, and values. It impacts several audiences:
User agents
that process content containing
WAI-ARIA
features;
Assistive technologies
that present content in special ways to user with disabilities;
Authors who create content;
Authoring tools that help authors create conforming content; and
Conformance checkers that verify appropriate use of
WAI-ARIA
Each conformance requirement indicates the audience to which it applies.
Although this specification is applicable to the above audiences, it is not specifically targeted to, nor is it intended to be the sole source of information for, any of these audiences. The following documents provide important supporting information:
1.3
User Agent Support
WAI-ARIA
relies on user agent support for its features in two ways:
Aside from using
WAI-ARIA
markup to improve what is exposed to accessibility
APIs
, user agents behave as they would natively. Assistive technologies react to the extra information in the accessibility
API
as they already do for the same information on non-web content. User agents that are not assistive technologies, however, need do nothing beyond providing appropriate updates to the accessibility
API
The
WAI-ARIA
specification neither requires nor forbids user agents from enhancing native presentation and interaction behaviors on the basis of
WAI-ARIA
markup. Mainstream user agents might expose
WAI-ARIA
navigational landmarks (for example, as a dialog box or through a keyboard command) with the intention to facilitate navigation for all users. User agents are encouraged to maximize their usefulness to users, including users without disabilities.
WAI-ARIA
is intended to provide missing semantics so that the intent of the author may be conveyed to assistive technologies. Generally, authors using
WAI-ARIA
will provide the appropriate presentation and interaction features. Over time, host languages may add
WAI-ARIA
equivalents, such as new form controls, that are implemented as standard accessible user interface controls by the user agent. This allows authors to use them instead of custom
WAI-ARIA
enabled user interface components. In this case the user agent would support the native host language feature. Developers of host languages that implement
WAI-ARIA
are advised to continue supporting
WAI-ARIA
semantics when they do not adversely conflict with implicit host language semantics, as
WAI-ARIA
semantics more clearly reflect the intent of the author if the host language features are inadequate to meet the author's needs.
1.4
Co-Evolution of
WAI-ARIA
and Host Languages
WAI-ARIA
is intended to augment semantics in supporting languages like [
html5
] and [
SVG2
], or to be used as an accessibility enhancement technology in other markup-based languages that do not explicitly include support for ARIA. It clarifies semantics to assistive technologies when authors create new types of objects, via style and script, that are not yet directly supported by the language of the page, because the invention of new types of objects is faster than standardized support for them appears in web languages.
It is not appropriate to create objects with style and script when the host language provides a semantic element for that type of object. While
WAI-ARIA
can improve the accessibility of these objects, accessibility is best provided by allowing the user agent to handle the object natively. For example, it's better to use an
h1
element in
HTML
than to use the
heading
role on a
div
element.
It is expected that, over time, host languages will evolve to provide semantics for objects that currently can only be declared with
WAI-ARIA
. This is natural and desirable, as one goal of
WAI-ARIA
is to help stimulate the emergence of more semantic and accessible markup. When native semantics for a given feature become available, it is appropriate for authors to use the native feature and stop using
WAI-ARIA
for that feature. Legacy content may continue to use
WAI-ARIA
, however, so the need for user agents to support
WAI-ARIA
remains.
While specific features of
WAI-ARIA
may lose importance over time, the general possibility of
WAI-ARIA
to add semantics to web pages is expected to be a persistent need. Host languages may not implement all the semantics
WAI-ARIA
provides, and various host languages may implement different subsets of the features. New types of objects are continually being developed, and one goal of
WAI-ARIA
is to provide a way to make such objects accessible, because web authoring practices often advance faster than host language standards. In this way,
WAI-ARIA
and host languages both evolve together but at different rates.
Some host languages exist to create semantics for features other than the user interface. For example,
SVG
expresses the semantics behind production of graphical objects, not of user interface components that those objects may represent; XForms provides semantics for form controls and does not provide wider user interface features. Host languages such as these might, by design, not provide native semantics that map to
WAI-ARIA
features. In these cases,
WAI-ARIA
could be adopted as a long-term approach to add semantic information to user interface components.
1.5
Authoring Practices
The accessibility of interactive content cannot be confirmed by static checks alone. Developers of interactive content should test for device-independent access to
widgets
and applications, and should verify accessibility
API
access to all content and changes during user interaction.
1.6
Assistive Technologies
Programmatic access to accessibility semantics is essential for assistive technologies. Most assistive technologies interact with user agents, like other applications, through a recognized accessibility
API
. Perceivable objects in the user interface are exposed to assistive technologies as accessible objects, defined by the accessibility
API
interfaces. To do this properly, accessibility information – role, states, properties as well as contextual information – needs to be accurately conveyed to the assistive technologies through the accessibility
API
. When a state change occurs, the user agent provides the appropriate event notification to the accessibility
API
. Contextual information, in many host languages like
HTML
, can be determined from the
DOM
itself as it provides a contextual tree hierarchy.
While some assistive technologies interact with these accessibility
APIs
, others may access the content directly from the
DOM
. These technologies can restructure, simplify, style, or reflow the content to help a different set of users. Common use cases for these types of adaptations may be the aging population, persons with cognitive impairments, or persons in environments that interfere with use of their tools. For example, the availability of regional navigational landmarks may allow for a mobile device adaptation that shows only portions of the content at any one time based on its semantics. This could reduce the amount of information the user needs to process at any one time. In other situations it may be appropriate to replace a custom user interface control with something that is easier to navigate with a keyboard, or touch screen device.
2.
Using
WAI-ARIA
This section is non-normative.
Complex web applications become inaccessible when
assistive technologies
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
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
]).
WAI-ARIA
divides the semantics into
roles
(the type defining a user interface element) and
states
and
properties
supported by the roles.
Authors need to associate
elements
in the document to a
WAI-ARIA
role and the appropriate states and properties (aria-*
attributes
) during its life-cycle, unless the elements already have the appropriate
implicit
WAI-ARIA
semantics
for states and properties. In these instances the equivalent host language states and properties take precedence to avoid a conflict while the role attribute will take precedence over the implicit role of the host language element.
2.1
WAI-ARIA
Roles
WAI-ARIA
role
is set on an
element
using a
role
attribute
, similar to the
role
attribute defined in
Role Attribute
role-attribute
].
Example 1
li
role
"menuitem"
Open file…
li
The roles defined in this specification include a collection of
document landmarks
and the
WAI-ARIA
role taxonomy
The roles in this
taxonomy
and their expected behaviors are modeled using
RDF
OWL
owl-features
]. 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
is contained 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
aria-checked
).
Attaching a role gives
assistive technologies
information about how to handle each element.
2.2
WAI-ARIA
States and Properties
WAI-ARIA
provides a collection of accessibility
states
and
properties
which are used to support platform
APIs
on various operating system platforms.
Assistive technologies
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 technologies with user interface information to convey to the user at any time. Changes in states or properties will result in a notification to assistive technologies, which could alert the user that a change has occurred.
In the following example, a list item (
html:li
) has been used to create a checkable menu item, and JavaScript
events
will capture mouse and keyboard events to toggle the 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.
Example 2
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 are managed by the user agent, such as
aria-posinset
and
aria-setsize
, but the author can 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
([
css3-selectors
]), and can allow the author to create
UI
changes based on
WAI-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 the text is bold and an image of a check mark is shown, based on the value of the
aria-checked
attribute.
Example 3
[aria-checked="true"] { font-weight: bold; }
[aria-checked="true"]::before { background-image: url(checked.gif); }
If
CSS
is not used to toggle the visual representation of the check mark, the author could include additional markup and scripts to manage an image that represents whether or not the
menuitemcheckbox
is checked.
Example 4
aria-checked=
"true"
img
src
"checked.gif"
role
"presentation"
alt
""
Sort by Last Modified
li
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. Authors are advised to
not
destroy the element with focus or scroll it off-screen unless through user intervention. All interactive
objects
should be focusable. All parts of composite interactive controls need to be focusable or have a documented alternative method to achieve their function, such as a keyboard shortcut. Authors are advised to maintain an obvious, discoverable way, either through tabbing or other standard navigation techniques, for keyboard users to move the focus to any interactive element. See
User Agent Accessibility Guidelines, Guideline 9
([
UAAG10
], Guideline 9).
When using standard
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.
SVG
Tiny provides a similar navigation "ring" mechanism that by default follows document order and which should be implemented using system dependent input facilities (the TAB key on most desktop computers).
SVG
authors may place elements in the navigation order by manipulating the
focusable
attribute and they may dynamically
specify the navigation order
by modifying elements'
navigation attributes
WAI-ARIA
includes a number of "managing container" widgets, also known as "composite" widgets. When appropriate, the container is responsible for tracking the last descendant that was active (the default is usually the first item in the container). It is essential that a container maintain a usable and consistent strategy when focus leaves a container and is then later refocused. While there may be exceptions, it is recommended that when a previously focused container is refocused, the active descendant be the same element as the active descendant when the container was last focused. Exceptions include cases where the contents of a container widget have changed, and widgets like a menubar where the user expects to always return to the first item when focus leaves the menu bar. For example, if the second item of a tree group was the active descendant when the user tabbed out of the tree group, then the second item of the tree group remains the active descendant when the tree group gets focus again. The user may also activate the container by clicking on one of the descendants within it.
When the container or its active descendant has focus, the user may navigate through the container by pressing additional keys, such as the arrow keys, to change the currently active descendant. Any additional press of the main navigation key (generally 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 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.
Content authors are required to manage focus on the following container roles:
More information on managing focus can be found in the
Developing a Keyboard Interface
section of the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
].
3.
Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
and notes in this specification are non-normative. Everything else in this specification is
normative.
The key words
MAY
MUST
MUST NOT
SHOULD
, and
SHOULD NOT
are
to be interpreted as described in [
RFC2119
].
This specification indicates whether a section is
normative
or
informative
. Classifying a section as normative or informative applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.
Normative sections provide requirements that authors, user agents, and assistive technologies
MUST
follow for an implementation to conform to this specification.
Informative sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.
3.1
Non-interference with the Host Language
WAI-ARIA
processing by the
user agent
MUST NOT
interfere with the normal operation of the built-in features of the host language.
If a
CSS
selector includes a
WAI-ARIA
attribute (e.g.,
input[aria-invalid="true"]
), user agents
MUST
update the visual display of any elements matching (or no longer matching) the selector any time the attribute is added/changed/removed in the
DOM
. The user agent
MAY
alter the mapping of the host language features into an
API
, but the user agent
MUST NOT
alter the
DOM
in order to remap
WAI-ARIA
markup into host language features.
3.2
All
WAI-ARIA
in
DOM
A conforming
user agent
which implements a document object model that does not conform to the
W3C
DOM
specification
MUST
include the content attribute for role and its
WAI-ARIA
role values
, as well as the
WAI-ARIA
States and Properties
in the
DOM
as specified by the author, even though processing may affect how the elements are exposed to accessibility
APIs
. Doing so ensures that each role attribute and all
WAI-ARIA
states and properties, including their values, are in the document in an unmodified form so other tools, such as assistive technologies, can access them. A conforming
W3C
DOM
meets this criterion.
3.3
Assistive Technology Notifications Communicated to Web Applications
Assistive technologies
, such as speech recognition systems and alternate input devices for users with mobility impairments, require the ability to control a web application in a device-independent way.
WAI-ARIA
states
and
properties
reflect the current state of rich internet application components. The ability for assistive technologies to notify web applications of necessary changes is essential because it allows these alternative input solutions to control an application without being dependent on the standard input device which the user is unable to effectively control directly.
User agents
MUST
provide a method to notify the web application when a change occurs to states or properties in the system accessibility
API
. Likewise, web application authors
SHOULD
update the web application accordingly when notified of a change request from the user agent or assistive technology.
Note
Many state and properties can be changed by assistive technologies through existing accessibility
APIs
by responding to a default action event. For example, the
aria-selected
state of a
tab
in a
tabpanel
can be changed by triggering the default action on the element.
3.4
Conformance Checkers
Any application or script verifying document conformance or validity
SHOULD
include a test for all of the
normative
author requirements in this specification. If testing for a given requirement, conformance checkers
MUST
issue an error if an author "
MUST
" requirement isn't met, and
MUST
issue a warning if an author "
SHOULD
" requirement isn't met.
3.5
Deprecated Requirements
As the technology evolves, sometimes new ways to meet a use case become available, that work better than a feature that was previously defined. But because of existing implementation of the older feature, that feature cannot be removed from the conformance model without rendering formerly conforming content non-conforming. In this case, the older feature is marked as "deprecated". This indicates that the feature is allowed in the conformance model and expected to be supported by user agents, but it is recommended that authors do not use it for new content. In future versions of the specification, if the feature is no longer widely used, the feature could be removed and no longer expected to be supported by user agents.
5.
The Roles Model
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
Schemata Appendix
The roles, their characteristics, the states and properties they support, and specification of how they may be used in markup, shall be considered normative. The
RDF
OWL
representation used to model the taxonomy shall be considered informative. The
RDF
OWL
taxonomy may be used as a vehicle to extend
WAI-ARIA
in the future or by tool manufacturers to validate states and properties applicable to roles per this specification.
Roles are element types and authors
MUST NOT
change role values over time or with user actions. Authors wishing to change a role
MUST
do so by deleting the associated element and its children and replacing it with a new element with the appropriate role. Typically, platform accessibility
APIs
do not provide a vehicle to notify assistive technologies of a role value change, and consequently, assistive technologies may not update their cache with the new role attribute value.
In order to reflect the content in the
DOM
, user agents
SHOULD
map the role attribute to the appropriate value in the implemented accessibility
API
, and user agents
SHOULD
update the mapping when the role attribute changes.
5.1
Relationships Between Concepts
The
role
taxonomy
uses the following relationships to relate
WAI-ARIA
roles to each other and to concepts from other specifications, such as
HTML
and XForms.
5.1.1
Superclass Role
Inheritance is expressed in
RDF
using the
RDF
Schema 1.1
subClassOf
([
rdf-schema
]) property.
RDF
Property
rdfs:subClassOf
The
role
that the current subclassed role extends in the
taxonomy
. This extension causes all the properties and constraints of the superclass role to propagate to the subclass role. Other than well known stable specifications, inheritance may be restricted to items defined inside this specification, so that external items cannot be changed and affect inherited
classes
5.1.2
Subclass Roles
RDF
Property
Informative list of
roles
for which this role is the superclass. This is provided to facilitate reading of the specification but adds no new information.
5.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
related concept
except that the base concept is almost identical to the role definition.
For example, the
checkbox
defined in this document has similar functionality and anticipated behavior to a
checkbox defined in
HTML
. Therefore, a
checkbox
has an
HTML
checkbox
as a
baseConcept
. However, if the original
HTML
checkbox baseConcept definition is modified, the definition of a
checkbox
in this document will not be affected, because there is no actual inheritance of the respective type.
5.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, and what instances 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.
5.2.1
Abstract Roles
RDF
Property
N/A
Values
Boolean
Abstract
roles
are the foundation upon which all other
WAI-ARIA
roles are built. Content authors
MUST NOT
use abstract roles because they are not implemented in the
API
binding. User agents
MUST NOT
map abstract roles to the standard role mechanism of the accessibility
API
. 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.
5.2.2
Required States and Properties
RDF
Property
role:requiredState
Values
Any valid
RDF
object reference, such as a
URI
States
and
properties
specifically required for the
role
and subclass roles. Content authors
MUST
provide a non-empty
value
for required states and properties. Content authors
MUST NOT
use the value
undefined
for required states and properties, unless
undefined
is an explicitly-supported value of that state or property.
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.
5.2.3
Supported States and Properties
RDF
Property
role:supportedState
Values
Any valid
RDF
object reference, such as a
URI
States
and
properties
specifically applicable to the
role
and child roles.
User agents
MUST
map all supported states and properties for the role to an accessibility
API
. Content authors
MAY
provide
values
for supported states and properties, but need not in some cases where default values are sufficient.
5.2.4
Inherited States and Properties
Informative list of properties that are inherited onto a
role
from superclass roles.
States
and
properties
are inherited from superclass 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. The set of supported states and properties combined with inherited states and properties forms the full set of states and properties supported by the role.
5.2.5
Required Owned Elements
RDF
Property
role:mustContain
Values
Any valid
RDF
object reference, such as a
URI
Any
element
that will be
owned
by the element with this
role
. For example, an element with the role
list
will own at least one element with the role
group
or
listitem
When multiple roles are specified as
required owned elements
for a role, at least one instance of one required owned element is expected. This specification does
not
require an instance of each of the listed owned roles. For example, a
should have at least one instance of a
menuitem
menuitemcheckbox
or
menuitemradio
. The
role does not require one instance of each.
There may be times that required owned elements are missing, for example, while editing or while loading a data set. When a widget is missing
required owned elements
due to script execution or loading, authors
MUST
mark a containing element with
aria-busy
equal to
true
. For example, until a page is fully initialized and complete, an author could mark the document element as busy.
Note
A role that has 'required owned elements' does not imply the reverse relationship. While processing of a role may be incomplete without elements of given roles present as descendants, elements with roles in this list do not always have to be found within elements of the given role. See
required context role
for requirements about the context where elements of a given role will be contained.
Note
An element with a
subclass role
of the 'required owned element' does not fulfill this requirement. For example, the
list
role requires ownership of an element using either the
listitem
or
group
role. Although the
group
role is the superclass of
row
, adding a owned element with a role of
row
will not fulfill the requirement that
list
must own a
listitem
or a
group
5.2.6
Required Context Role
RDF
Property
role:scope
Values
Any valid
RDF
object reference, such as a
URI
The required context role defines the owning container where this
role
is allowed. If a role has a required context, authors
MUST
ensure that an element with the role is contained inside (or
owned
by) an element with the required context role. For example, an element with role
listitem
is only meaningful when contained inside (or owned by) an element with role
list
Note
A role that has 'required context role' does not imply the reverse relationship. While an element with the given role needs to appear within an element of the listed role(s) in order to be meaningful, elements of the listed roles do not always need descendant elements of the given role in order to be meaningful. See
required owned elements
for requirements about elements that require presence of a given descendant to be processed properly.
5.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, the
aria-labelledby
attribute, or the host language labeling mechanism, such as the
alt
or
title
attributes in
HTML
, with
HTML
title
attribute having the lowest precedence for specifying a text alternative.
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 higher priority "author" features are not provided. Priority is defined by the
text alternative computation
algorithm.
5.2.7.3
Text Alternative Computation
Text Alternative Computation
is defined in the Accessible Name and Description specification [
accname-aam-1.1
].
5.2.7.4
Roles Supporting Name from Author
All roles support name from author with two exceptions. The roles that do not support name from author are
presentation
and
none
5.2.7.5
Roles Supporting Name from Content
5.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
API
. If
user agents
do not hide the descendant nodes, some information may be read twice.
5.2.9
Implicit Value for Role
Many states and properties have default values. Occasionally, the default value when used on a given role should be different from the usual default. Roles that require a state or property to have a non-standard default value indicate this in the "Implicit Value for Role". This is expressed in the form "
state or property name
is
new default value
". Roles that define this have the new default value for the state or property if the author does not provide an explicit value.
5.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.). Note that some assistive technologies provide special modes of interaction for regions marked with role
application
or
document
Roles are categorized as follows:
Abstract Roles
Widget Roles
Document Structure Roles
Landmark Roles
Live Region Roles
Window Roles
5.3.1
Abstract Roles
The following
roles
are used to support the
WAI-ARIA
role
taxonomy
for the purpose of defining general role concepts.
Abstract roles are used for the ontology. Authors
MUST NOT
use abstract roles in content.
5.3.3
Document Structure
The following
roles
describe structures that organize content in a page. Document structures are not usually interactive.
5.3.4
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 all are imported from the
Role Attribute
role-attribute
]. The roles are included here in order to make them clearly part of the
WAI-ARIA
Role
taxonomy
5.3.6
Window Roles
The following
roles
act as windows within the browser or application.
5.4
Definition of Roles
Below is an alphabetical list of
WAI-ARIA
roles
to be used by rich internet application authors.
Abstract roles are used for the ontology. Authors
MUST NOT
use abstract roles in content.
alert
A type of
live region
with important, and usually time-sensitive, information. See related
alertdialog
and
status
alertdialog
A type of dialog that contains an alert message, where initial focus goes to an
element
within the dialog. See related
alert
and
dialog
application
structure
containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by a
widget
role.
article
A section of a page that consists of a composition that forms an independent part of a document, page, or site.
banner
A region that contains mostly site-oriented content, rather than page-specific content.
button
An input that allows for user-triggered actions when clicked or pressed. See related
link
cell
A cell in a tabular container. See related
gridcell
checkbox
A checkable input that has three possible
values
true
false
, or
mixed
columnheader
A cell containing header information for a column.
combobox
A composite
widget
containing a single-line
textbox
and another element, such as a
listbox
or
grid
, that can dynamically pop up to help the user set the value of the
textbox
command
(abstract role)
A form of widget that performs an action but does not receive input data.
complementary
A supporting section of the document, designed to be complementary to the main content at a similar level in the
DOM
hierarchy, but remains meaningful when separated from the main content.
composite
(abstract role)
widget
that may contain navigable descendants or owned children.
contentinfo
A large perceivable region that contains information about the parent document.
definition
A definition of a term or concept. See related
term
dialog
A dialog is a descendant window of the primary window of a web application. For
HTML
pages, the primary application window is the entire web document, i.e., the
body
element.
directory
A list of references to members of a group, such as a static table of contents.
document
An
element
containing content that
assistive technology
users may want to browse in a reading mode.
feed
A scrollable
list
of
articles
where scrolling may cause
articles
to be added to or removed from either end of the list.
figure
A perceivable
section
of content that typically contains a
graphical document
, images, code snippets, or example text. The parts of a
figure
MAY
be user-navigable.
form
landmark
region that contains a collection of items and objects that, as a whole, combine to create a form. See related
grid
A composite
widget
containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.
gridcell
cell
in a
grid
or
treegrid
group
A set of user interface
objects
which are not intended to be included in a page summary or table of contents by
assistive technologies
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 perceivable
section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
link
An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See related
button
list
section
containing
listitem
elements. See related
listbox
listbox
widget
that allows the user to select one or more items from a list of choices. See related
combobox
and
list
listitem
A single item in a list or directory.
log
A type of
live region
where new information is added in meaningful order and old information may disappear. See related
marquee
main
The main content of a document.
marquee
A type of
live region
where non-essential information changes frequently. See related
log
math
Content that represents a mathematical expression.
A type of
widget
that offers a list of choices to the user.
menubar
A presentation of
that usually remains visible and is usually presented horizontally.
menuitem
An option in a set of choices contained by a
or
menubar
menuitemcheckbox
menuitem
with a checkable state whose possible
values
are
true
false
, or
mixed
menuitemradio
A checkable
menuitem
in a set of elements with the same role, only one of which can be checked at a time.
A collection of navigational
elements
(usually links) for navigating the document or related documents.
none
An
element
whose implicit native role semantics will not be mapped to the
API
. See synonym
presentation
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 implicit native role semantics will not be mapped to the
API
. See synonym
none
progressbar
An
element
that displays the progress status for tasks that take a long time.
radio
A checkable input in a group of elements with the same role, only one of which can be checked at a time.
radiogroup
A group of
radio
buttons.
range
(abstract role)
An input representing a range of values that can be set by the user.
region
A perceivable
section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
roletype
(abstract role)
The base
role
from which all other roles in this
taxonomy
inherit.
row
A row of cells in a tabular container.
rowgroup
A structure containing one or more row elements in a tabular container.
rowheader
A cell containing header information for a row in a grid.
scrollbar
A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.
landmark
region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related
form
and
searchbox
searchbox
A type of textbox intended for specifying search criteria. See related
textbox
and
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 the user to select from among discrete choices.
status
A type of
live region
whose content is advisory information for the user but is not important enough to justify an
alert
, often but not necessarily presented as a status bar.
structure
(abstract role)
A document structural
element
switch
A type of checkbox that represents on/off values, as opposed to checked/unchecked values. See related
checkbox
tab
A grouping label providing a mechanism for selecting the tab content that is to be rendered to the user.
table
section
containing data arranged in rows and columns. See related
grid
tablist
A list of
tab
elements
, which are references to
tabpanel
elements.
tabpanel
A container for the resources associated with a
tab
, where each
tab
is contained in a
tablist
term
A word or phrase with a corresponding definition. See related
definition
textbox
A type of input that allows free-form text as its value.
timer
A type of
live region
containing a numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.
toolbar
A collection of commonly used function buttons or controls represented in compact visual form.
tooltip
A contextual popup that displays a description for an element.
tree
A type of
list
that may contain sub-level nested groups that can be collapsed and expanded.
treegrid
grid
whose rows can be expanded and collapsed in the same manner as for 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 tree item elements.
widget
(abstract role)
An interactive component of a graphical user interface (
GUI
).
window
(abstract role)
A browser or application window.
alert
(role)
A type of
live region
with important, and usually time-sensitive, information. See related
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 will be processed as an atomic
live region
Alerts are assertive live regions and will be processed as such by assistive technologies. Neither authors nor user agents are required to set or manage focus to them in order for them to be processed. Since alerts are not required to receive focus, content authors
SHOULD NOT
require users to close an alert. If the operating system allows, the
user agent
SHOULD
fire a system alert
event
through the accessibility
API
when the
WAI-ARIA
alert is created. If an alert requires focus to close the alert, then content authors
SHOULD
use
alertdialog
instead.
Elements with the role
alert
have an implicit
aria-live
value of
assertive
, and an implicit
aria-atomic
value of
true
alertdialog
(role)
A type of dialog that contains an alert message, where initial focus goes to an
element
within the dialog. See related
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. Content authors
SHOULD
make alert dialogs modal by ensuring that, while the
alertdialog
is shown, keyboard and mouse interactions only operate within the dialog. See
aria-modal
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
SHOULD
fire a system alert
event
through the accessibility
API
when the alert is created, provided one is specified by the intended
API
Authors
SHOULD
use
aria-describedby
on an
alertdialog
to reference the alert message element in the dialog. If they do not, an
assistive technology
can resort to its internal recovery mechanism to determine the contents of the alert message.
application
(role)
structure
containing one or more focusable elements requiring user input, such as keyboard or gesture events, that do not follow a standard interaction pattern supported by a
widget
role.
Some
user agents
and
assistive technologies
have a browse mode where standard input events, such as up and down arrow key events, are intercepted and used to control a reading cursor. This browse mode behavior prevents elements that do not have a
widget
role from receiving and using such keyboard and gesture events to provide interactive functionality.
When there is a need to create an element with an interaction model that is not supported by any of the
WAI-ARIA
widget
roles, authors
MAY
give that element role
application
. And, when a user navigates into an element with role
application
assistive technologies
that intercept standard input events
SHOULD
switch to a mode that passes most or all standard input events through to the web application.
For example, a presentation slide editor uses arrow keys to change the positions of textbox and image elements on the slide. There are not any
WAI-ARIA
widget
roles that correspond to such an interaction model so an author could give the slide container role
application
, an
aria-roledescription
of "Slide Editor", and use
aria-describedby
to provide instructions.
Because only the focusable elements contained in an
application
element are accessible to users of some assistive technologies, authors
MUST
use one of the following techniques to ensure all non-decorative static text or image content inside an application is accessible:
Associate the content with a focusable element using
aria-labelledby
or
aria-describedby
Place the content in a focusable element that has role
document
or
article
Manage focus of descendants as described in
Managing Focus
, updating the value of
aria-activedescendant
to reference the
element
containing the focused content.
article
(role)
A section of a page that consists of a composition that forms an independent part of a document, page, or site.
An article is not a navigational
landmark
, but may be nested to form a discussion where assistive technologies could pay attention to article nesting to assist the user in following the discussion. An article could be a forum post, a magazine or newspaper article, a web log entry, a user-submitted comment, or any other independent item of content. It 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.
When the user navigates to an element assigned the role of
article
assistive technologies
that typically intercept standard keyboard events
SHOULD
switch to document browsing mode, as opposed to passing keyboard events through to the web application. Assistive technologies
MAY
provide a feature allowing the user to navigate the hierarchy of any nested
article
elements.
When an
article
is in the context of a
feed
, the author
MAY
specify values for
aria-posinset
and
aria-setsize
banner
(role)
A region that contains mostly site-oriented content, rather than page-specific content.
Site-oriented content typically includes things such as the logo or identity of the site sponsor, and a site-specific search tool. A banner usually appears at the top of the page and typically spans the full width.
User agents
SHOULD
treat elements with the role of
banner
as navigational
landmarks
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
button
(role)
An input that allows for user-triggered actions when clicked or pressed. See related
link
Buttons are mostly used for discrete actions. Standardizing the appearance of buttons enhances the user's recognition of the
widgets
as buttons and allows for a more compact display in toolbars.
Buttons support the optional
attribute
aria-pressed
. Buttons with a non-empty
aria-pressed
attribute are toggle buttons. When
aria-pressed
is
true
the button is in a "pressed"
state
, when
aria-pressed
is
false
it is not pressed. If the attribute is not present, the button is a simple command button.
cell
(role)
A cell in a tabular container. See related
gridcell
Authors
MUST
ensure
elements
with
role
cell are contained in, or owned by, an element with the
role
row
checkbox
(role)
A 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.
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.
Authors
MUST
ensure
elements
with
role
columnheader
are contained in, or owned by, an element with the role
row
Applying the
aria-selected
state on a columnheader
MUST
not cause the user agent to automatically propagate the
aria-selected
state to all the cells in the corresponding column. An author
MAY
choose to propagate selection in this manner depending on the specific application.
While the
columnheader
role can be used in both interactive grids and non-interactive tables, the use of
aria-readonly
and
aria-required
is only applicable to interactive elements. Therefore, authors
SHOULD NOT
use
aria-required
or
aria-readonly
in a
columnheader
that descends from a
table
, and user agents
SHOULD NOT
expose either property to
assistive technologies
unless the
columnheader
descends from a
grid
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.
combobox
(role)
A composite
widget
containing a single-line
textbox
and another element, such as a
listbox
or
grid
, that can dynamically pop up to help the user set the value of the
textbox
Authors
MUST
ensure an element with role
combobox
contains or owns a text input element with role
textbox
or
searchbox
and that the text input has
aria-multiline
set to
false
. If the
combobox
provides autocompletion behavior for the text input as described in
aria-autocomplete
, authors
MUST
set
aria-autocomplete
on the
textbox
element to the value that corresponds to the provided behavior.
Typically, the default state of a
combobox
is collapsed. In the collapsed state, only the
textbox
element of a
combobox
is visible. A
combobox
is said to be expanded when both the
textbox
and a secondary element that serves as its popup are visible. Authors
MUST
set
aria-expanded
to
true
on an element with role
combobox
when it is expanded and
false
when it is collapsed. Elements with the role
combobox
have an implicit
aria-expanded
value of
false
When a
combobox
is expanded, authors
MUST
ensure it contains or owns an element that has a role of
listbox
tree
grid
, or
dialog
. This element is the
combobox
popup. When the
combobox
is expanded, authors
MUST
set
aria-controls
on the
textbox
element to a value that refers to the
combobox
popup element.
Elements with the role
combobox
have an implicit
aria-haspopup
value of
listbox
. If the
combobox
popup element has a role other than
listbox
, authors
MUST
specify a value for
aria-haspopup
that corresponds to the type of its popup.
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants for all instances of this
role
, as described in
Managing Focus
. When a
combobox
receives focus, authors
SHOULD
ensure focus is placed on the
textbox
element.
Authors
SHOULD
provide keyboard mechanisms for moving focus between the
textbox
element and the elements contained in the popup. For example, one common convention is that
Down Arrow
moves focus from the text input to the first focusable descendant of the popup element. If the popup element supports
aria-activedescendant
, in lieu of moving focus, such keyboard mechanisms can control the value of
aria-activedescendant
on the
textbox
element. When a descendant of the popup element is active, authors
MAY
set
aria-activedescendant
on the
textbox
to a value that refers to the active element within the popup while focus remains on the
textbox
element.
Example 5
div
aria-label
"Tag"
role
"combobox"
aria-expanded
"true"
aria-owns
"owned_listbox"
aria-haspopup
"listbox"
input
type
"text"
aria-autocomplete
"list"
aria-controls
"owned_listbox"
aria-activedescendant
"selected_option"
div
ul
role
"listbox"
id
"owned_listbox"
li
role
"option"
Zebra
li
li
role
"option"
id
"selected_option"
Zoom
li
ul
The ARIA 1.0 specification describes a
combobox
pattern where a text input element has the
combobox
role and owns a
listbox
element.
User agents
assistive technologies
, and conformance checkers
SHOULD
continue to support the ARIA 1.0 pattern so that existing implementations of the ARIA 1.0 pattern remain functional.
The features and behaviors of combobox implementations vary widely. Consequently, there are many important authoring considerations. See the
WAI-ARIA
Authoring Practices Guide
wai-aria-practices-1.1
] for additional details on implementing combobox design patterns.
command
(abstract role)
A form of widget that performs an action but does not receive input data.
Note
command
is an abstract role used for the ontology. Authors should not use this role in content.
complementary
(role)
A supporting section of the document, designed to be complementary to the main content at a similar level in the
DOM
hierarchy, but remains meaningful 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 complementary role indicates that contained content is relevant to the main content. If the complementary content is completely separable from the main content, it may be appropriate to use a more general role.
User agents
SHOULD
treat elements with the role of
complementary
as navigational
landmarks
composite
(abstract role)
widget
that may contain navigable descendants or owned children.
Authors
SHOULD
ensure that a composite widget exists as a single navigation stop within the larger navigation system of the web page. Once the composite widget has focus, authors
SHOULD
provide a separate navigation mechanism for users to navigate to
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.
contentinfo
(role)
A large perceivable region that contains information about the parent document.
Examples of information included in this region of the page are copyrights and links to privacy statements.
User agents
SHOULD
treat elements with the role of
contentinfo
as navigational
landmarks
Within any
document
or
application
, the author
SHOULD
mark no more than one
element
with the
contentinfo
role.
Note
Because
document
and
application
elements can be nested in the
DOM
, they may have multiple
contentinfo
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.
definition
(role)
A definition of a term or concept. See related
term
Authors
SHOULD
identify the
element
being defined by giving that element a role of
term
and referencing it with the
aria-labelledby
attribute
dialog
(role)
A dialog is a descendant window of the primary window of a web application. For
HTML
pages, the primary application window is the entire web document, i.e., the
body
element.
Dialogs are most often used to prompt the user to enter or respond to information. A dialog that is designed to interrupt workflow is usually modal. See related
alertdialog
Authors
SHOULD
provide a dialog label, which can be done with the
aria-label
or
aria-labelledby
attribute.
Authors
SHOULD
ensure that all dialogs (both modal and non-modal) have at least one focusable descendant element. Authors
SHOULD
focus an element in the modal dialog when it is displayed, and authors
SHOULD
manage focus of modal dialogs.
Note
In the description of this role, the term "web application" does not refer to the
application
role, which specifies specific assistive technology behaviors.
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.
document
(role)
An
element
containing content that
assistive technology
users may want to browse in a reading mode.
When
user agent
focus moves to an element assigned the role of
document
assistive technologies
having a reading mode for browsing static content
MAY
switch to that reading mode and intercept standard input events, such as Up or Down arrow keyboard events, to control the reading cursor.
Because
assistive technologies
that have a reading mode default to that mode for all elements except for those with either a
widget
or
application
role, the only circumstance where the
document
role is useful for changing assistive technology behavior is when the element with role
document
is a focusable child element of a
widget
or
application
. For example, given an
application
element which contains some static rich text, the author can apply role
document
to the element containing the text and give it a
tabindex
of
. When a screen reader user presses the Tab key and places focus on the
document
element, the user will be able to read the text with the screen reader's reading cursor.
feed
(role)
A scrollable
list
of
articles
where scrolling may cause
articles
to be added to or removed from either end of the list.
feed
enables users of
assistive technologies
that have a document browse mode, such as screen readers, to use the browse mode reading cursor to both read and scroll through a stream of rich content that may continue scrolling infinitely by loading more content as the user reads. In a
feed
assistive technologies
provide a web application with signals of the user's reading cursor movement by moving
user agent
focus, enabling the application to both add new content and visually position content as the user browses the page. The
feed
also lets authors inform assistive technologies when additions and removals are occurring so assistive technologies can more reliably update their reading view without disrupting reading or degrading performance.
For example, a
feed
could be used to present a stream of news stories where each
article
contains a story with text, links, images, and comments as well as widgets for sharing and commenting. As a screen reader user reads and interacts with each story and moves the screen reader reading cursor from story to story, each story scrolls into view and, as needed, new stories are loaded.
feed
is a container element whose children have role
article
. When
articles
are added or removed from either or both ends of a
feed
, authors
SHOULD
set
aria-busy
to
true
on the
feed
element before the changes are made and set it to
false
after the changes are complete. Authors
SHOULD
avoid inserting or removing
articles
in the middle of a
feed
. These requirements help
assistive technologies
gracefully respond to changes in the
feed
content that occur simultaneously with user commands to move the reading cursor within the
feed
Authors
SHOULD
make each
article
in a
feed
focusable and ensure that the application scrolls an
article
into view when
user agent
focus is set on the
article
or one of its descendant elements. For example, in
HTML
, each
article
element should have a
tabindex
value of either
-1
or
When an
assistive technology
reading cursor moves from one
article
to another,
assistive technologies
SHOULD
set user agent focus on the
article
that contains the reading cursor. If the reading cursor lands on a focusable element inside the
article
, the assistive technology
MAY
set focus on that element in lieu of setting focus on the containing
article
Because the ability to scroll to another
article
with an
assistive technology
reading cursor depends on the presence of another
article
in the page, authors
SHOULD
attempt to load additional
articles
before
user agent
focus reaches an
article
at either end of the set of
articles
that has been loaded. Alternatively, authors
MAY
include an
article
at either or both ends of the loaded set of
articles
that includes an element, such as a
button
, that lets the user request more
articles
to be loaded.
In addition to providing a brief label, authors
MAY
apply
aria-describedby
to
article
elements in a
feed
to suggest to screen readers which elements to speak after the label when users navigate by
article
. Screen readers
MAY
provide users with a way to quickly scan
feed
content by speaking both the label and accessible description when navigating by
article
, enabling the user to ignore repetitive or less important elements, such as embedded interaction widgets, that the author has left out of the description.
Authors
SHOULD
provide keyboard commands for moving focus among
articles
in a
feed
so users who do not utilize an assistive technology that provides
article
navigation features can use the keyboard to navigate the
feed
If the number of articles available in a
feed
supply is static, authors
MAY
specify
aria-setsize
on
article
elements in that
feed
. However, if the total number is extremely large, indefinite, or changes often, authors
MAY
set
aria-setsize
to
-1
to communicate the unknown size of the set.
See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for additional details on implementing a feed design pattern.
figure
(role)
A perceivable
section
of content that typically contains a
graphical document
, images, code snippets, or example text. The parts of a
figure
MAY
be user-navigable.
Authors
SHOULD
provide a reference to the
figure
from the main text, but the
figure
need not be displayed at the same location as the referencing element. Authors
MAY
reference text serving as a caption using
aria-describedby
. Authors
MAY
provide a label using
aria-label
or
MAY
reference text serving as a label using
aria-labelledby
Assistive technologies
SHOULD
enable users to quickly navigate to figures. Mainstream
user agents
MAY
enable users to quickly navigate to figures.
form
(role)
landmark
region that contains a collection of items and objects that, as a whole, combine to create a form. See related
A form may be a mix of host language form controls, scripted controls, and hyperlinks. Authors are reminded to use native host language semantics to create form controls, whenever possible. For search facilities, authors
SHOULD
use the
role and not the generic
form
role. Authors
SHOULD
provide a visible label for the form referenced with
aria-labelledby
. If an author uses a script to submit a form based on a user action that would otherwise not trigger an
onsubmit
event (for example, a form submission triggered by the user changing a form element's value), the author
SHOULD
provide the user with advance notification of the behavior.
User agents
SHOULD
treat elements with the role of
form
as navigational
landmarks
grid
(role)
A composite
widget
containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.
The
grid
role does not imply a specific visual, e.g., tabular, presentation. It describes
relationships
among
elements
. It may be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.
The cell elements of a
grid
have role
gridcell
. Authors
MAY
designate a cell as a row or column header by using either the
rowheader
or
columnheader
role
in lieu of the
gridcell
role. Authors
MUST
ensure elements with role
gridcell
columnheader
, or
rowheader
are
owned
by elements with role
row
, which are in turn owned by an element with role
rowgroup
, or
grid
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants of a
grid
as described in
Managing Focus
. When a user is navigating the
grid
content with a keyboard, authors
SHOULD
set focus as follows:
If a
gridcell
contains a single interactive
widget
that will not consume arrow key presses when it receives focus, such as a
checkbox
button
, or
link
, authors
MAY
set focus on the interactive element contained in that cell. This allows the contained widget to be directly operable.
Otherwise, authors
SHOULD
ensure the element that receives focus is a
gridcell
rowheader
, or
columnheader
element.
Authors
SHOULD
provide a mechanism for changing to an interaction or edit mode that allows users to navigate and interact with content contained inside a focusable cell if that focusable cell contains any of the following:
a widget that requires arrow keys to operate, e.g., a
combobox
or
radiogroup
multiple interactive elements
editable content
For example, if a cell in a spreadsheet contains a
combobox
or editable text, the
Enter
key might be used to activate a cell interaction or editing mode when that cell has focus so the directional arrow keys can be used to operate the contained
combobox
or
textbox
. Depending on the implementation, pressing
Enter
again,
Tab
Escape
, or another key may switch the application back to the grid navigation mode.
Authors
MAY
use a
gridcell
to display the result of a formula, which could be editable by the user. In a spreadsheet application, for example, a
gridcell
may show a value calculated from a formula until the user activates the
gridcell
for editing when a
textbox
appears in the
gridcell
containing the formula in an editable state.
If
aria-readonly
is set on an element with role
grid
user agents
MUST
propagate the value to all
gridcell
elements owned by the
grid
and expose the value in the accessibility
API
. An author
MAY
override the propagated value of
aria-readonly
for an individual
gridcell
element.
In a
grid
that provides cell content editing functions, if the content of a focusable
gridcell
element is not editable, authors
MAY
set
aria-readonly
to
true
on the
gridcell
element. However, the value of
aria-readonly
, whether specified for a
grid
or individual cells, only indicates whether the content contained in cells is editable. It does not represent availability of functions for navigating or manipulating the
grid
itself.
An unspecified value for
aria-readonly
does not imply that a
grid
or a
gridcell
contains editable content. For example, if a
grid
presents a collection of elements that are not editable, such as a collection of
link
elements representing dates in a datepicker, it is not necessary for the author to specify a value for
aria-readonly
Authors
MAY
indicate that a focusable
gridcell
is selectable as the object of an action with the
aria-selected
attribute. If the
grid
allows multiple
gridcell
s to be selected, the author
SHOULD
set
aria-multiselectable
to
true
on the element with role
grid
Since
WAI-ARIA
can augment an element of the host language, a
grid
can reuse the elements and attributes of a native table, such as an
HTML
table
element. For example, if an author applies the
grid
role to an
HTML
table
element, the author does not need to apply the
row
and
gridcell
roles to the descendant
HTML
tr
and
td
elements because the
user agent
will automatically make the appropriate translations. When the author is reusing a native host language table element and needs a
gridcell
element to span multiple rows or columns, the author
SHOULD
apply the appropriate host language attributes instead of
WAI-ARIA
aria-rowspan
or
aria-colspan
properties.
See the
WAI-ARIA
Authoring Practices Guide
wai-aria-practices-1.1
] for additional details on implementing grid design patterns.
gridcell
(role)
cell
in a
grid
or
treegrid
gridcell
may be focusable, editable, and selectable. A
gridcell
may have
relationships
such as
aria-controls
to address the application of functional relationships.
If an author intends a
gridcell
to have a row header, column header, or both, and if the relevant headers cannot be determined from the
DOM
structure, authors
SHOULD
explicitly indicate which header cells are relevant to the
gridcell
by applying
aria-describedby
on the
gridcell
and referencing
elements
with
role
rowheader
or
columnheader
In a
treegrid
, authors
MAY
define a
gridcell
as expandable by using 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
gridcell
is pivot table behavior.
Authors
MUST
ensure
elements
with
role
gridcell are contained in, or owned by, an element with the
role
row
group
(role)
A set of user interface
objects
which are not intended to be included in a page summary or table of contents by
assistive technologies
Contrast with
region
which is a grouping of user interface objects that will 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. However, when a
group
is used in the context of list, authors
MUST
limit its children to
listitem
elements. Therefore, proper handling of
group
by authors and assistive technologies is determined by the context in which it is provided.
Authors
MAY
nest
group
elements. If a section is significant enough to warrant inclusion in the web page's table of contents, the author
SHOULD
assign the section a
role
of
region
or a
standard landmark role
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 is used to indicate the nesting level.
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 for elements with a
role
of
img
be
perceivable
, authors
MUST
provide alternative text or a label determined by the
accessible name calculation
input
(abstract role)
A generic type of
widget
that allows user input.
landmark
(abstract role)
A perceivable
section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
Authors designate the purpose of the content by assigning a role that is a subclass of the landmark role and, when needed, by providing a brief, descriptive label.
Elements with a role that is a subclass of the landmark role are known as landmark regions or navigational landmark regions.
Assistive technologies
SHOULD
enable users to quickly navigate to landmark regions. Mainstream
user agents
MAY
enable users to quickly navigate to landmark regions.
Note
landmark
is an abstract role used for the ontology. Authors should not use this role in content.
link
(role)
An interactive reference to an internal or external resource that, when activated, causes the user agent to navigate to that resource. See related
button
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 author is responsible for managing navigation.
Note
If pressing the link triggers an action but does not change browser focus or page location, authors are advised to consider using the
button
role instead of the
link
role.
list
(role)
section
containing
listitem
elements. See related
listbox
Lists contain children whose
role
is
listitem
, or elements whose
role
is
group
which in turn contains children whose
role
is
listitem
listbox
(role)
widget
that allows the user to select one or more items from a list of choices. See related
combobox
and
list
Items within the list are static and, unlike standard
HTML
select
elements
, may contain images. List boxes contain children whose
role
is
option
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants for all instances of this
role
, as described in
Managing Focus
Elements with the role
listbox
have an implicit
aria-orientation
value of
vertical
log
(role)
A type of
live region
where new information is added in meaningful order and old information may disappear. See related
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.
Elements with the role
log
have an implicit
aria-live
value of
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
assistive technologies
User agents
SHOULD
treat elements with the role of
main
as navigational landmarks.
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.
marquee
(role)
A type of
live region
where non-essential information changes frequently. See related
log
Common usages of
marquee
include stock tickers and ad banners. The primary difference between a
marquee
and a
log
is that logs usually have a meaningful order or sequence of important content changes.
Elements with the role
marquee
have an implicit
aria-live
value of
off
math
(role)
Content that represents a mathematical expression.
Content with the role
math
is intended to be marked up in an accessible format such as
MathML
MathML3
], or with another type of textual representation such as TeX or LaTeX, which can be converted to an accessible format by native browser implementations or a polyfill library.
While it is not ideal to use an image of a mathematical expression, there exists a significant amount of legacy content where images are used to represent mathematical expressions. Authors
SHOULD
ensure that images of math are labeled by text that describes the mathematical expression as it might be spoken.
Note
Browsers that support native implementations of
MathML
are able to provide a more robust, accessible math experience than can be accomplished with plain text approximations of math. Some rendering engines have close integration with screen readers that allow spacial touch exploration of the formula and refreshable braille display output in the
Nemeth Braille
format. This level of integration is not supported with images of mathematical formulas, even if the author provides a plain text approximation.
At the time of this writing, some mainstream browsers do not support
MathML
natively, and must be retrofit using a JavaScript polyfill library. When authoring math content, use native
MathML
wherever possible, and test thoroughly. Use a polyfill library or provide a fallback image with a text alternative approximation if necessary.
MathML
Example with Embedded TeX Annotation
Example 6
math
xmlns
"http://www.w3.org/1998/Math/MathML"
mrow
mi
mi
mo
mo
mfrac
mrow
mo
form
"prefix"
mo
mi
mi
mo
mo
msqrt
msup
mi
mi
mn
mn
msup
mo
mo
mn
mn
mo
mo
mi
mi
mo
mo
mi
mi
msqrt
mrow
mrow
mn
mn
mo
mo
mi
mi
mrow
mfrac
mrow
annotation
encoding
"TeX"
x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
annotation
math
Plain
HTML
or Polyfill
DOM
Result of the
MathML
Quadratic Formula
If a rendering engine does not support a native math format such as
MathML
, authors
MAY
use JavaScript to downgrade the content to a format the browser can display, such as this
HTML
image using a data
URI
and plain text alternative.
Example 7
img
role
"math"
src
"..."
alt
"x=⟮−b±√⟮b²−4ac⟯⟯÷2a"
(role)
A collection of navigational
elements
(usually links) for navigating the document or related documents.
User agents
SHOULD
treat elements with the role of
as navigational
landmarks
none
(role)
An
element
whose implicit native role semantics will not be mapped to the
API
. See synonym
presentation
Note
Note regarding the ARIA 1.1
none
role.
In ARIA 1.1, the working group introduced
none
as a synonym to the
presentation
role, due to author confusion surrounding the intended meaning of the word "presentation" or "presentational." Many individuals erroneously consider
role="presentation"
to be synonymous with
aria-hidden="true"
, and we believe
role="none"
conveys the actual meaning more unambiguously.
Until implementations include sufficient support for
role="none"
, web authors are advised to use the
presentation
role alone
role="presentation"
or redundantly as a fallback to the
none
role
role="none presentation"
note
(role)
A section whose content is parenthetic or ancillary to the main content of the resource.
option
(role)
A selectable item in a
select
list.
Authors
MUST
ensure
elements
with
role
option
are contained in, or owned by, an element with the
role
listbox
. Options not associated with a
listbox
might not be correctly mapped to an
API
Elements with the role
option
have an implicit
aria-selected
value of
false
presentation
(role)
An
element
whose implicit native role semantics will not be mapped to the
API
. See synonym
none
Note
Note regarding the ARIA 1.1
none
role.
In ARIA 1.1, the working group introduced
none
as a synonym to the
presentation
role, due to author confusion surrounding the intended meaning of the word "presentation" or "presentational." Many individuals erroneously consider
role="presentation"
to be synonymous with
aria-hidden="true"
, and we believe
role="none"
conveys the actual meaning more unambiguously.
Until implementations include sufficient support for
role="none"
, web authors are advised to use the
presentation
role alone
role="presentation"
or redundantly as a fallback to the
none
role
role="none presentation"
The intended use is when an element is used to change the look of the page but does not have all the functional, interactive, or structural relevance implied by the element type, or may be used to provide for an accessible fallback in older browsers that do not support
WAI-ARIA
Example use cases:
An element whose content is completely presentational (like a spacer image, decorative graphic, or clearing element);
An image that is in a container with the
img
role
and where the full text alternative is available and is marked up with
aria-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 rows, cells, etc.
For any element with a role of presentation and which is not focusable, the user agent
MUST NOT
expose the implicit native semantics of the element (the role and its states and properties) to accessibility
APIs
. However, the user agent
MUST
expose content and descendant elements that do not have an explicit or inherited role of presentation. Thus, the
presentation
role causes a given element to be treated as having no role or to be removed from the accessibility tree, but does not cause the content contained within the element to be removed from the accessibility tree.
For example, according to an accessibility
API
, the following markup elements would appear to have identical role semantics (no role) and identical content.
Example 8
h1
role
"presentation"
Sample Content
h1
span
Sample Content
span
span
role
"presentation"
Sample Content
span
Sample Content
The
presentation
role is used on an element that has implicit native semantics, meaning that there is a default accessibility
API
role for the element. Some elements are only complete when additional descendant elements are provided. For example, in
HTML
, table elements (matching the
grid
role) require
tr
descendants (the
row
role
), which in turn require
th
or
td
children (the
gridcell
columnheader
rowheader
roles). Similarly, lists require list item children. The descendant elements that complete the semantics of an element are described in
WAI-ARIA
as
required owned elements
When an explicit or inherited role of
presentation
is applied to an element with the implicit semantic of a
WAI-ARIA
role that has
required owned elements
, in addition to the element with the explicit role of
presentation
, the user agent
MUST
apply an inherited role of presentation to any owned elements that do not have an explicit role defined. Also, when an explicit or inherited role of presentation is applied to a host language element which has required children as defined by the host language specification, in addition to the element with the explicit role of presentation, the user agent
MUST
apply an inherited role of presentation to any required children that do not have an explicit role defined.
In
HTML
, the
img
element
is treated as a single entity regardless of the type of image file. Consequently, using
role="presentation"
or
role="none"
on an
HTML
img
is equivalent to using
aria-hidden="true"
. In order to make the image contents accessible, authors can embed the object using an
object
or
iframe
element
, or use inline
SVG
code, and follow the accessibility guidelines for the image content.
For any element with an explicit or inherited role of presentation and which is not focusable, user agents
MUST
ignore role-specific
WAI-ARIA
states and properties for that element. For example, in
HTML
, a
ul
or
ol
element with a role of
presentation
will have the implicit native semantics of its
li
elements removed because the
list
role to which the
ul
or
ol
corresponds has a
required owned element
of
listitem
. Likewise, although an
HTML
table
element does not have an implicit native semantic role corresponding directly to a
WAI-ARIA
role, the implicit native semantics of its
thead
tbody
tfoot
tr
th
td
descendants will also be removed, because the
HTML
specification indicates that these are required structural descendants of the
table
element.
Note
Only the implicit native semantics of elements that correspond to
WAI-ARIA
required owned elements
are removed. All other content remains intact, including nested tables or lists, unless those elements also have a explicit role of
presentation
applied.
For example, according to an accessibility
API
, the following markup elements would appear to have identical role semantics (no roles) and identical content.
Example 9
ul
role
"presentation"
li
Sample Content
li
li
More Sample Content
li
ul
foo
foo
Sample Content
foo
foo
More Sample Content
foo
foo
Note
There are other
WAI-ARIA
roles with required children for which this situation is applicable (e.g., radiogroups and listboxes), but tables and lists are the most common real-world cases in which the presentation inheritance is likely to apply.
For any element with an explicit or inherited role of
presentation
, user agents
MUST
apply an inherited role of
presentation
to all host-language-specific labeling elements for the presentational element. For example, a
table
element with a role of
presentation
will have the implicit native semantics of its
caption
element removed, because the caption is merely a label for the presentational table.
Authors
SHOULD NOT
provide meaningful alternative text (for example, use
alt=""
in
HTML
) when the
presentation
role is applied to an image.
In the following code sample, the containing
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 alternatives are provided by the containing element.
Example 10
"img"
aria-labelledby=
"caption"
img
src
"example.png"
role
"presentation"
alt
""
id
"caption"
A visible text caption labeling the image.
div
In the following code sample, because the anchor (
HTML
element) is acting as the treeitem, the list item (
HTML
li
element) is assigned an explicit
WAI-ARIA
role of presentation to override the user agent's implicit native semantics for list items.
Example 11
ul
role
"tree"
li
role
"presentation"
role
"treeitem"
aria-expanded
"true"
An expanded tree node
li
ul
Presentational Roles Conflict Resolution
There are a number of ways presentational role conflicts are resolved.
Host languages elements, having implicit presentational roles for which no roles, may be applied,
MUST
never be exposed to in the accessibility tree. With this exception, user agents
MUST
always expose global
WAI-ARIA
states and properties to accessibility
APIs
. In this case, the user agent ignores the
presentation
role and exposes the element according to its implicit native semantics. However, user agents
MUST
ignore any non-global, role-specific
WAI-ARIA
states and properties, unless it is on an inherited presentational role where an explicit role is applied.
For example,
aria-haspopup
is a global attribute and would always be applied;
aria-level
is not a global attribute and would therefore only apply if the element was not in a presentational state.
Example 12
h1
role
"presentation"
aria-haspopup
"true"
Sample Content
h1
h1
role
"presentation"
aria-level
"2"
Sample Content
h1
Explicit roles on a descendant or
owned
element override the inherited role of
presentation
, and cause the owned element to behave as any other element with an explicit role. If the action of exposing the implicit role causes the accessibility tree to be malformed, the expected results are undefined and the user agent
MAY
resort to an internal recovery mechanism to repair the accessibility tree.
If an element with a role of presentation is focusable, or otherwise interactive, user agents
MUST
ignore the normal effect of the role and expose the element with implicit native semantics, in order to ensure that the element is both
understandable
and
operable
User agents
MUST
always expose global
WAI-ARIA
states and properties to accessibility
APIs
, even if an element has an explicit or inherited role of presentation. In this case, the user agent ignores the
presentation
role and exposes the element according to its implicit native semantics. However, user agents
MUST
ignore any non-global, role-specific
WAI-ARIA
states and properties, unless it is on an inherited presentational role where an explicit role is applied.
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 author
SHOULD
omit the
aria-valuenow
attribute. Authors
SHOULD
update these values 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. It is not possible for the user to alter the value of a
progressbar
because it is always readonly.
Note
Assistive technologies generally will render the value of
aria-valuenow
as a percent of a range between the value of
aria-valuemin
and
aria-valuemax
, unless
aria-valuetext
is specified. It is best to set the values for
aria-valuemin
aria-valuemax
, and
aria-valuenow
in a manner that is appropriate for this calculation.
radio
(role)
A checkable input in a group of elements with the same role, only one of which can be checked at a time.
Authors
SHOULD
ensure that
elements
with role
radio
are explicitly grouped in order to indicate which ones affect the same value. This is achieved by enclosing the radio elements in an element with role
radiogroup
. If it is not possible to make the radio buttons
DOM
children of the
radiogroup
, authors
SHOULD
use the
aria-owns
attribute
on the
radiogroup
element to indicate the
relationship
to its children.
radiogroup
(role)
A group of
radio
buttons.
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
).
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.
region
(role)
A perceivable
section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
Authors
SHOULD
limit use of the region role to sections containing content with a purpose that is not accurately described by one of the other
landmark
roles, such as
main
complementary
, or
Authors
MUST
give each element with role region a brief label that describes the purpose of the content in the region. Authors
SHOULD
reference a visible label with
aria-labelledby
if a visible label is present. Authors
SHOULD
include the label inside of a heading whenever possible. The heading
MAY
be an instance of the standard host language heading element or an instance of an element with role
heading
Assistive technologies
SHOULD
enable users to quickly navigate to elements with role region. Mainstream
user agents
MAY
enable users to quickly navigate to elements with role region.
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.
row
(role)
A row of cells in a tabular container.
Rows contain
cell
or
gridcell
elements
, and thus serve to organize the
table
or
grid
In a
treegrid
, authors
MAY
mark rows as expandable, using the
aria-expanded
attribute
to indicate the present status. This is not the case for an ordinary
table
or
grid
, in which the
aria-expanded
attribute is not present.
Authors
MUST
ensure
elements
with
role
row
are contained in, or
owned
by, an element with the role
table
grid
rowgroup
, or
treegrid
rowgroup
(role)
A structure containing one or more row elements in a tabular container.
The
rowgroup
role establishes a
relationship
between
owned
row
elements. It is a structural equivalent to the
thead
tfoot
, and
tbody
elements in an
HTML
table
element
Authors
MUST
ensure
elements
with
role
rowgroup
are contained in, or
owned
by, an element with the role
table
or
grid
Note
The
rowgroup
role exists, in part, to support role symmetry in
HTML
, and allows for the propagation of presentation inheritance on
HTML
table
elements with an explicit
presentation
role applied.
Note
This role does not differentiate between types of row groups (e.g.,
thead
vs.
tbody
), but an issue has been raised for
WAI-ARIA
2.0.
(role)
landmark
region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related
form
and
searchbox
A search region may be a mix of host language form controls, scripted controls, and hyperlinks.
User agents
SHOULD
treat elements with the role of
as navigational
landmarks
searchbox
(role)
A type of textbox intended for specifying search criteria. See related
textbox
and
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.
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.
select
(abstract role)
A form widget that allows the user to make selections from a set of choices.
Note
select
is an abstract role used for the ontology. Authors should not use this role in content.
separator
(role)
A divider that separates and distinguishes sections of content or groups of menuitems.
There are two types of separators: a static
structure
that provides only a visible boundary and a focusable, interactive
widget
that is also moveable. If a
separator
is not focusable, it is revealed to
assistive technologies
as a static structural element. For example, a static
separator
can be used to help visually divide two groups of menu items in a menu or to provide a horizontal rule between two sections of a page.
Authors
MAY
make a
separator
focusable to create a
widget
that both provides a visible boundary between two sections of content and enables the user to change the relative size of the sections by changing the position of the
separator
. A variable
separator
widget can be moved continuously within a range, whereas a fixed
separator
widget supports only two discrete positions. Typically, a fixed
separator
widget is used to toggle one of the sections between expanded and collapsed states.
If the
separator
is focusable, authors
MUST
set the value of
aria-valuenow
to a
number
reflecting the current position of the
separator
and update that value when it changes. Authors
SHOULD
also provide the value of
aria-valuemin
if it is not
and the value of
aria-valuemax
if it is not
100
. If missing or not a number, the implicit values of these attributes are as follows:
The implicit value of
aria-valuemin
is
The implicit value of
aria-valuemax
is
100
The implicit value of
aria-valuenow
is
50
In applications where there is more than one focusable
separator
, authors
SHOULD
provide an accessible name for each one.
Elements with the role
separator
have an implicit
aria-orientation
value of
horizontal
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.
Authors
MUST
set the
aria-valuemin
aria-valuemax
, and
aria-valuenow
attributes. If missing, their implicit values follow the same rules as the
HTML
range input type
If
aria-valuemin
is missing or not a
number
, it defaults to 0 (zero).
If
aria-valuemax
is missing or not a
number
, it defaults to 100.
If
aria-valuenow
is missing or not a
number
, it defaults to the value half way between
aria-valuemin
and
aria-valuemax
If
aria-valuenow
is present but less than
aria-valuemin
, it defaults to the value of
aria-valuemin
If
aria-valuenow
is present but greater than
aria-valuemax
, it defaults to the value of
aria-valuemax
Elements with the role
slider
have an implicit
aria-orientation
value of
horizontal
spinbutton
(role)
A form of
range
that expects the user to select from among discrete choices.
spinbutton
typically allows the user to select from the given range through the use of an up and down button on the keyboard. Visibly, the current value is incremented or decremented until a maximum or minimum value is reached. Authors
SHOULD
ensure this functionality is accomplished programmatically through the use of
up
and
down
arrows on the keyboard.
Although a
spinbutton
is similar in appearance to many presentations of
select
, it is advisable to use
spinbutton
when working with known ranges (especially in the case of large ranges) as opposed to distinct options. For example, a
spinbutton
representing a range from 1 to 1,000,000 would provide much better performance than a
select
widget
representing the same values.
Authors
MAY
create a
spinbutton
with children or owned elements, but
MUST
limit those elements to a
textbox
and/or two
buttons
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants for all instances of this
role
, as described in
Managing Focus
. When a
spinbutton
receives focus, authors
SHOULD
ensure focus is placed on the
textbox
element if one is present, and on the
spinbutton
itself otherwise. Authors
SHOULD NOT
include contained
button
elements in the primary navigation ring, e.g., the Tab ring in
HTML
, because they are superfluous for people using keyboard devices.
Authors
MUST
set the
aria-valuenow
attribute. Authors
SHOULD
set the
aria-valuemin
attribute when there is a minimum value, and the
aria-valuemax
attribute when there is a maximum value. If missing or not a
number
, the implicit values of these attributes are as follows:
The implicit value of
aria-valuemin
is that there is no minimum value.
The implicit value of
aria-valuemax
is that there is no maximum value.
The implicit value of
aria-valuenow
is
status
(role)
A type of
live region
whose content is advisory information for the user but is not important enough to justify an
alert
, often but not necessarily presented as a status bar.
Authors
SHOULD
ensure an element with role
status
does not receive focus as a result of change in status.
Status is a form of
live region
. If another part of the page controls what appears in the status, authors
SHOULD
make the
relationship
explicit with the
aria-controls
attribute
Assistive technologies
MAY
reserve some cells of a Braille display to render the status.
Elements with the role
status
have an implicit
aria-live
value of
polite
and an implicit
aria-atomic
value of
true
structure
(abstract role)
A document structural
element
Roles
for document structure support the accessibility of dynamic web content by helping
assistive technologies
determine active content versus static document content. Structural roles by themselves do not all map to
APIs
, but are used to create
widget
roles or assist content adaptation for assistive technologies.
Note
structure
is an abstract role used for the ontology. Authors should not use this role in content.
switch
(role)
A type of checkbox that represents on/off values, as opposed to checked/unchecked values. See related
checkbox
The
aria-checked
attribute
of a
switch
indicates whether the input is on (
true
) or off (
false
). The
mixed
value is invalid, and user agents
MUST
treat a
mixed
value as equivalent to
false
for this role.
Note
switch
provides approximately the same functionality as a
checkbox
and toggle
button
, but makes it possible for assistive technologies to present the widget in a fashion consistent with its on-screen appearance.
tab
(role)
A grouping label providing a mechanism for selecting the tab content that is 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 in
Managing Focus
tablist
elements, which contain a set of associated
tab
elements, are typically placed near a series of
tabpanel
elements, usually preceding it. See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for details on implementing a tab set design pattern.
Authors
MUST
ensure
elements
with
role
tab
are contained in, or
owned
by, an element with the role
tablist
Authors
SHOULD
ensure the
tabpanel
associated with the currently active tab is
perceivable
to the user.
For a single-selectable
tablist
, authors
SHOULD
hide other
tabpanel
elements
from the user until the user selects the tab associated with that tabpanel. For a multi-selectable
tablist
, authors
SHOULD
ensure each visible
tabpanel
has its
aria-expanded
attribute
set to
true
, and that the remaining hidden
tabpanel
elements have their
aria-expanded
attributes set to
false
In either case, authors
SHOULD
ensure that a selected tab has its
aria-selected
attribute set to
true
, that inactive tab elements have their
aria-selected
attribute set to
false
, and that the currently selected tab provides a visual indication that it is selected. In the absence of an
aria-selected
attribute on the current tab,
user agents
SHOULD
indicate to
assistive technologies
through the platform
API
that the currently focused tab is selected.
table
(role)
section
containing data arranged in rows and columns. See related
grid
The
table
role is intended for tabular containers which are not interactive. If the tabular container maintains a selection state, provides its own two-dimensional navigation, or allows the user to rearrange or otherwise manipulate its contents or the display thereof, authors
SHOULD
use
grid
or
treegrid
instead.
Authors
SHOULD
prefer the use of the host language's semantics for table whenever possible, such as the
HTML
table
element.
tablist
(role)
A list of
tab
elements
, which are references to
tabpanel
elements.
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants for all instances of this
role
, as described in
Managing Focus
For a single-selectable
tablist
, authors
SHOULD
hide other
tabpanel
elements
from the user until the user selects the tab associated with that tabpanel. For a multi-selectable
tablist
, authors
SHOULD
ensure each visible
tabpanel
has its
aria-expanded
attribute
set to
true
, and that the remaining hidden
tabpanel
elements have their
aria-expanded
attributes set to
false
tablist
elements are typically placed near usually preceding, a series of
tabpanel
elements. See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for details on implementing a tab set design pattern.
Elements with the role
tablist
have an implicit
aria-orientation
value of
horizontal
tabpanel
(role)
A container for the resources associated with a
tab
, where each
tab
is contained in a
tablist
Authors
SHOULD
associate a
tabpanel
element
with its
tab
, either by using the
aria-controls
attribute on the tab to reference the tab panel, or by using the
aria-labelledby
attribute on the tab panel to reference the tab.
tablist
elements are typically placed near, usually preceding, a series of
tabpanel
elements. See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for details on implementing a tab set design pattern.
term
(role)
A word or phrase with a corresponding definition. See related
definition
The
term
role is used to explicitly identify a word or phrase for which a
definition
has been provided by the author or is expected to be provided by the user.
Authors
SHOULD NOT
use the
term
role on interactive elements such as links because doing so could prevent users of
assistive technologies
from interacting with those elements.
textbox
(role)
A type of input that allows free-form text as its 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
, or cases in which an element with different
semantics
is repurposed as a text field.
Note
In most user agent implementations, the default behavior of the
ENTER
or
RETURN
key is different between the single-line and multi-line text fields in
HTML
. When user has focus in a single-line
element, the keystroke usually submits the form. When user has focus in a multi-line
aria-labelledby=
"caption"
img
src
"example.png"
role
"presentation"
alt
""
id
"caption"
A visible text caption labeling the image.
div
In the following code sample, because the anchor (
HTML
element) is acting as the treeitem, the list item (
HTML
li
element) is assigned an explicit
WAI-ARIA
role of presentation to override the user agent's implicit native semantics for list items.
Example 11
ul
role
"tree"
li
role
"presentation"
role
"treeitem"
aria-expanded
"true"
An expanded tree node
li
ul
Presentational Roles Conflict Resolution
There are a number of ways presentational role conflicts are resolved.
Host languages elements, having implicit presentational roles for which no roles, may be applied,
MUST
never be exposed to in the accessibility tree. With this exception, user agents
MUST
always expose global
WAI-ARIA
states and properties to accessibility
APIs
. In this case, the user agent ignores the
presentation
role and exposes the element according to its implicit native semantics. However, user agents
MUST
ignore any non-global, role-specific
WAI-ARIA
states and properties, unless it is on an inherited presentational role where an explicit role is applied.
For example,
aria-haspopup
is a global attribute and would always be applied;
aria-level
is not a global attribute and would therefore only apply if the element was not in a presentational state.
Example 12
h1
role
"presentation"
aria-haspopup
"true"
Sample Content
h1
h1
role
"presentation"
aria-level
"2"
Sample Content
h1
Explicit roles on a descendant or
owned
element override the inherited role of
presentation
, and cause the owned element to behave as any other element with an explicit role. If the action of exposing the implicit role causes the accessibility tree to be malformed, the expected results are undefined and the user agent
MAY
resort to an internal recovery mechanism to repair the accessibility tree.
If an element with a role of presentation is focusable, or otherwise interactive, user agents
MUST
ignore the normal effect of the role and expose the element with implicit native semantics, in order to ensure that the element is both
understandable
and
operable
User agents
MUST
always expose global
WAI-ARIA
states and properties to accessibility
APIs
, even if an element has an explicit or inherited role of presentation. In this case, the user agent ignores the
presentation
role and exposes the element according to its implicit native semantics. However, user agents
MUST
ignore any non-global, role-specific
WAI-ARIA
states and properties, unless it is on an inherited presentational role where an explicit role is applied.
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 author
SHOULD
omit the
aria-valuenow
attribute. Authors
SHOULD
update these values 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. It is not possible for the user to alter the value of a
progressbar
because it is always readonly.
Note
Assistive technologies generally will render the value of
aria-valuenow
as a percent of a range between the value of
aria-valuemin
and
aria-valuemax
, unless
aria-valuetext
is specified. It is best to set the values for
aria-valuemin
aria-valuemax
, and
aria-valuenow
in a manner that is appropriate for this calculation.
radio
(role)
A checkable input in a group of elements with the same role, only one of which can be checked at a time.
Authors
SHOULD
ensure that
elements
with role
radio
are explicitly grouped in order to indicate which ones affect the same value. This is achieved by enclosing the radio elements in an element with role
radiogroup
. If it is not possible to make the radio buttons
DOM
children of the
radiogroup
, authors
SHOULD
use the
aria-owns
attribute
on the
radiogroup
element to indicate the
relationship
to its children.
radiogroup
(role)
A group of
radio
buttons.
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
).
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.
region
(role)
A perceivable
section
containing content that is relevant to a specific, author-specified purpose and sufficiently important that users will likely want to be able to navigate to the section easily and to have it listed in a summary of the page. Such a page summary could be generated dynamically by a user agent or assistive technology.
Authors
SHOULD
limit use of the region role to sections containing content with a purpose that is not accurately described by one of the other
landmark
roles, such as
main
complementary
, or
Authors
MUST
give each element with role region a brief label that describes the purpose of the content in the region. Authors
SHOULD
reference a visible label with
aria-labelledby
if a visible label is present. Authors
SHOULD
include the label inside of a heading whenever possible. The heading
MAY
be an instance of the standard host language heading element or an instance of an element with role
heading
Assistive technologies
SHOULD
enable users to quickly navigate to elements with role region. Mainstream
user agents
MAY
enable users to quickly navigate to elements with role region.
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.
row
(role)
A row of cells in a tabular container.
Rows contain
cell
or
gridcell
elements
, and thus serve to organize the
table
or
grid
In a
treegrid
, authors
MAY
mark rows as expandable, using the
aria-expanded
attribute
to indicate the present status. This is not the case for an ordinary
table
or
grid
, in which the
aria-expanded
attribute is not present.
Authors
MUST
ensure
elements
with
role
row
are contained in, or
owned
by, an element with the role
table
grid
rowgroup
, or
treegrid
rowgroup
(role)
A structure containing one or more row elements in a tabular container.
The
rowgroup
role establishes a
relationship
between
owned
row
elements. It is a structural equivalent to the
thead
tfoot
, and
tbody
elements in an
HTML
table
element
Authors
MUST
ensure
elements
with
role
rowgroup
are contained in, or
owned
by, an element with the role
table
or
grid
Note
The
rowgroup
role exists, in part, to support role symmetry in
HTML
, and allows for the propagation of presentation inheritance on
HTML
table
elements with an explicit
presentation
role applied.
Note
This role does not differentiate between types of row groups (e.g.,
thead
vs.
tbody
), but an issue has been raised for
WAI-ARIA
2.0.
(role)
landmark
region that contains a collection of items and objects that, as a whole, combine to create a search facility. See related
form
and
searchbox
A search region may be a mix of host language form controls, scripted controls, and hyperlinks.
User agents
SHOULD
treat elements with the role of
as navigational
landmarks
searchbox
(role)
A type of textbox intended for specifying search criteria. See related
textbox
and
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.
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.
select
(abstract role)
A form widget that allows the user to make selections from a set of choices.
Note
select
is an abstract role used for the ontology. Authors should not use this role in content.
separator
(role)
A divider that separates and distinguishes sections of content or groups of menuitems.
There are two types of separators: a static
structure
that provides only a visible boundary and a focusable, interactive
widget
that is also moveable. If a
separator
is not focusable, it is revealed to
assistive technologies
as a static structural element. For example, a static
separator
can be used to help visually divide two groups of menu items in a menu or to provide a horizontal rule between two sections of a page.
Authors
MAY
make a
separator
focusable to create a
widget
that both provides a visible boundary between two sections of content and enables the user to change the relative size of the sections by changing the position of the
separator
. A variable
separator
widget can be moved continuously within a range, whereas a fixed
separator
widget supports only two discrete positions. Typically, a fixed
separator
widget is used to toggle one of the sections between expanded and collapsed states.
If the
separator
is focusable, authors
MUST
set the value of
aria-valuenow
to a
number
reflecting the current position of the
separator
and update that value when it changes. Authors
SHOULD
also provide the value of
aria-valuemin
if it is not
and the value of
aria-valuemax
if it is not
100
. If missing or not a number, the implicit values of these attributes are as follows:
The implicit value of
aria-valuemin
is
The implicit value of
aria-valuemax
is
100
The implicit value of
aria-valuenow
is
50
In applications where there is more than one focusable
separator
, authors
SHOULD
provide an accessible name for each one.
Elements with the role
separator
have an implicit
aria-orientation
value of
horizontal
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.
Authors
MUST
set the
aria-valuemin
aria-valuemax
, and
aria-valuenow
attributes. If missing, their implicit values follow the same rules as the
HTML
range input type
If
aria-valuemin
is missing or not a
number
, it defaults to 0 (zero).
If
aria-valuemax
is missing or not a
number
, it defaults to 100.
If
aria-valuenow
is missing or not a
number
, it defaults to the value half way between
aria-valuemin
and
aria-valuemax
If
aria-valuenow
is present but less than
aria-valuemin
, it defaults to the value of
aria-valuemin
If
aria-valuenow
is present but greater than
aria-valuemax
, it defaults to the value of
aria-valuemax
Elements with the role
slider
have an implicit
aria-orientation
value of
horizontal
spinbutton
(role)
A form of
range
that expects the user to select from among discrete choices.
spinbutton
typically allows the user to select from the given range through the use of an up and down button on the keyboard. Visibly, the current value is incremented or decremented until a maximum or minimum value is reached. Authors
SHOULD
ensure this functionality is accomplished programmatically through the use of
up
and
down
arrows on the keyboard.
Although a
spinbutton
is similar in appearance to many presentations of
select
, it is advisable to use
spinbutton
when working with known ranges (especially in the case of large ranges) as opposed to distinct options. For example, a
spinbutton
representing a range from 1 to 1,000,000 would provide much better performance than a
select
widget
representing the same values.
Authors
MAY
create a
spinbutton
with children or owned elements, but
MUST
limit those elements to a
textbox
and/or two
buttons
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants for all instances of this
role
, as described in
Managing Focus
. When a
spinbutton
receives focus, authors
SHOULD
ensure focus is placed on the
textbox
element if one is present, and on the
spinbutton
itself otherwise. Authors
SHOULD NOT
include contained
button
elements in the primary navigation ring, e.g., the Tab ring in
HTML
, because they are superfluous for people using keyboard devices.
Authors
MUST
set the
aria-valuenow
attribute. Authors
SHOULD
set the
aria-valuemin
attribute when there is a minimum value, and the
aria-valuemax
attribute when there is a maximum value. If missing or not a
number
, the implicit values of these attributes are as follows:
The implicit value of
aria-valuemin
is that there is no minimum value.
The implicit value of
aria-valuemax
is that there is no maximum value.
The implicit value of
aria-valuenow
is
status
(role)
A type of
live region
whose content is advisory information for the user but is not important enough to justify an
alert
, often but not necessarily presented as a status bar.
Authors
SHOULD
ensure an element with role
status
does not receive focus as a result of change in status.
Status is a form of
live region
. If another part of the page controls what appears in the status, authors
SHOULD
make the
relationship
explicit with the
aria-controls
attribute
Assistive technologies
MAY
reserve some cells of a Braille display to render the status.
Elements with the role
status
have an implicit
aria-live
value of
polite
and an implicit
aria-atomic
value of
true
structure
(abstract role)
A document structural
element
Roles
for document structure support the accessibility of dynamic web content by helping
assistive technologies
determine active content versus static document content. Structural roles by themselves do not all map to
APIs
, but are used to create
widget
roles or assist content adaptation for assistive technologies.
Note
structure
is an abstract role used for the ontology. Authors should not use this role in content.
switch
(role)
A type of checkbox that represents on/off values, as opposed to checked/unchecked values. See related
checkbox
The
aria-checked
attribute
of a
switch
indicates whether the input is on (
true
) or off (
false
). The
mixed
value is invalid, and user agents
MUST
treat a
mixed
value as equivalent to
false
for this role.
Note
switch
provides approximately the same functionality as a
checkbox
and toggle
button
, but makes it possible for assistive technologies to present the widget in a fashion consistent with its on-screen appearance.
tab
(role)
A grouping label providing a mechanism for selecting the tab content that is 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 in
Managing Focus
tablist
elements, which contain a set of associated
tab
elements, are typically placed near a series of
tabpanel
elements, usually preceding it. See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for details on implementing a tab set design pattern.
Authors
MUST
ensure
elements
with
role
tab
are contained in, or
owned
by, an element with the role
tablist
Authors
SHOULD
ensure the
tabpanel
associated with the currently active tab is
perceivable
to the user.
For a single-selectable
tablist
, authors
SHOULD
hide other
tabpanel
elements
from the user until the user selects the tab associated with that tabpanel. For a multi-selectable
tablist
, authors
SHOULD
ensure each visible
tabpanel
has its
aria-expanded
attribute
set to
true
, and that the remaining hidden
tabpanel
elements have their
aria-expanded
attributes set to
false
In either case, authors
SHOULD
ensure that a selected tab has its
aria-selected
attribute set to
true
, that inactive tab elements have their
aria-selected
attribute set to
false
, and that the currently selected tab provides a visual indication that it is selected. In the absence of an
aria-selected
attribute on the current tab,
user agents
SHOULD
indicate to
assistive technologies
through the platform
API
that the currently focused tab is selected.
table
(role)
section
containing data arranged in rows and columns. See related
grid
The
table
role is intended for tabular containers which are not interactive. If the tabular container maintains a selection state, provides its own two-dimensional navigation, or allows the user to rearrange or otherwise manipulate its contents or the display thereof, authors
SHOULD
use
grid
or
treegrid
instead.
Authors
SHOULD
prefer the use of the host language's semantics for table whenever possible, such as the
HTML
table
element.
tablist
(role)
A list of
tab
elements
, which are references to
tabpanel
elements.
To be
keyboard accessible
, authors
SHOULD
manage focus of descendants for all instances of this
role
, as described in
Managing Focus
For a single-selectable
tablist
, authors
SHOULD
hide other
tabpanel
elements
from the user until the user selects the tab associated with that tabpanel. For a multi-selectable
tablist
, authors
SHOULD
ensure each visible
tabpanel
has its
aria-expanded
attribute
set to
true
, and that the remaining hidden
tabpanel
elements have their
aria-expanded
attributes set to
false
tablist
elements are typically placed near usually preceding, a series of
tabpanel
elements. See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for details on implementing a tab set design pattern.
Elements with the role
tablist
have an implicit
aria-orientation
value of
horizontal
tabpanel
(role)
A container for the resources associated with a
tab
, where each
tab
is contained in a
tablist
Authors
SHOULD
associate a
tabpanel
element
with its
tab
, either by using the
aria-controls
attribute on the tab to reference the tab panel, or by using the
aria-labelledby
attribute on the tab panel to reference the tab.
tablist
elements are typically placed near, usually preceding, a series of
tabpanel
elements. See the
WAI-ARIA
Authoring Practices
wai-aria-practices-1.1
] for details on implementing a tab set design pattern.
term
(role)
A word or phrase with a corresponding definition. See related
definition
The
term
role is used to explicitly identify a word or phrase for which a
definition
has been provided by the author or is expected to be provided by the user.
Authors
SHOULD NOT
use the
term
role on interactive elements such as links because doing so could prevent users of
assistive technologies
from interacting with those elements.
textbox
(role)
A type of input that allows free-form text as its 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
, or cases in which an element with different
semantics
is repurposed as a text field.
Note
In most user agent implementations, the default behavior of the
ENTER
or
RETURN
key is different between the single-line and multi-line text fields in
HTML
. When user has focus in a single-line
element, the keystroke usually submits the form. When user has focus in a multi-line