This document provides readers with an understanding of how to use WAI-ARIA 1.1 [WAI-ARIA] to create accessible rich internet applications. It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties. This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers.
This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This is a Working Draft by the Accessible Rich Internet Applications Working Group of the Web Accessibility Initiative. It supports the WAI-ARIA 1.1 [WAI-ARIA] specification, providing detailed advice and examples beyond what would be appropriate to a technical specification but which are important to understand the specification. This version includes additional refinements to the authoring guidance.
This draft includes only a portion of content planned for the complete WAI-ARIA Authoring Practices 1.1. To see what is planned for future drafts and releases, review the Authoring Practices Milestone Plan.
Feedback on the information provided here is essential to the ultimate success of Rich Internet Applications that afford full access to their information and operations. The Accessible Rich Internet Applications Working Group asks in particular:
To comment, file an issue in the W3C ARIA Practices GitHub repository, or if that is not possible, send email to firstname.lastname@example.org (comment archive). Comments are requested by 27 January 2017. In-progress updates to the document may be viewed in the publicly visible editors' draft.
This document was published by the Accessible Rich Internet Applications Working Group as a Working Draft.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. 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.
This document is governed by the 1 September 2015 W3C Process Document.
This section is informative.
WAI-ARIA Authoring Practices is a guide to understanding how to use WAI-ARIA to create an accessible Rich Internet Application. It describes recommended WAI-ARIA usage patterns and provides an introduction to the concepts behind them.
This guide is one part of a suite of resources that support the WAI-ARIA specification. The WAI-ARIA suite fills accessibility gaps identified by the [WAI-ARIA-ROADMAP].
This section demonstrates how to make common rich internet application widgets and patterns accessible by applying WAI-ARIA roles, states, and properties and implementing keyboard support.
Although users of Mac OS X are familiar with using the Command key instead of the Control key, the Command key is typically reserved for desktop applications and OS-level integration. Until device and platform independence can be addressed in WAI-ARIA 2.0, the primary Control modifier key for WAI-ARIA widget interaction is specified as Control on all platforms, including Mac OS X.
The following keyboard conventions are applicable to many of the patterns described in subsequent sections.
This section is work in progress. Development of the next revision is tracked by issue 220.
Unlike native HTML form elements, browsers do not provide keyboard support for graphical user interface (GUI) components that are made accessible with ARIA; authors have to provide the keyboard support in their code. This section describes the principles and methods for making the functionality of a web page that includes ARIA widgets, such as menus and grids, as well as interactive components, such as toolbars and dialogs, operable with a keyboard. Along with the basics of focus management, this section offers guidance toward the objective of providing experiences to people who rely on a keyboard that are as efficient and enjoyable as the experiences available to others.
This section covers:
Work to complete this section is tracked by issue 217.
When operating with a keyboard, two essentials of a good experience are the abilities to easily discern the location of the keyboard focus and to discover where focus landed after a navigation key has been pressed. The following factors affect to what extent a web page affords users these capabilities.
Occasionally, it may appear as if two elements on the page have focus at the same time. For example, in a multi-select list box, when an option is selected it may be greyed. Yet, the focus indicator can still be moved to other options, which may also be selected. Similarly, when a user activates a tab in a tablist, the selected state is set on the tab and its visual appearance changes. However, the user can still navigate, moving the focus indicator elsewhere on the page while the tab retains its selected appearance and state.
Focus and selection are quite different. From the keyboard user's perspective, focus is a pointer, like a mouse pointer; it tracks the path of navigation. There is only one point of focus at any time and all operations take place at the point of focus. On the other hand, selection is an operation that can be performed in some widgets, such as list boxes, trees, and tablists. If a widget supports only single selection, then only one item can be selected and very often the selected state will simply follow the focus when focus is moved inside of the widget. That is, in some widgets, moving focus may also perform the select operation. However, if the widget supports multiple selection, then more than one item can be in a selected state, and keys for moving focus do not perform selection. Some multi-select widgets do support key commands that both move focus and change selection, but those keys are different from the normal navigation keys. Finally, when focus leaves a widget that includes a selected element, the selected state persists.
From the developer's perspective, the difference is simple -- the focused element is the active element (document.activeElement). Selected elements are elements that have
With respect to focus and the selected state, the most important considerations for designers and developers are:
in composite widgets where only one element may be selected, such as a tablist or single-select listbox, moving the focus may also cause the focused element to become the selected element. This is called having selection follow focus. Having selection follow focus is often beneficial to users, but in some circumstances, it is extremely detremental to accessibility.
For example, in a tablist, the selected state is used to indicate which panel is displayed. So, when selection follows focus in a tablist, moving focus from one tab to another automatically changes which panel is displayed. If the content of panels is present in the DOM, then displaying a new panel is nearly instantaneous. A keyboard user who wishes to display the fourth of six tabs can do so with 3 quick presses of the right arrow. And, a screen reader user who perceives the labels on tabs by navigating through them may efficiently read through the complete list without any latency.
However, if displaying a new panel causes a network request and possibly a page refresh, the effect of having selection automatically focus can be devistating to the experience for keyboard and screen reader users. In this case, displaying the fourth tab or reading through the list becomes a tedious and time-consuming task as the user experiences significant latency with each movement of focus. Further, if displaying a new tab refreshes the page, then the user not only has to wait for the new page to load but also return focus to the tab list.
When selection does not follow focus, the user changes which element is selected by pressing the Enter or Space key.
As explained in section 4.1 Fundamental Keyboard Navigation Conventions, all interactive UI components need to be reachable vai the keyboard. This is best achieved by either including them in the tab sequence or by making them accessible from a component that is in the tab sequence, e.g., as part of a composite component. This section addresses building and managing the tab sequence, and subsequent sections cover making focusable elements that are contained within components keyboard accessible.
The HTML tabindex and SVG tabindex attributes can be used to add and remove elements from the tab sequence. The value of tabindex can also influence the order of the tab sequence, although authors are strongly advised not to use tabindex for that purpose.
In HTML, the default tab sequence of a web page includes only links and HTML form elements, except In Mac OS, where it includes only form elements. Mac OS system preferences include a keyboard setting that enables the tab key to move focus to all focusable elements.
The default order of elements in the tab sequence is the order of elements in the DOM. The DOM order also determines screen reader reading order. It is important to keep the keyboard tab sequence and the screen reader reading order aligned, logical, and predictable as described in 4.2 Discernable and Predictable Keyboard Focus. The most robust method of manipulating the order of the tab sequence while also maintaining alignment with the reading order that is currently available in all browsers is rearranging elements in the DOM.
The values of the tabindex attribute have the following effects.
As described in section 4.1 Fundamental Keyboard Navigation Conventions, the tab sequence should include only one focusable element of a composite UI component. Once a composite contains focus, keys other than Tab and Shift + Tab enable the user to move focus among its focusable elements. Authors are free to choose which keys move focus inside of a composite, but they are strongly advised to use the same key bindings as similar components in common GUI operating systems as demonstrated in 2. Design Patterns and Widgets.
The convention for where focus lands in a composite when it recieves focus as a result of a Tab key event depends on the type of composite. It is typically one of the following.
The following sections explain two strategies for managing focus inside composite elements: creating a roving tabindex and using the aria-activedescendant property.
When using roving tabindex to manage focus in a composite UI component, the element that is to be included in the tab sequence has tabindex of "0" and all other focusable elements contained in the composite have tabindex of "-1". The algorithm for the roving tabindex strategy is as follows.
tabindex="0"on the element that will initially be included in the tab sequence and set
tabindex="-1"on all other focusable elements it contains.
tabindex="-1"on the element that has
tabindex="0"on the element that will become focused as a result of the key event.
element.focus(), on the element that has
tabindex="0"when the composite loses focus. If it does not, set
tabindex="0"on the target element and set
tabindex="-1"on the element that previously had
One benefit of using roving tabindex rather than aria-activedescendant to manage focus is that the user agent will scroll the newly focused element into view.
If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. Instead, only the container element needs to be included in the tab sequence. When the container has DOM focus, the value of aria-activedescendant on the container tells assistive technologies which element is active within the widget. Assistive technologies will consider the element referred to as active to be the focused element even though DOM focus is on the element that has the aria-activedescendant property. And, when the value of aria-activedescendant is changed, assistive technologies will receive focus change events equivalent to those received when DOM focus actually moves.
The steps for using the aria-activedescendant method of managing focus are as follows.
aria-activedescendant="IDREF"where IDREF is the ID of the element within the container that should be identified as active when the widget receives focus. The referenced element needs to meet the DOM relationship requirements described below.
The specification for aria-activedescendant places important restrictions on the DOM relationship between the focused element that has the aria-activedescendant attribute and the element referenced as active by the value of the attribute. One of the following three conditions must be met.
Work to draft content for this section is tracked by issue 218.
By default, disabled HTML input elements are removed from the tab sequence. In most contexts, the normal expectation is that disabled interactive elements are not focusable. However, there are some contexts where it is common for disabled elements to be focusable, especially inside of composite widgets. For example, as demonstrated in the 2.14 Menu or Menu bar pattern, disabled items are focusable when navigating through a menu with the arrow keys.
Removing focusability from disabled elements can offer users both advantages and disadvantages. Allowing keyboard users to skip disabled elements usually reduces the number of key presses required to complete a task. However, preventing focus from moving to disabled elements can hide their presence from screen reader users who "see" by moving the focus.
Authors are encouraged to adopt a consistent set of conventions for the focusability of disabled elements. The examples in this guide adopt the following conventions, which both reflect common practice and attempt to balance competing concerns.
One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in 4.8 Keyboard Shortcuts.
When effectively designed, keyboard shortcuts that focus an element, activate a widget, or both can dramatically enhance usability of frequently used features of a page or site. This section addresses some of the keyboard shortcut design and implementation factors that most impact their effectiveness, including:
This section explains the following factors when determining which elements and features to assign keyboard shortcuts and what behavior to give each shortcut:
Before assigning keyboard shortcuts, it is essential to ensure the features and functions to which shortcuts may be assigned are keyboard accessible without a keyboard shortcut. In other words, all elements that could be targets for keyboard shortcuts need to be focusable via the keyboard using the methods described in:
Do not use keyboard shortcuts as a substitute for access via navigation. This is essential to full keyboard access because:
The following conventions may help identify the most advantageous behavior for a keyboard shortcut.
Work to draft content for this section is tracked in issue 219.
The first goal when designing a keyboard interface is simple, efficient, and and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient , attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.
Consider the following when deciding where to assign keyboard shortcuts:
When choosing the keys to assign to a shortcut, there are many factors to consider.
Methods for designing a key shortcut scheme that supports learning and memory is beyond the scope of this guide. Unless the key shortcut scheme is extensive, it is likely sufficient to mimic concepts that are familiar from common desktop software, such as browsers. Similarly, while localization is important, describing how to address it is left to other resources that specialize in that topic.
The remainder of this section provides guidance balancing requirements and concerns related to key assignment conflicts. It is typically ideal if key assignments do not conflict with keys that are assigned to functions in the user's operating system, browser, or assistive technology. Conflicts can block efficient access to functions that are essential to the user, and a perfect storm of conflicts can trap a user. At the same time, there are some circumstances where intentional conflicts are useful. And, given the vast array of operating system, browser, and assistive technology keys, it is almost impossible to be certain conflicts do not exist. So it is also important to employ strategies that mitigate the impact of conflicts whether they are intentional or unknown.
In the following sections, meta key refers to the Windows key on Windows-compatible keyboards and the Command key on MacOS-compatible keyboards.
It is essential to avoid conflicts with keys that perform system level functions, such as appplication and window management and display and sound control. In general, this can be achieved by refraining from the following types of assignments.
In addition, there are some important application level features that most applications, including browsers, generally support. These include:
Even though assistive technologies have collectively taken thousands of key assignments, avoiding conflicts is relatively easy. This is because assistive technologies have had to develop key assignment schemes that avoid conflicts with both operating systems and applications. They do this by hijacking specific keys as modifiers that uniquely define their key commands. For example, many assistive technologies use the Caps Lock key as a modifier.
Deflect assistive technology key conflicts by steering clear of the following types of assignments.
While there is considerable similarity among browser keyboard schemes, the patterns within the schemes are less homogenious. Consequently, it is more difficult to avoid conflicts with browser key assignments. While the impact of conflicts is sometimes mitigated by the availability of two paths to nearly every function -- keyboard accessible menus and keyboard shortcuts, avoiding conflicts with shortcuts to heavily used functions is nonetheless important. Pay special attention to avoiding conflicts with shortcuts to:
While avoiding key conflicts is usually desirable, there are circumstances where intentionally conflicting with a browser function is acceptable or even desirable. This can occur when the following combination of conditions arises:
For example, consider a save function that is available when the focus is in an editor. Most browsers use ... to be continued ...
Work to complete this section is tracked in issue 167.
Drafting content for this section is issue 65.
[placeholder]. This section will cover colcount, rowcount, colindex, rowindex, colspan, rowspan, and sort. It will explain when they are useful and how to use them. It is referenced by the grid and table design patterns. This section will refer readers to the grid and table design patterns for the basics of grid and table.
Please provide feedback on this section in issue 176.
While ARIA is primarily used to express semantics, there are some situations where hiding an element’s semantics from assistive technologies is helpful. This is done with the
presentation role, which declares that an element is being used only for presentation and therefore does not have any accessibility semantics. The ARIA 1.1 specification also includes role
none , which serves as a synonym for
For example, consider a tabs widget built using an HTML
<ul role="tablist"> <li role="presentation"> <a role="tab" href="#">Tab 1</a> </li> <li role="presentation"> <a role="tab" href="#">Tab 2</a> </li> <li role="presentation"> <a role="tab" href="#">Tab 3</a> </li> </ul>
Because the list is declared to be a tablist, the list items are not in a list context. It could confuse users if an assistive technology were to render those list items. Applying role
presentation to the
li elements tells browsers to leave those elements out of their accessibility tree. Assistive technologies will thus be unaware of the list item elements and see the tab elements as immediate children of the tablist.
Three common uses of role
role="presentation" is specified on an element, if a
condition that requires a browser to ignore the
presentation role does not exist, it has the following three effects.
display: noneor has
presentationis applied to a
olelement, each child
lielement inherrits the
presentationrole because ARIA requires the
listitemelements to have the parent
listelement. So, the
lielements are not exposed to assistive technologies, but elements contained inside of those
lielements, including nested lists, are visible to assistive technologies.
presentationis applied to a
tableelement, The descendant
tdelements inherit role
presentationand are thus not exposed to assistive technologies. But, elements inside of the
tdelements, including nested tables, are exposed to assistive technologies.
presentationto be Ignored
role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:
<ul role="presentation"> <li>Date of birth:</li> <li>January 1, 3456</li> </ul>
when parsed by a browser, is equivalent to the following from the perspective of a screen reader or other assistive technology that relies on the browser's accessibility tree:
<div>Date of birth:</div> <div>January 1, 3456</div>
presentation role examples page
includes several more examples that illustrate the three effects of the
presentation role in a variety of scenarios and provides more detailed explanations of the rationale behind them.
Please provide feedback on this section in issue 178.
There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. For example, accessibility APIs do not have a way of representing semantic elements contained in a button. To deal with this limitation, WAI-ARIA requires browsers to automatically apply role
presentation to all descendant elements of any element with a role that cannot support semantic children.
The roles that require all children to be presentational are:
For instance, consider the following tab element, which contains a heading.
<li role="tab"><h3>Title of My Tab</h3></li>
Because WAI-ARIA requires descendants of tab to be presentational, the following code is equivalent.
<li role="tab"><h3 role="presentation">Title of My Tab</h3></li>
And, from the perspective of anyone using a technology that relies on an accessibility API, such as a screen reader, the heading does not exist since the previous code is equivalent to the following.
<li role="tab">Title of My Tab</li>
section about role
for a detailed explanation of what it does.
Drafting content for this section is issue 193.
Placeholder for a section covering this topic that is yet to be written.
[Placeholder section that will be resolved by issue #84.]
This section is non-normative.
The following people contributed to the development of this document.
This publication has been funded in part with U.S. Federal funds from the Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR), initially under contract number ED-OSE-10-C-0067 and currently under contract number HHSP23301500054C. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.