Status of This Document
This
section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical
report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This
is an internal Scratch Draft not endorsed by the Protocols and Formats
Working Group. It is not stable and may change at any time.
This
scratch draft has been prepared as a vehicle for sharing a possible
rewrite to section 6.2. Please ignore any accidental breakage or
changes outside that section. This scratch draft is based on the
14 November 2008 version of the Editor's Draft.
Implementors
should not use this for anything other than experimental
implementations. This document is available to W3C Members and should
not be distributed to anyone who does not have W3C Member access.
Publication
as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by
other documents at any time. It is inappropriate to cite this document
as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures
made in connection with the deliverables of the group; that page also
includes instructions for disclosing a patent. An individual who has
actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The disclosure obligations of the Participants of this group are described in the charter.
1. Introduction
This section is informative.
The
domain of Web accessibility defines how to make Web content usable by
people with disabilities. People with some types of disabilities use
Assistive Technology (AT) to interact with content. AT
can transform the presentation of content into a format more suitable
to the user, and can allow the user to interact in different ways than
the author designed. In order to accomplish this, AT
must understand the semantics of the content. Semantics are knowledge
of roles, states, and properties, as a person would understand them,
that apply to elements within the content. For instance, if a paragraph
is semantically identified as such, AT
can interact with it as a unit separable from the rest of the content,
knowing the exact boundaries of that paragraph. A slider or tree widget
is a more complex example, in which various parts of a widget each have
semantics that must be properly identified for the computer to support
effective interaction.
Established content technologies define
semantics for elements commonly used in those technologies. However,
new technologies can overlook some of the semantics required for
accessibility. Furthermore, new authoring practices evolve which
override the intended semantics—elements that have one defined
semantic meaning in the technology are used with a different semantic
meaning intended to be understood by the user.
For example,
Rich Internet Applications developers can create a tree widget in HTML
using CSS and JavaScript even though HTML lacks a semantic element for
that. A different element must be used, possibly a list element with
display instructions to make it look and behave like a tree widget.
Assistive technology, however, must present the element in a different
modality and the display instructions may not be applicable. The AT
will present it as a list, which has very different display and
interaction from a tree widget, and the user may be unsuccessful at
understanding and operating the widget.
The incorporation of
WAI-ARIA is a way for an author to provide proper type semantics on
custom widgets (elements with repurposed semantics) to make these
widgets accessible, usable and interoperable with assistive
technologies. This specification identifies the types of widgets and
structures that are recognized by accessibility products, by providing
an ontology of corresponding roles that can be attached to content.
This allows elements with a given role to be understood as a particular
widget or structural type regardless of any semantic inherited from the
implementing technology. Roles are a common property of platform
Accessibility APIs
which applications use to support assistive technologies. Assistive
technology can then use the role information to provide effective
presentation and interaction with these elements.
This role taxonomy currently includes interaction widget (user interface widget)
and structural document (content organization) types of objects. The
role taxonomy describes inheritance (widgets that are types of other
widgets) and details what states and properties each role supports.
When possible, information is provided about mapping of roles to
accessibility APIs.
Roles
are element types and should not change with time or user actions.
Changing the role on an element from its inital value will be treated,
via accessibility API events, as the removal of the old element and
insertion of a new element with the new role.
Changeable states
and properties of elements are also defined in this specification.
States and Properties are used to declare important properties of an
element that affect and describe interaction. These properties enable
the user agent or operating system to properly handle the element even
when these properties are altered dynamically by scripts. For example,
alternative input and output technology such as screen readers, speech
dictation software and on-screen keyboards must recognize the state of
an element (such as: if an object is disabled, checked, focused,
collapsed, hidden, etc.).
While it is possible for assistive technologies to access these properties 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.
Figure 1.0 illustrates a typical Document Object Model (DOM) [DOM]
node. Placed within the DOM node and the assistive technology is a box
containing the contract provided by the user agent to the assistive
technology. This data includes typical accessibility information found
in the accessibility API
for many of our accessible platforms for GUIs (role, state, caret,
selection, event notification, parent/child information, relationship,
and descriptions).
![The contract model with accessibility APIs](accessibleelement.png)
Figure 1: The contract model with accessibility APIs
For more information see the WAI-ARIA Primer [ARIA-PRIMER] for the use of roles in making interactive content accessible.
In addition to the prose documentation, the role taxonomy is provided in Web Ontology Language (OWL) [OWL], which is an implementation of Resource Description Framework (RDF) [RDF]. Tools can use these to validate the implementation of roles in a given content document.
Note:
the use of RDF/OWL as a formal representation of roles may be used to
support future extensibility. Standard RDF/OWL mechanisms can be used
to define new roles that inherit from the roles defined in this
specification. The mechanism to define and use role extensions in an
interoperable manner, however, is not defined by this specification. A
future version of ARIA is expected to define how to extend roles.
1.1. Scope
The design aims of creating this specification include:
- Define what state information may be controlled by the author.
- Support device independence - new devices coming on line, such as telephones, PDA's,
tablets, televisions, etc. mean that it is imperative to have a design
that allows you to author once and render in different ways on
different devices, rather than authoring new versions of the document
for each type of device.
- Improve the accessibility of dynamic content such as that generated by script.
- Provide for interoperability with Assistive Technologies.
This draft currently handles two aspects of roles: GUI functionality and structural relationships of the element. For more information see the WAI-ARIA Primer [ARIA-PRIMER] for the use of roles in making interactive content accessible.
The role taxonomy is designed in part to support the common roles found in platform accessibility APIs.
Reference to roles found in this taxonomy by dynamic Web content may be
used to support interoperability with assistive 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 XML Schema [XSD]. However, being able to define similarities between roles, such as baseConcepts
and more descriptive definitions, would not be available in XSD. While
this extensibility is possible, this version of the specification does
not define how this extension is to be achieved.
WAI-ARIA is supported by a set of informative resources. In addition to the WAI-ARIA Roadmap, the WAI-ARIA Primer [ARIA-PRIMER] provides a basic introduction to the concepts behind and reason for ARIA, and the WAI-ARIA Best Practices [ARIA-PRACTICES]
describe recommended usage patterns for Web content developers. These
documents are intended to help authors learn the practice of putting
WAI-ARIA to use.
1.2. Use Cases
Keyboard
accessible content helps users of alternate input devices. The new
semantics when combined by our style guide work will allow alternate
input solutions to facilitate command and control via an alternate
input solution.
Low vision solutions benefit from ARIA markup
in that the improved keyboard navigation helps people with extremely
low vision. Low vision solutions offer a degree of screen reading
functionality (like AI Squared's Zoom text). Furthermore, ARIA
introduces navigation landmarks both through our taxonomy and the XHTML
role landmarks which dramatically improves keyboard navigation
productivity. This is a huge benefit for alternate input solutions as
well.
ARIA will also be used to assist people with cognitive
impairments. The additional semantics will allow authors to restructure
and substitute alternative content in adaptive Web 2.0 solutions.
Assistive
technology needs the ability to support alternative input forms by
getting and setting the current value of widgets. AT also needs to
determine what objects are selected, and manage widgets that allow
multiple selections.
ARIA is used as a supplement for
native language semantics, not a replacement. When the host language
provides a feature that is equivalent to the ARIA feature, use the host
language feature. ARIA should only be used in cases where the host
language lacks the needed role, state, or property indicator. First use
a host language feature that is as similar as possible to the ARIA
feature, then refine the meaning by adding ARIA. For instance, a
multiselectable grid could be implemented as a table, and then ARIA
used to clarify that it is a grid, not just a table. This allows for
the best possible fallback for user agents that do not support ARIA and
preserves the integrity of the host language semantics.
2. Using WAI-ARIA
This section is informative.
Complex
web applications become inaccessible when assistive 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 the Roadmap for Accessible Rich Internet Applications [ARIA-ROADMAP]).
ARIA divides the semantics into roles (the type defining a user
interface element) and states and properties supported by the roles.
Authors
must associate elements in the document to an ARIA role and the
appropriate attributes (states and properties) during its lifecycle.
2.1. WAI-ARIA Roles
An ARIA role is set on an element using the a role attribute similar to the one defined in the XHTML Role Attribute
Module [XHTML-ROLES].
<div role="checkbox">
The roles defined in this specification include a collection of document landmarks and the ARIA role taxonomy.
The Roles in this taxonomy were modeled using RDF/OWL [OWL]
to build rich descriptions of the expected behaviors of each role.
Features of the role taxononmy provide the following information for
each role:
- describes the context of a role, for example a
listitem
should be inside a list
; - defines a hierarchy of roles with related properties, for example a
directory
is a type of list
; - makes use of OWL to provide a type hierarchy allowing for semantic inheritance similar to a class hierarchy;
- makes references to related concepts in other specifications;
- provides descriptions for each role;
- describes what states are supported for each role, for example, a
checkbox
supports being aria-checked
.
Attaching
a role from the role taxonomy to an element in the document gives
assistive technology the information it needs to handle an element
correctly.
2.2. WAI-ARIA States and Properties
ARIA
provides a collection of accessibility states and properties which are
used to support platform accessibility APIs on the various operating
system platforms. Assistive technology may access this information
through an exposed user agent DOM or through a mapping to the platform
accessibility API. When combined with roles, the user agent can supply
the assistive technology with information to render the information to
the user at any instance in time. Changes in states or properties will
result in a notification to an assistive technology to let them know
that a change in behavior has occurred.
In the following example, a span
has been used to create a checkbox which in this case has three
possible states. A role is used to make the behavior of this simple
widget known to the user agent. Properties that may change with user
actions (such as aria-checked
) are defined in the States and Properties.
<span role="checkbox" aria-checked="mixed"
onkeydown="return checkBoxEvent(event);"
onclick="return checkBoxEvent(event);" >
A checkbox label
</span>
It should be noted that some accessibility state information is managed and controlled by the user agent. These are called managed states. Often these states have corresponding CSS pseudo-classes to reflect necessary style changes. An example of a managed state is focus
.
In contrast, the states in this specification are typically controlled
by the author and are called unmanaged states. Some states are managed
by the UA but the author can override them, such as aria-posinset
and aria-setsize
.
The author should override those only if the DOM is not complete and
thus the UA calculation would be incorrect. Both managed and unmanaged
states are mapped to the platform accessibility APIs by the user agent.
Finally, an added value for ARIA is that user agents that support CSS attribute selectors ([CSS], Section 5.8) can allow the author to create UI
changes based on the ARIA state information, dramatically reducing the
amount of script used to create the equivalent functionality. In the
following example, CSS selectors based on the value of the ARIA aria-checked
state are used to determine whether an image of a checked or an unchecked box is shown:
*[aria-checked=true]:before {content: url('checked.gif')}
*[aria-checked=false]:before {content: url('unchecked.gif')}
2.3. Managing Focus
In any application
there must always be an element with focus, as applications require
users to have a place to provide user input. The element with focus
must never be destroyed, hidden or scrolled off-screen. All interactive
elements should be focusable. There should be an obvious, discoverable
way, either through tabbing or other standard navigation techniques,
for keyboard users to move the focus to any interactive element they
wish to interact with. See User Agent Accessibility Guidelines, Guideline 9 ([UAAG], Guideline 9).
When
using standard (X)HTML and basic WAI-ARIA widgets, application
developers can simply manipulate the tab order or use script to create
keyboard shortcuts to elements in the document. Use of more complex
widgets requires the author to manage focus within them.
WAI-ARIA
includes a number of "managing container" widgets, also often referred
to as "composite" widgets. Typically, the container is responsible for
tracking the last descendant which was active (the default is usually
the first item in the container). When the container is navigated to
with the Tab key, focus goes directly to the last active descendant.
The user may also activate the container by clicking on one of the
descendants within it.
When something in the container has
focus, the user may navigate through the container by pressing
additional keys such as the arrow keys to move relative to the current
item. Any additional press of the main navigation key (generally the
Tab key) will move out of the container to the next widget.
For example, a grid
may be used as a spreadsheet with thousands of gridcell
s,
all of which may not be present in the document at one time. This
requires their focus to be managed by the container using the aria-activedescendant
property, on the managing container element, or by the container managing the tabindex
of its child elements and setting focus on the appropriate child. For more information, see Providing Keyboard Focus in WAI-ARIA Best Practices ([ARIA-PRACTICES], section 3.2).
Containers that manage focus in this way are:
2.4. Features Managed by the User Agent
Editorial Note: Content is expected to come from the ARIA User Agent Implementors Guide.
There are things like focused, focusable, selected, selectable,
checkable, etc. Certain roles also have to be treated specially.
2.5. Building Accessible
Applications with WAI-ARIA
This
section provides a brief introduction to the process of making
applications accessible using ARIA. The choice and usage of roles can
be complex and context dependent. It is beyond the scope of this
document to explain implementations for all the possible ARIA use
cases. ARIA Best Practices [ARIA-PRACTICES] provides detailed guidance on ARIA implementation methodology as well as references to sample code.
First steps to making an application accessible:
- Each element or widget has full and correct semantics that fully describes its behavior (using element names or roles);
- The relationships between elements and groups are known;
- States, properties, and container relationships are valid for each element's behavior and are accessible via the Document Object Model [DOM] and the platform accessibility API;
- There is an element with input focus.
ARIA
provides authors with the means to make the different elements in a Web
application semantically rich. User agents use the role semantics to
understand how to handle each element. Roles convey missing information
that the assistive technology needs to anticipate the behavior of the
elements inside the application such as how to present the
corresponding ARIA states and properties to the user. The user agent
will use the accessibility semantics from the host language and ARIA
accessibility semantics which may override those of the host language
and present them to an assistive technology through the Document Object
Model or the platform accessibility API. When supporting the platform
accessibility API the user agent will create accessible objects
containing the accessibility semantics for each visual element on your
page. It will use the chosen API to notify the assistive technology of
changes to the semantics as well.
The following steps are recommended as ARIA is applied to content:
-
Use native markup when possible
Use
the semantic elements that are defined in the host markup language. For
example, with XHTML it is better to use the native checkbox than to use
a div element with role checkbox
as these should already be accessible through your browser. There may
also be cases where ARIA can augment an existing element in the host
language. For example, a grid
and gridcell
s
can reuse the functionality of a table when overlaying it. ARIA roles,
states, and properties are best used when the markup language does not
support all the semantics required. When a role attribute is added to
an element, the semantics and behavior of the element are overridden by
the role behavior.
-
Apply the appropriate roles from ARIA
Set
roles to make sure elements behave predictably and correctly describe
the behavior of each element within the application (unless elements
behaviors are fully described by the native markup language). Roles for
interactive elements should support all the states that the element
could use. Once a role attribute is set it should not be changed as
this could confuse an assistive technology. This does not preclude an
element being removed which has the role attribute set. Only states and
properties may be changed for a given element.
-
Preserve semantic structure
Structural
information is critical to providing context to people with
disabilities. This is achieved through preserving DOM hierarchy within
structural elements and widgets; forming logical groups within within
user interface widgets such as treeitem
s in a group
.
Look for groups within a page, and mark them using the most appropriate
role that best describes their usage. For example: a region of the page
that contains a group of elements that are likely to change through an
Ajax application could be tagged as a region
.
The preservation of semantic web structure involves your entire web
page such as through the use of document landmarks to facilitate
keyboard navigation for screen reader and mobility impaired users as
well as page restructuring and simplification for users with cognitive
and learning impairments.
-
Build relationships
Look
for relationships between elements, and mark them using the most
appropriate property or attribute. For example: If container A contains
search results, and container B contains the search widgets, then mark
each container as a region
and set the aria-controls
property in region B to reference region A. See relationships in WAI-ARIA.
Some relationships are determined automatically from the host language, such as by using the label
tag in HTML.
-
Set and properties in response to events
Once
the role for an element has been set, select the appropriate states and
properties for that role during the element's life cycle. This is often
done in response to user input events. States are special properties
for widgets that may change frequently during a widget's life cycle due
to user interaction, while properties are more stable attributes of
objects. User agents should notify assistive technology of state
changes. Conversely, assistive technology notification of property
changes depends on the method by which an assistive technology
communicates with the user agent. For example, the aria-multiline
property is not something that changes frequently, whereas the aria-checked
state changes frequently in response to user input.
When
setting states and properties, set them until the behavior of the
element is fully defined. Only use those supported for the chosen role
or element as defined in this specification.
-
Support full, usable keyboard navigation
Usable
keyboard navigation in a rich internet application is different from
the tabbing paradigm in a static document. Rich internet applications
behave more like desktop applications where the user tabs to
significant widgets and uses the arrow keys to navigate within the
widget, such as a spreadsheet or menu. The changes that ARIA introduces
in keyboard navigation makes this enhanced accessibility possible. For
a more in-depth understanding of keyboard navigation in ARIA, see the ARIA Best Practices [ARIA-PRACTICES]
-
Synchronize the visual UI with accessibility states properties for supporting user agents
This will allow the state of your UI to be perceivable to the user as well as the assistive technology. There are many ways to do this using script or by using CSS attribute selectors (in conforming user agents) For example, the author should have an associated selector that responds to a form element being aria-required
or a gridcell being aria-selected
. Refer to the ARIA Best Practices [ARIA-PRACTICES] for techniques for proper UI synchronization with the accessible state of the document.
2.6. Example: building a tree widget
A
basic tree view allows the user to select different list items and
expand and collapse embedded lists. Arrow keys are used to navigate
through a tree, including left/right to collapse/expand sub trees.
Double clicking with the mouse also toggles expansion.
Building
this user interface element with script could leave assistive
technology guessing about the role of each element. To make this
feature accessible we need to:
- Inform assistive technology about the role of each element, so they know how to handle it;
- Inform assistive technology about the relationships between tree items;
- Give a clear keyboard focus that will not confuse users with disabilities;
- Expose the changing states (e.g., open and closed) of the the tree items.
We can do that by following the steps below:
-
Look at the native mark up language
There
is no tree element in HTML that supports our behavior including
expansion. If such an element existed, we should use that to take
advantage of existing support. Since it does not, we will need to use
roles.
-
Finding the right roles
As
we did not find a tree element in the native mark up we need to add
roles that do this by referencing roles from this taxonomy that support
states that we need.
Our tree will need roles that support
embedded list behavior and expandable/collapsible embedded lists. The
roles that support tree behavior for a tree are:
tree
: A tree is the main container element for our tree. It is a form of a select
where sub-level groups of treeitems may be collapsed and expanded.treeitem
:
A treeitem is an option item of a tree. This is an element within a
tree; sub-level groups of treeitems may be expanded or collapsed.
-
Look for groups and build relationships
Tree
relationships can be made simply via the DOM and logical structure of
the page. A tree element will be the main container encompassing all
other elements in the tree. Each selectable item in the tree will be a
treeitem.
When a treeitem contains an embedded list of
treeitems they will be all embedded in a group. A group should be
contained inside the tree item that is the parent item.
Tree relationships are like list relationships in HTML. Group and tree elements act like list containers (ol
and ul
). A tree item acts like a list item (li
) in HTML.
Because treeitems and groups commonly both use div
elements it is recommended to add a comment next to closing treeitems that contain embedded tree groups.
<div role="tree">
<div >Veggies</div>
<div role="group"> <!-- veggies children ->
<div role="treeitem">Green</div>
<div role="group"> <!-- green children -->
<div role="treeitem">Asparagus</div>
<div role="treeitem">Kale</div>
<div role="treeitem">Leafy</div>
<div role="group"> <!-- leafy children -->
<div role="treeitem">Lettuce</div>
<div role="treeitem">Kale</div>
<div role="treeitem">Spinach</div>
<div role="treeitem">Chard</div>
</div> <!-- close leafy -->
<div role="treeitem">Green beans</div>
</div> <!-- close green -->
<div role="treeitem">Legumes</div>
<div role="treeitem">Yellow</div>
<div role="group"> <!-- yellow children -->
<div role="treeitem">Bell peppers</div>
<div role="treeitem">Squash</div>
</div> <!-- close yellow -->
</div> <!-- close veggies -->
</div> <-- close tree -->
Sometimes
a tree structure is not explicit via the DOM and logical structure of a
page. In such cases the relationships must still be made explicit using
the states and properties. In the following example, the aria-owns
property indicates that the item with id "yellowtreegroup" should be considered a child of the div
element with the property, even though it is not a child in the DOM.
<div role="treeitem" aria-owns="yellowtreegroup">Yellow<div>
…
<div id="yellowtreegroup" role="group">
<div role="treeitem">Bell peppers</div>
<div role="treeitem">Squash</div>
…
</div>
If the tree is not completely represented in the DOM at all times, don't use either the structured or aria-owns
methods. Instead use aria-level
, aria-posinset
and aria-setsize
.
-
Use States, Properties in response to events
Control the behavior of the element in response to user input events such as from the keyboard and the mouse as shown here:
<div tabindex="-1" role="treeitem" aria-expanded="true"
onclick="return toggleExpansion(event)"
onkeydown="return processArrowKeystoToggleExpansion(event);"
>Yellow</div>
Use device independent events with supporting JavaScript to
handle user interaction:
<div role="tree" tabindex="-1"
onfocus="return treeItemFocus(event);"
onclick="return treeItemEvent(event);"
ondblclick="return treeItemEvent(event);"
onkeydown="return treeItemEvent(event);">
Create JavaScript support to control the event driven behavior of the application.
4. The Roles Model
This section is normative.
This
section defines the WAI-ARIA role taxonomy and describes the
characteristics and properties of all roles. A formal RDF
representation of all the information presented here is available in Appendix 8.1: Implementation.
4.1. Relationships between concepts
The
role taxonomy uses the following relationships to relate ARIA roles to
each other and to concepts from other specifications, such as HTML and
XForms.
4.1.1. Parent Roles
- RDF Property
- rdfs:subClassOf
The
role that this role extends in the taxonomy. This extension causes all
the properties and constraints of the parent role to propagate to the
child role. Other than well known stable specifications, inheritance
may be restricted to items defined inside this specification so that
items cannot be changed and affect inherited classes.
For example: checkbox
is a subclass or type of a option
. If we change the properties and expected behavior of an option
then the properties and behavior of checkbox
will also change.
Inheritance is expressed in RDF using the RDF Schema subClassOf ([RDFS], section 3.4) property.
4.1.2. Child Roles
- RDF Property
- <none>
Informative
list of roles for which this role is the parent. This is provided to
facilitate reading of the specification but adds no new information as
the list of child roles is the list of roles for which the current role
is the parent.
4.1.4. Base Concept
- RDF Property
- role:baseConcept
Informative
information about objects that are considered prototypes for the role.
Base concept is similar to type, but without inheritance of limitations
and properties. Base concepts are designed as a substitute for
inheritance for external concepts. A base concept is like a relatedConcept except that base concepts are almost identical to each other.
For example: the checkbox
defined in this document has the same functionality and anticipated behavior as a checkbox defined in HTML.
Therefore, a checkbox
has an HTML checkbox
as a baseConcept
. However, if the HTML checkbox is modified, the definition of a checkbox
in this document will not be not affected, because there is no actual inheritance of type.
4.2. Characteristics of Roles
Roles
are defined and described by their characteristics. Characteristics
define the structural function of a role, such as what a role is,
concepts behind it, what instances of the role can or must contain. In
the case of widgets this also includes how it interacts with the user
agent based on mapping to HTML forms and XForms. States and properties
from WAI-ARIA that are supported by the role are also indicated.
The
Roles Taxonomy defines the following characteristics. These
characteristics are implemented in RDF as properties of the OWL classes
that describe the roles.
4.2.1. Is Abstract
- RDF Property
- N/A
- Values
- Boolean
Abstract roles are the foundation upon which all other ARIA roles are built. They MUST NOT be used by authors because they are not implemented in the API binding. Abstract roles are provided to help with the following:
- Organize the role taxonomy and provide roles with a meaning in the context of known concepts.
- Streamline the addition of roles that include appropriate features.
4.2.2. Required States and Properties
- RDF Property
- role:supportedState
- Values
- Any valid RDF object reference, such as a URI or RDF ID reference.
States and properties required for the role. Content authors MUST provide values for required states and properties.
When
an object inherits from multiple ancestors and one ancestor indicates
that property is supported while another ancestor indicates that it is
required, the property is required in the inheriting object.
4.2.3. Supported States and Properties
- RDF Property
- role:supportedState
- Values
- Any valid RDF object reference, such as a URI or RDF ID reference.
States and properties applicable to the role. User agents MUST support all supported states and properties for the role. Content authors MAY provide values for supported states and properties, but may not in all cases because default values are sufficient.
4.2.4. Inherited States and Properties
Informative
list of properties that are inherited onto a role from ancestor roles.
States and properties are inherited from ancestor roles in the role
taxonomy, not from ancestor elements in the DOM tree. These properties
are not explicitly defined on the role, as the inheritance of
properties is automatic. This information is provided to facilitate
reading of the specification. Inherited states and properties that are
required are indicated as such in this field as well. The set of
supported states and properties combined with inherited states and
properties forms the full set of states and properties supported by the
role.
4.2.5. Required Child Elements
- RDF Property
- role:mustContain
- Values
- Any valid RDF object reference, such as a URI or RDF ID reference.
A
child element that must be contained in the DOM by this role. A child
element is any descendent element specified with the required child
role. For example, an element with role list
must contain an element with role listitem
.
When multiple required children are indicated, either of them are permitted.
4.2.6. Parent Element
- RDF Property
- role:scope
- Values
- Any valid RDF object reference, such as a URI or RDF ID reference.
Context where this role is allowed, in other words, roles for elements in which the present role MUST appear.
For example an element with role listitem
MUST be contained inside an element with role list
.
4.2.7. Name From
- 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
property, aria-labelledby
property, or the HTML title
attribute. - contents:
name comes from the text value of the element node. Although this may
be allowed in addition to "author" in some roles, this is used in
content only if "author" features are not provided.
User agents MUST use the following approach to compute the accessible name for an element. Start with an empty string:
- Prepend
a space if necessary: if the current node is an element and is not
styled with display: inline, append a space character if the name
result string is not currently empty. This space character should be
removed at the end, if the entire name computation for an element
yields no other results.
- Compute the name string for the current node:
- If the current node is hidden and its ID is not explicitly pointed to for this calculation with
aria-labelledby
or aria-describedby
, then skip the current node. - Else if the current node is a text node, append the text contents. Whitespace may be normalized.
- Else if
aria-label
is present, use the value of the aria-label
property for the accessible name. - Else if
aria-labelledby
is present, and this node is the root node for the current name calculation, and was not arrived at via another aria-labelledby
, then process use aria-labelledby
to generate the name for this node. Within the aria-labelledby
value, process the IDs in the order they occur and ignore IDs in that
are not specified on an element in the document. For each ID's
associated element, implement this name computation starting with step
1, appending the results to the total name result string as they are
collected. - Else if the native markup provides a text
equivalent, append it to the accessible name. An example of a native
markup text equivalent is alt for HTML
<img>
. - If the current node is not at the beginning or end of a name computation, append the current value for the node.
- If
the accessible name text for this node is not empty, and the current
node's role allows "Name From: contents", recursively implement this
name computation for each child, starting with step 1, appending the
results to the total name result string as they are collected. If this
recursion only produces white space, consider the name text for the
current node to be empty, and use the following rule instead.
- Else
if the accessible name text for this node is still empty, use the
tooltip attribute for the given markup language (e.g. title in HTML,
tooltiptext in XUL) of the current node.
- Append
a space if necessary: if the current node is an element and is not
styled with display: inline, append a space character. This last space
should be trimmed off if it ends up being last character in the entire
name computation for an element.
4.2.8. Children Presentational
- RDF Property
- role:childrenArePresentational
- Values
-
Boolean (true | false)
The DOM children are presentational. User agents SHOULD NOT
expose descendants of this element through the platform accessibility
API. If user agents do not hide the children, some information may be
read twice.
4.3. Global States and Properties
Some
states and properties are applicable to all roles, and most are
applicable to all elements regardless of role. In addition to
explicitly expressed supported states and properties, the following
global states and properties are supported by all roles as well. These
include:
Global states and properties are applied to the role roletype
,
which is the base role, and therefore inherit into all roles. To
facilitate reading, they are not explicitly identified as either
supported or inherited states and properties in the specification.
Instead, the inheritance is indicated by a link to this section.
4.4. Categorization of Roles
To
support the current user scenario, this specification defines roles
that help define widgets (for example, a slider control) and help
define page structure (for example, a section header).
Roles are categorized as follows:
- Base Types
- User Input Widgets
- User Interface Elements
- Document Structure
- Specialized Regions
- Landmark Roles Inherited from the XHTML Role Attribute Module
- Section Roles inherited from XHTML Role Attribute Module
4.4.1. Base Types
The
following roles are used as base types for applied roles. Base classes
are used to build a picture of the role taxonomy class hierarchy within
the taxonomy. Note that while all roles in this section are abstract,
not all abstract roles are in this section. This section includes only
the most high-level abstractions in the taxonomy.
4.4.3. User Interface Elements
These roles encompass features that usually are used as part of the graphical user interface.
4.4.4. Document Structure
These
roles describe the structures that organize content in a page. In
contrast to widgets, structures are not usually interactive. However,
they can be in certain circumstances.
4.4.5. Specialized Regions
These are special types of self-contained aspects of the user interface.
4.4.6. Landmark Roles Inherited from the XHTML Role Attribute Module
This section includes roles imported from the XHTML Role Attribute Module [XHTML-ROLES,
Section 4]. These roles are included here in order to make them clearly
part of the ARIA Role taxonomy. Role descriptions are taken from the
description provided in the XHTML Role Attribute Module.
4.4.7. Section Roles inherited from XHTML Role Attribute Module
4.5. Definition of Roles
Below is an alphabetical list of ARIA roles to be used by rich internet application authors.
Note: Abstract roles are used for the ontology. Authors must not use abstract roles in content.
alert
- A message with important information.
alertdialog
- A separate window (may be simulated) with an alert, where initial focus goes to the window or a widget within it.
application
- A software unit executing a set of tasks for its users.
article
- Represents a section of a page consisting of a composition forming an independent part of a document, page, or site.
banner
- A region that contains the prime heading or internal title of a page.
button
- Allows for user-triggered actions.
checkbox
- A widget that has three possible values: "true", "false", or "mixed".
columnheader
- A table cell containing header information for a column.
combobox
- Combobox is a presentation of a select, where users can type to select an item.
complementary
- Any
section of the document that supports but is separable from the main
content, but is meaningful on its own even when separated from it.
composite
(abstract role)- A widget that may contain navigable descendants or owned children.
contentinfo
- Meta information which applies to the first immediate ancestor whose role is not presentation.
definition
- A definition of a term or concept.
description
- Descriptive content for a page element.
dialog
- A
dialog is a small application window that sits above the application
and is designed to interrupt the current processing of an application
in order to prompt the user to enter information or require a response.
directory
- A list of references to members of a single group.
document
- Content that contains related information.
grid
- A grid contains cells of tabular data arranged in rows and columns (e.g., a table).
gridcell
- A cell in a grid.
group
- A
section of user interface objects which would not be included in a page
summary or table of contents by an assistive technology.
heading
- A heading for a section of the page.
img
- A container for a collection of elements that form an image.
input
(abstract role)- Generic type for widgets for which users can input a value.
link
- Interactive reference to a resource.
list
- Group of non-interactive list items.
listbox
- A widget that allows the user to select one or more items from a list of choices.
listitem
- A single item in a list.
log
- A region where new information is added and old information may disappear.
main
- Main content in a document.
marquee
- A marquee is used to scroll text across the page.
math
- Content that represents a mathematical expression.
menu
- Offers a list of choices to the user.
menubar
- A container of menu items (items with role menuitem).
menuitem
- An option in a group of choices contained in a menu.
menuitemcheckbox
- Defines a menuitem which is checkable.
menuitemradio
- Indicates a menuitem which is part of a group of menuitemradio roles, only one of which can be checked at a time.
navigation
- A collection of links suitable for use when navigating the document or related documents.
note
- The content is parenthetic or ancillary to the main content of the resource.
option
- A selectable item in a list represented by a select.
presentation
- An element whose role is decorative, not meaningful, and does not need to be mapped to the accessibility API.
progressbar
- Displays the execution status for tasks that take a long time to execute.
radio
- An option in single-select list.
radiogroup
- A group of radio buttons.
range
(abstract role)- Represents a range of values that can be set by the user.
region
- Region is a large perceivable section on the web page.
roletype
(abstract role)- Base role from which all other roles in this taxonomy inherit.
row
- A row of grid cells.
rowheader
- A table cell containing header information for a row.
search
- The search tool of a web document.
section
(abstract role)- A renderable structural containment unit in a document or application.
sectionhead
(abstract role)- 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 line or bar that separates and distinguishes sections of content.
slider
- A user input where the user selects a value from within a given range.
spinbutton
- A form of range that expects a user to select from amongst discrete choices.
status
- Container for processing advisory information to give feedback to the user.
structure
(abstract role)- A document structural element.
tab
- A header for a tabpanel.
tablist
- A list of tabs, which are references to tabpanels.
tabpanel
- A container for the resources associated with a tab.
textbox
- Inputs that allow free-form text as their value.
timer
- A numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.
toolbar
- A collection of commonly used functions represented in compact visual form.
tooltip
- A
popup that displays a description for an element when a user passes
over or rests on that element. Supplement to the normal tooltip
processing of the user agent.
tree
- A form of a list having groups inside groups, where sub trees can be collapsed and expanded.
treegrid
- A grid whose rows can be expanded and collapsed in the same manner as for a tree.
treeitem
- An option item of a tree. This is an element within a tree that may be expanded or collapsed.
widget
(abstract role)- A component of a Graphical User Interface (GUI).
window
(abstract role)- Browser or application window.
alert
(role)
A message with important information.
Alerts
are used to convey messages to alert the user. In the case of audio
warnings this is an accessible alternative for a hearing impaired user.
The alert role goes on the node containing the alert message. Alerts
are specialized forms of the status
role, which should be processed as an atomic live region.
Alerts do not require user input and therefore should not receive focus. Since alerts do not receive focus users SHOULD NOT be required to close an alert. The user agent MAY fire an accessibility alert event, when the alert is created, provided one is specified by the intended accessibility API. If an alert requires focus to close the alert, then an alertdialog
SHOULD be used instead.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Child Roles: | |
Related Concepts: | XForms alert |
Inherited States and Properties: | |
Name From: | author |
alertdialog
(role)
A separate window (may be simulated) with an alert, where initial focus goes to the window or a widget within it.
Alert dialogs are used to convey messages to alert the user. The alertdialog role goes on the node containing the alert message.
Unlike alert
, alertdialog
can receive a response from the user, such as to confirm that the user
understands the alert being generated. When the alert dialog is
displayed, authors MUST set focus to an active element within the alert dialog, such as a form edit field or an ok pushbutton. The user agent MAY fire an accessibility alert event, when the alert is created, provided one is specified by the intended accessibility API.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Related Concepts: | XForms alert |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
application
(role)
A software unit executing a set of tasks for its users.
The
intent is to hint to the assistive technology to switch its normal
browsing mode functionality to one in which they would for an
application. Screen readers have a browse navigation mode where keys,
such as up and down arrows, are used to browse the document. This
breaks use of these keys by a web application.
To properly set the role of application
, an author should set the application
role on an element which encompasses the entirety of the region for
which assistive technology browser navigation mode is applied. If it
applies to the entire Web page, it should be set on the root node for
content, e.g., body
in HTML or svg
in SVG.
For
example, an email application has a document and an application in it.
The author would want to use typical application navigation mode to
cycle through the list of emails. Much of this navigation would be
defined by the application author. However, when reading an email
message the content should appear in a region with a document
role in order to use browsing navigation.
All non-decorative static text or image content inside the application must be either associated with a form widget or group
via aria-label
, aria-labelledby
, or aria-describedby
, or separated out into an element with role of document
or article
of its own.
Applications MUST
have a document title or label. This should be suitable for use as a
navigation preview or table-of-contents entry for the page section in
question. The label SHOULD come from one of the following sources:
- The
title
element in HTML labels the entire document; - Any
group
element may contain a non-empty aria-label
property; - Any
group
element in SVG may contain a non-empty title
element; - The element with the
application
role may have a aria-labelledby
property referencing one or more elements with non-empty text content.
Editorial note: Suggest removing "in SVG" from item 3 because title is not limited to SVG.
article
(role)
Represents a section of a page consisting of a composition forming an independent part of a document, page, or site.
An
article could be a forum post, a magazine or newspaper article, a Web
log entry, a user-submitted comment, or any other independent item of
content. It is "independent" in that its contents could stand alone,
for example in syndication. However, the element is still associated
with its ancestors; for instance, contact information that applies to a
parent body element still covers the article as well. When nesting
articles, the inner articles represent articles that are in principle
related to the contents of the outer article. For instance, a Web log
entry on a site that accepts user-submitted comments could represent
the comments as articles nested within the article for the Web log
entry. Author, heading, date or other information associated with an
article does not apply to nested articles. Assistive technologies must
treat and article like a document in that article must must be
processed like an application. Unlike a document, the use of articles
allows the user to identify them and follow related articles based on
the nesting.
When applying the article to a host language
element, ensure that the element and the corresponding end tag wrap the
entire article.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Related Concepts: | HTML 5 article |
Inherited States and Properties: | |
Name From: | author |
banner
(role)
A region that contains the prime heading or internal title of a page.
Most
of the content of a banner is site-oriented, rather than being
page-specific. Site-oriented content typically includes things such as
the logo of the site sponsor, the main heading for the page, and
site-specific search tool. Typically this appears at the top of the
page spanning the full width.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
checkbox
(role)
A widget that has three possible values: "true", "false", or "mixed".
Many checkboxes do not use the "mixed" value, and thus are effectively boolean checkboxes. However, the aria-checked
state supports the "mixed" value to support cases such as installers where an option has been partially installed.
Characteristics:Characteristic | Value |
---|
Parent Roles: | input |
Child Roles: | |
Related Concepts: |
|
Required States and Properties: | aria-checked |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
columnheader
(role)
A table 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 a structural equivalent to an HTML th
element with a "column" scope.
Note:
because grid cells are organized into rows, there is not a single
container element for the column. The column is the set of gridcell
s in a particular position within their respective row
containers.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Base Concept: | HTML th with scope=col |
Parent Element: | row |
Supported States and Properties: | aria-sort |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
combobox
(role)
Combobox is a presentation of a select
, where users can type to select an item.
Combobox
is the combined presentation of a single line textbox with a drop down
select widget. The combobox may be editable. Typically editable combo
boxes are used for autocomplete behavior, and the autocomplete property
would be used on the child textbox.
NOTE: In XForms [XFORMS] the same select
can have one of 3 appearances: combo-box, drop-down box, or group of
radio-buttons. Many browsers (if not all of them) allow users to type
in a drop-down select as well. This specification does not constrain
the presentation of the combobox.
Instances of this role MUST manage focus of descendants, as described in Managing Focus.
Characteristics:Characteristic | Value |
---|
Parent Roles: | select |
Related Concepts: |
|
Required Child Elements: | listbox |
Required States and Properties: | aria-expanded |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
complementary
(role)
Any
section of the document that supports but is separable from the main
content, but is meaningful on its own even when separated from it.
There
are various types of content that would appropriately have this role.
For example, in the case of a portal, this may include but not be
limited to show times, current weather, related articles, or stocks to
watch. The content should be relevant to the main content; if it is
completely separable, a more general role should be used instead.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
composite
(abstract role)
A widget that may contain navigable descendants or owned children.
The composite widget SHOULD exist as a single navigation stop within the larger navigation system of the web page. Once the composite widget has focus, it SHOULD
provide a separate navigation mechanism for users to document elements
that are descendants or owned children of the composite element.
Descendants of this role MUST NOT have the "nameFrom" value of "contents" set. This role and its descendants must not have a childrenArePresentational value of "true".
Note: composite
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | widget |
Child Roles: | |
Supported States and Properties: | aria-activedescendant |
Inherited States and Properties: | |
Name From: | author |
Children Presentational: | False |
contentinfo
(role)
Meta information which applies to the first immediate ancestor whose role is not presentation.
In
the context of the page this would apply to a section or the page of
which it is the child. For example, footnotes, copyrights, links to
privacy statements, etc. would belong here.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
definition
(role)
A definition of a term or concept.
A
role is not provided to specify the term being defined, although host
languages may provide such an element; in HTML this is the dfn
element. The defined term should be included in such an element even when occurring within an element having the definition
role.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Name From: | author |
description
(role)
Descriptive content for a page element.
A description
MUST be referenced from the element it describes via aria-describedby
.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Child Roles: | |
Inherited States and Properties: | |
dialog
(role)
A
dialog is a small application window that sits above the application
and is designed to interrupt the current processing of an application
in order to prompt the user to enter information or require a response.
Dialog boxes SHOULD have a title, which may be provided with an aria-label
or aria-labelledby
property if other mechanisms are not available. They MUST have a focused descendant element that has keyboard focus.
Characteristics:Characteristic | Value |
---|
Parent Roles: | window |
Child Roles: | |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
directory
(role)
A list of references to members of a single group.
Authors SHOULD
use this role for static tables of contents. This includes tables of
contents built with lists, including nested lists. Dynamic tables of
contents, however, would be a tree
.
Note: directories do not have to contain links. They can have simply unlinked references.
Characteristics:Characteristic | Value |
---|
Parent Roles: | list |
Child Roles: | |
Related Concepts: | DAISY Guide |
Inherited States and Properties: | |
Name From: |
|
document
(role)
Content that contains related information.
The
document role informs screen readers of the need to augment browser
keyboard support in order to allow users to visit and read any content
within the document region. In contrast, additional commands are not
necessary for screen reader users to read text withn a region with
role="application", where all text should be semantically associated
with focusable elements. An important trait of documents is that they
have some text which is not associated with widgets or groups thereof.
To properly set the role of document
, an author should set the document
role on an element which encompasses the entirety of the region for
which assistive technology browser navigation mode is applied.If it
applies to the entire Web page, it should be set on the root note for
content, e.g., body
in HTML or svg
in SVG.
Documents MUST
have a document title or label. This should be suitable for use as a
navigation preview or table-of-contents entry for the page section in
question. The label SHOULD come from one of the following sources:
- The
title
element in HTML labels the entire document; - Any
group
element may contain a non-empty aria-label
property; - Any
group
element in SVG may contain a non-empty title
element; - The element with the
document
role may have a aria-labelledby
property referencing one or more elements with non-empty text content.
Editorial note: Suggest removing "in SVG" from item 3 because title is not limited to SVG.
grid
(role)
A grid
contains cells of tabular data arranged in rows and columns (e.g., a table).
This does not necessarily imply presentation. The grid
construct describes relationships between data such that it may be used
for different presentations. Grids allow the user to move focus between
grid cells with two dimensional navigation.
Grids MUST contain rows with role row
, which in turn contain cells. Grid cells may be focusable. Grids MAY have row and column headers, provided with rowheader
and columnheader
roles, which also assist the user agent in supporting navigation. Grid cells MAY have contents determined by a calculation.
Grid cells with the aria-selected
state set can be selected for user interaction, and multiple cells can be selected if the aria-multiselectable
property of the grid
is true. Grids may be used for spreadsheets like those in Open Office, Microsoft Office, etc.
Instances of this role MUST manage focus of descendants, as described in Managing Focus.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Child Roles: | |
Base Concept: | HTML table |
Required Child Elements: | row |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
gridcell
(role)
A cell in a grid.
Grid cell may be active, editable, and selectable. Cells may have relationships such as aria-controls
to address the application of functional relationships.
Grid cells should explicitly indicate which header cells are relevant to them. They do this by referencing elements with role rowheader
or columnheader
using the aria-describedby
property.
In a treegrid, cells MAY be expandable and use the aria-expanded
state. If the aria-expanded
property 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 property on a cell is pivot table type behavior.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Child Roles: | |
Base Concept: | HTML td |
Parent Element: | row |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
group
(role)
A section of user interface objects which would not be included in a page summary or table of contents by an assistive technology.
Contrast with region
which is sections of user interface objects that should be included in a page summary or table of contents.
Authors should use a group
to form logical collection of items in a widget such as children in a
tree widget forming a collection of siblings in a hierarchy, or a
collection of items having the same container in a directory.
Therefore, proper handling of group by assistive technologies must be
determined by the context in which it is provided.
Groups
may also be nested. If the author believes a section is significant
enough in terms of the entire delivery unit web page then the author
should assign the section a role of region
or a standard landmark role.
Group
members that are not a DOM descendant of the group would need to have
explicit relationships assigned to participate in the group using the aria-owns
property.
heading
(role)
A heading for a section of the page.
This indicates that an object serves as a header. Often, heading
s will be referenced with the aria-labelledby
property of the section for which they serve as a header. If headings are organized into a logical outline, the aria-level
property can be used to indicate the nesting level.
Characteristics:Characteristic | Value |
---|
Parent Roles: | sectionhead |
Related Concepts: |
|
Supported States and Properties: | aria-level |
Inherited States and Properties: | |
Accessible Name Required: | True |
img
(role)
A container for a collection of elements that form an image.
An img
can contain captions and descriptive text, as well as multiple image
files that when viewed together give the impression of a single image.
An img
represents a single graphic within a document,
whether or not it is formed by a collection of drawing objects.
Elements with a role of img MUST have alternative text or a label associated via the aria-label
or aria-labelledby
property.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Related Concepts: | DTB imggroup |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
link
(role)
Interactive reference to a resource.
Activating the link causes the user agent to navigate to that resource.
Characteristics:Characteristic | Value |
---|
Parent Roles: | widget |
Related Concepts: | HTML link |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
list
(role)
Group of non-interactive list items.
Lists contain children whose role is listitem
, or elements whose role is group
which in turn contains children whose role is listitem
.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Child Roles: | |
Base Concept: | HTML ul |
Required Child Elements: |
|
Inherited States and Properties: | |
Name From: | author |
listbox
(role)
A widget that allows the user to select one or more items from a list of choices.
Items within the list are static and may contain images. List boxes contain children whose role is option
.
Instances of this role MUST manage focus of descendants, as described in Managing Focus.
Although listbox
inherits the aria-expanded
state, if there is a use case to use that state, authors should consider using a combobox
instead.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Related Concepts: |
|
Required Child Elements: | option |
Supported States and Properties: | aria-multiselectable |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
listitem
(role)
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Child Roles: | |
Base Concept: | HTML li |
Related Concepts: | XForms item |
Parent Element: | list |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
log
(role)
A region where new information is added and old information may disappear.
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.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
main
(role)
Main content in a document.
This marks the content that is directly related to or expands upon the central topic of the page.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
marquee
(role)
A marquee is used to scroll text across the page.
A common usage is a stock ticker. A marquee
behaves like a live region, with an assumed default aria-live
property value of "off". An example of a marquee is a stock ticker. A major difference between a marquee and a log
is how fast it gets updates from timed or real world events.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Accessible Name Required: | True |
math
(role)
Content that represents a mathematical expression.
This
is for sections that represent math, such as images and ASCII art, but
are not in a formal mathematical language. Such images MUST be labeled by text that can be converted to an accessible format, using the aria-describedby
property with a reference to a description of the math expression as it
would be spoken. This is designed to facilitate conversion to speech.
The text description should have no special markup used to control a
speech device. Authors MAY store image alternative text in the image formats themselves. In these scenarios the alternative text from the image SHOULD also be brought into the text of the document and referenced by the aria-describedby
property.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Name From: | author |
Children Presentational: | True |
navigation
(role)
A collection of links suitable for use when navigating the document or related documents.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
note
(role)
The content is parenthetic or ancillary to the main content of the resource.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Inherited States and Properties: | |
Name From: | author |
option
(role)
A selectable item in a list represented by a select
.
An option MUST appear inside an element with select
role.
Characteristics:Characteristic | Value |
---|
Parent Roles: | input |
Child Roles: | |
Base Concept: | HTML option |
Related Concepts: |
|
Parent Element: | select |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
presentation
(role)
An element whose role is decorative, not meaningful, and does not need to be mapped to the accessibility API.
The
intended use is when an element is used to change the look of the page
but does not have all the functional, interactive, or structural
relevance implied by the element type.
Example use cases:
- A layout table;
- An
object
in HTML whose content is decorative like a white space
image or decorative object; - An image used for white space;
- A
div
in HTML used to force line breaks before and after its contents.
The user agent MAY choose not to present all structural aspects of the element being repurposed. For example, for a table marked as presentation
, the user agent would remove the table
, td
, th
, tr
,
etc. elements from the accessibility API mapping, while preserving the
individual text elements within them. Because the user agent knows to
ignore the structural aspects implied in a table, no harm is done by
using a table for layout.
User agents should
ignore elements with the presentation role for the purpose of
determining the containment of items with ARIA roles. For example, in
the following code sample:
<ul role="group">
<li role="presentation">
<span>...</span>
</li>
</ul>
The span
should be considered a child of the ul
element with the group
role.
Characteristics:Characteristic | Value |
---|
Parent Roles: | structure |
Inherited States and Properties: | |
progressbar
(role)
Displays the execution status for tasks that take a long time to execute.
This
lets the user know that the user's action request has been accepted and
that the application continues (or ceases, in the case of a static
display) to make 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 the property should be omitted. These values should be updated when the visual progress indicator is updated. If the progressbar
is describing the loading progress of a particular region of a page, the author SHOULD use aria-describedby
to point to the status, and set the aria-busy
state to "true" on the region until it is finished loading.
Characteristics:Characteristic | Value |
---|
Parent Roles: | widget |
Related Concepts: | status |
Supported States and Properties: |
aria-valuetext |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
radio
(role)
An option in single-select list.
Elements with role radio
MUST
be be explicitly grouped in order to indicate which ones affect the
same value. This should be done by enclosing them in an element with
role radiogroup
. If it is not possible to make the radio buttons DOM children of the radiogroup
, use the aria-owns
property on the radiogroup
element to indicate the relationship.
Characteristics:Characteristic | Value |
---|
Parent Roles: | checkbox |
Child Roles: | |
Related Concepts: | HTML input (type : radio) |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
radiogroup
(role)
A group of radio
buttons.
A radiogroup
is a type of select
list that can only have single entries checked, not mutliple. Authors should
enforce that only one radio button in a radiogroup can be checked at
the same time. When another button is checked, previously checked
buttons become unchecked (their aria-checked
state becomes "false").
Characteristics:Characteristic | Value |
---|
Parent Roles: | select |
Related Concepts: | list |
Required Child Elements: | radio |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
range
(abstract role)
Represents a range of values that can be set by the user.
Note: range
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | input |
Child Roles: | |
Supported States and Properties: |
aria-valuetext |
Inherited States and Properties: | |
Name From: | author |
region
(role)
Region is a large perceivable section on the web page.
This
role defines a group of elements that together form a large perceivable
section, that the author feels should be included in a summary of page
features. A region
MUST have a heading, provided via an instance of the heading
role or using the aria-label
property or aria-labelledby
property to reference an element. A region does not necessarily follow
the logical structure of the content, but follows the perceivable
structure of the page.
When defining regions of a web page, authors should consider using standard document landmark roles. If the definition of these regions are inadequate, authors should use the region
role and provide the appropriate title text.
Characteristics:Characteristic | Value |
---|
Parent Roles: | section |
Child Roles: | |
Related Concepts: |
|
Inherited States and Properties: | |
Name From: | author |
roletype
(abstract role)
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 must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Child Roles: | |
Related Concepts: |
|
Supported States and Properties: | Placeholder for global properties |
Inherited States and Properties: | |
row
(role)
A row of grid cells.
Rows contain gridcell
s, and thus serve to organize the grid
.
In a treegrid
, rows MAY be expandable, using the aria-expanded
state to indicate the present status. This is not the case for an ordinary grid
, in which the aria-expanded
state is not present.
Characteristics:Characteristic | Value |
---|
Parent Roles: | group |
Base Concept: | HTML tr |
Parent Element: |
|
Required Child Elements: | gridcell |
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: |
|
search
(role)
The search tool of a web document.
This is typically a form used to submit search requests about the site or to a more general Internet search service.
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
section
(abstract role)
A renderable structural containment unit in a document or application.
Note: section
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | structure |
Child Roles: | |
Related Concepts: |
|
Inherited States and Properties: | |
Name From: |
|
sectionhead
(abstract role)
Labels or summarizes the topic of its related section.
Note: sectionhead
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | structure |
Child Roles: | |
Inherited States and Properties: | |
Name From: |
|
select
(abstract role)
A form widget that allows the user to make selections from a set of choices.
An element with role select
MUST contain elements with role option
.
Note: select
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: |
|
Child Roles: | |
Inherited States and Properties: | |
Name From: | author |
separator
(role)
A line or bar that separates and distinguishes sections of content.
This
is a visual separator between sections of content. For example,
separators are found between groups of menu items in a menu.
Characteristics:Characteristic | Value |
---|
Parent Roles: | structure |
Related Concepts: | HTML hr |
Inherited States and Properties: | |
Name From: | author |
Children Presentational: | True |
slider
(role)
A user input where the user selects a value from within a given range.
A
slider represents the current value and range of possible values via
the size of the slider and position of the thumb. It is typically
possible to add or subtract to the value by using directional keys such
as arrow keys.
Characteristics:Characteristic | Value |
---|
Parent Roles: | range |
Required States and Properties: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
Children Presentational: | True |
status
(role)
Container for processing advisory information to give feedback to the user.
A status
object must have content within it to provide the actual status information. This object SHOULD NOT receive focus.
Status is a form of live region. Its assumed default value for the aria-live
property is "polite".
If another part of the page controls what appears in the status, the relationship should be made explicit with the aria-controls
property.
Some cells of a Braille display MAY be reserved to render the status.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Child Roles: | |
Inherited States and Properties: | |
structure
(abstract role)
A document structural element.
Roles
for document structure support the accessibility of dynamic Web content
by helping assistive technology to determine active content vs. static
document content. Structural roles by themselves do not all map to
accessibility APIs, but are used to create widget roles or assist content adaptation.
The taxonomy of structural roles is likely to evolve as new use cases are added to the scope of this specification.
Note: structure
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | roletype |
Child Roles: | |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: | |
tab
(role)
A header for a tabpanel
.
tab
is used as a grouping label, providing a link for selecting the tab
content to be rendered to the user. If a tabpanel or item in a tabpanel
has focus, the associated tab is the currently active tab in the
tablist.
One, and only one, of the tabs in the tablist
MUST be the currently selected tab. The tabpanel associated with the current tab MUST be rendered to the user. Other tabpanel elements SHOULD be hidden from the user until the user selects the tab associated with that tabpanel. Authors MUST ensure the currently selected tab has the aria-selected
state set to true
while other tab elements SHOULD have aria-selected
set to false
. The currently selected tab SHOULD provide visual indication that it is selected. In the absence of a selected state on the current tab, user agents MUST indicate the currently active tab to assistive technologies through the platform accessibility API.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Parent Element: | tablist |
Inherited States and Properties: | |
Name From: |
|
tabpanel
(role)
Characteristics:Characteristic | Value |
---|
Parent Roles: | region |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
tablist
(role)
A list of tab
s, which are references to tabpanel
s.
Instances of this role MUST manage focus of descendants, as described in Managing Focus.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Related Concepts: | DAISY Guide |
Required Child Elements: | tab |
Inherited States and Properties: | |
Name From: |
|
textbox
(role)
Inputs that allow free-form text as their value.
If the aria-multiline
property is true, the widget accepts line breaks within the input, as in a HTML textarea. Otherwise this is a simple text box.
Intended
use is in languages that do not have a text input object (such as SVG),
or cases in which an element with different semantics is repurposed as
an input box. Another use is for a rich text edit textbox, or one that
validates input as users type (perhaps marking specific subregions with
errors with the aria-invalid
state ).
Characteristics:Characteristic | Value |
---|
Parent Roles: | input |
Related Concepts: |
|
Supported States and Properties: |
|
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
timer
(role)
A numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.
The
text contents of the timer object indicate the current time
measurement, and are updated as that amount changes. However, the timer
value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point.
A timer is a form of live region. The default value of aria-live
for timer
is "off".
Characteristics:Characteristic | Value |
---|
Parent Roles: | status |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
tree
(role)
A form of a list
having groups inside groups, where sub trees can be collapsed and expanded.
Instances of this role MUST manage focus of descendants, as described in Managing Focus.
Characteristics:Characteristic | Value |
---|
Parent Roles: | select |
Child Roles: | |
Required Child Elements: | treeitem |
Supported States and Properties: | aria-multiselectable |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
treegrid
(role)
A grid
whose rows can be expanded and collapsed in the same manner as for a tree
.
Instances of this role MUST manage focus of descendants, as described in Managing Focus.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Required Child Elements: | row |
Inherited States and Properties: | |
Name From: | author |
Accessible Name Required: | True |
treeitem
(role)
An option item of a tree
. This is an element within a tree that may be expanded or collapsed.
A collection of treeitems to be expanded and collapsed are enclosed in a group
.
Characteristics:Characteristic | Value |
---|
Parent Roles: |
|
Parent Element: | tree |
Inherited States and Properties: | |
Name From: |
|
Accessible Name Required: | True |
window
(abstract role)
Browser or application window.
Elements with this role have a window-like behavior in a GUI context, regardless of whether they are implemented as a window in the OS. This is helpful when there is the visual appearance of a window that is merely a styled section of the document.
Note: window
is an abstract role used for the ontology. Authors must not use this role in content.
Characteristics:Characteristic | Value |
---|
Is Abstract: | True |
Parent Roles: | roletype |
Child Roles: | |
Supported States and Properties: | aria-expanded |
Inherited States and Properties: | |
Name From: | author |
6. Implementation in Host Languages
This section is normative.
6.1. Introduction
This section is informative.
The
roles, states, and properties defined in this specification do not form
a whole web language or format. They are intended to be used in the
context of a profile based on some host language or other. This section
discusses what host languages should do to implement WAI-ARIA, that is
to say assure that the markup specified here will integrate smoothly
and effectively with their markup in instances of their format.
Although
markup languages superficially look alike, they do not all share much
by way of language-definition infrastructure. To accomodate differences
in language-building approaches, the requirements here have been set
out at two levels, general, and modualrization-specific. While allowing
for differences in how the specifications are written, we believe we
have maintained consistency in how the WAI-ARIA information looks to
authors and how it is manipulated in the DOM by scripts.
ARIA
Roles, States, and Properties are implemented as attributes of
elements. Roles are applied by placing their names among the tokens
appearing in the value of a host-language-provided 'role' attribute.
States and properties each get their own attribute, with values as
defined for each particular state or property in this specification.
The name of the attribute is the name of the state or property.
6.2. General requirements on implementing host languages
6.2.1. Role attribute
An implementing host language MUST provide an attribute with the name 'role' with the following characteristics:
- the attribute value string for this attribute MUST allow a space-separated sequence of whitespace-free substrings;
- the appearance of the name literal of any concrete ARIA role (see section 7.3.2) as one of these substrings MUST NOT in and of itself make the attribute value illegal in the host-language syntax;
- the appearance of the name literal of any role defined in the Role Attribute Module [XHTML-ROLES] as one of these substrings MUST NOT in and of itself make the attribute value illegal in the host-language syntax;
- host
languages may define elements with strong semantics as regards
interaction and accessibility API binding that are immune to being
overridden by WAI-ARIA markup as defined in this document.
- the host language SHOULD
provide that, other than where a concrete ARIA role appears on one of
these immune elements, where the name literal of a concrete ARIA role
appears as one of the substrings in the space-separated list in 'role'
attribute value, that that value MUST be processed in accordance with this specification;
- the host language SHOULD provide that, other than where a role-module-defined role appears on one of these immune elements,
where the name literal of any role defined in the Role Attribute Module
appears as one of the substrings in the space-separated list in 'role'
attribute value, that that value MUST be processed in accordance with that specification.
6.2.2. State and property attributes
An implementing host language MUST allow attributes as follows:
- the
attribute name of one of these attributes is the name of any state or
property identified in Section 5 above, prefixed by "aria-", such as
"aria-busy", "aria-selected", "aria-activedescendant", "aria-valuetext";
- other
than where one of these attributes appears on an aria-immune element as
defined in the host language,the host language syntax MUST not prevent the attribute from appearing anywhere that it is applicable as specified in this specification;
- the host language MUST
provide that where these attributes are allowed in a document instance
of their format, these attributes are to be processed as provided in
this specification.
Editorial Note: Following the Namespaces Recommendation [XML-NAMES],
the namespace name for these attributes "has no value". The names of
these attributes do not have a prefix set off by a colon; in the terms
of Namespaces they are "unprefixed attribute names." The ECMASCRIPT
binding of the DOM interface getAttributeNS for example, treats an
empty string ("") as representing this condition, so that both getAttribute(aria-busy) and getAttributeNS("", aria-busy) access the same aria-busy attribute in the DOM.
6.2.3. Focus navigation
An implementing host language MUST provide support for
- the author to make arbitrary elements focusable;
- the
user to have device-independent capability and in particular keyboard
capability to navigate the focus to all focusable elements.
Editorial
note: do we have to move the user capability to navigate the focus to a
user agent requirement? What is the role of the host language in this?
6.2.4. Conflict with host language features
If
the host language incorporates ARIA support, and there is a conflict
between a host language feature and an ARIA feature, assistive
technologies should assign preference to the ARIA feature.
6.3. Implementation using the Modularization Recommendation
Host languages can be constructed using the methods of the W3C Recommendation Modularization in XHTML [@@ref2m12n].
Host languages that are constructed following this Recommendation MUST
implement the abstract module comprising the attributes defined in
section 5. above using a module implementation provided in this
specification.
Appendix 8.1.2 below provides an implementation of this module as a DTD module.
Appendix
8.1.3 below is a sample DTD integrating a language profile that
implements WAI-ARIA by including the DTD module. Note how the
applicability of the tabindex attribute has been extended to satisfy
6.2.3 above.
Editorial Note: The URIs to be used to identify the module are still under discussion.