Introduction
This section is informative.
The WAI-ARIA Authoring Practices Guide is intended to provide an understanding of 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]].
As explained in Background on WAI-ARIA, languages used to create rich and dynamic web sites, e.g., HTML, Javascript, CSS, and SVG, do not natively include all the features required to make sites usable by people who use assistive technologies (AT) or who rely on keyboard navigation.
The W3C Web Accessibility Initiative's (WAI) Accessible Rich Internet Applications working group (ARIA WG) is addressing these deficiencies through several W3C standards efforts, with a focus on the WAI-ARIA specifications.
For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview.
With the understanding many prefer to learn from examples, the guide begins with a section that demonstrates how to make common widgets accessible with descriptions of expected behaviors supported by working code.
Where it is helpful to do so, the examples refer to detailed explanations of supporting concepts in subsequent sections.
The sections that follow the examples first provide background that helps build understanding of how WAI-ARIA works and how it fits into the larger web technology picture.
Next, the guide covers general steps for building an accessible widget using WAI-ARIA, JavaScript, and CSS, including detailed guidance on how to make rich internet applications keyboard accessible.
The scope then widens to include the full application, addressing the page layout and structural semantics critical to enabling a usable experience with assistive technologies on pages containing both rich applications and rich documents.
It includes guidance on dynamic document management, use of WAI-ARIA Form properties, and the creation of WAI-ARIA-enabled alerts and dialogs.
Design Patterns and Widgets
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.
Grids : Interactive Tabular Data and Layout Containers
A grid widget is a container that enables users to navigate the information or interactive elements it contains using directional navigation keys, such as arrow keys, Home , and End.
As a generic container widget that offers flexible keyboard navigation, it can serve a wide variety of needs.
It can be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.
While ARIA properties and assistive technologies use row and column nomenclature when describing and presenting the logical structure of elements with the grid role, using the grid role on an element does not necessarily imply that its visual presentation is tabular.
When presenting content that is tabular, consider the following factors when choosing between implementing this grid patern or the table pattern.
-
A
grid is a composite widget so it:
- Always contains multiple focusable elements.
- Has only one focusable element in the page tab sequence.
- Requires the author to provide code that manages focus movement inside it.
- All focusable elements contained in a table are included in the page tab sequence.
Uses of the grid pattern broadly fall into two categories: presenting tabular information (data grids) and grouping other widgets (layout grids).
Even though both data grids and layout grids employ the same ARIA roles, states, and properties, differences in their content and purpose surface factors that are important to consider in keyboard interaction design.
To address these factors, the following two sections describe separate keyboard interaction patterns for data and layout grids.
Data Grids For Presenting Tabular Information
A grid can be used to present tabular information that has column titles, row titles, or both.
The grid pattern is particularly useful if the tabular information is editable or interactive.
For example, when data elements are links to more information, rather than presenting them in a static table and including the links in the tab sequence, implementing the grid pattern provides users with intuitive and efficient keyboard navigation of the grid contents as well as a shorter tab sequence for the page.
A grid may also offer functions, such as cell content editing, selection, cut, copy, and paste.
In a grid that presents tabular data, every cell contains a focusable element or is itself focusable, regardless of whether the cell content is editable or interactive.
There is one exception: if column or row header cells do not provide functions, such as sort or filter, they do not need to be focusable. One reason this is important is that screen readers need to be in their application reading mode, rather than their document reading mode, while the user is interacting with the grid.
While in application reading mode, a screen reader user can only discover focusable elements and content that labels focusable elements.
So, a screen reader user may unknowningly overlook elements contained in a grid that are either not focusable or not used to label a column or row.
A more detailed description of this topic with examples is available in the section describing screen reader document and application reading modes.
Keyboard Interaction For Data Grids
The following keys provide grid navigation by moving focus among cells of the grid.
These key commands are available by default after an element in the grid receives focus.
-
Right Arrow: Moves focus one cell to the right.
If focus is on the right-most cell in the row, focus does not move.
- Left Arrow: Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move.
- Down Arrow: Moves focus one cell down. If focus is on the bottom cell in the column, focus does not move.
- Up Arrow: Moves focus one cell Up. If focus is on the top cell in the column, focus does not move.
- Page Down: Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move.
- Page Up: Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move.
- Home: moves focus to the first cell in the row that contains focus.
- End: moves focus to the last cell in the row that contains focus.
- Control + Home: moves focus to the first cell in the first row.
- Control + End: moves focus to the last cell in the last row.
-
When the above grid navigation keys move focus, whether the focus is set on an element inside the cell or the grid cell depends on cell content.
See Whether to Focus on a Cell or an Element Inside It.
-
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell.
If this functionality is needed, see Editing and Navigating Inside a Cell.
- If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as control + End, may move focus to the last row in the DOM rather than the last available row in the back-end data.
If a grid supports selection of cells, rows, or columns, the following keys are commonly used for these functions.
- Control + Space: selects the column that contains the focus.
- Shift + Space: Selects the row that contains the focus. If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.
- Control + A: Selects all cells.
- Shift + Right Arrow: Extends selection one cell to the right.
- Shift + Left Arrow: Extends selection one cell to the left.
- Shift + Down Arrow: Extends selection one cell down.
- Shift + Up Arrow: Extends selection one cell Up.
See Global Recommendations for cut, copy and paste key assignments.
Layout Grids for Grouping Widgets
The grid pattern can be used to group a set of interactive elements, such as links, buttons, or checkboxes.
Since only one element in the entire grid is included in the tab sequence, grouping with a grid can dramatically reduce the number of tab stops on a page.
This is especially valuable if scrolling through a list of elements dynamically loads more of those elements from a large data set, such as in a continuous list of suggested products on a shopping site.
If elements in a list like this were in the tab sequence, keyboard users are effectively trapped in the list.
If any elements in the group also have associated elements that appear on hover, the grid pattern is also useful for providing keyboard access to those contextual elements of the user interface.
Unlike grids used to present data, A grid used for layout does not necessarily have header cells for labeling rows or columns and might contain only a single row or a single column.
Even if it has multiple rows and columns, it may present a single, logically homogenous set of elements.
For example, a list of recipients for a message may be a grid where each cell contains a link that represents a recipient.
The grid may initially have a single row but then wrap into multiple rows as recipients are added.
In such circumstances, grid navigation keys may also wrap so the user can read the list from beginning to end by pressing either Right Arrow or Down Arrow.
While This type of focus movement wrapping can be very helpful in a layout grid, it would be disorienting if used in a data grid, especially for users of assistive technologies.
Because arrow keys are used to move focus inside of a grid, a grid is both easier to build and use if the components it contains do not require the arrow keys to operate.
If a cell contains an element like a listbox, then an extra key command to focus and activate the listbox is needed as well as a command for restoring the grid navigation functionality.
Aproaches to supporting this need are described in the section on Editing and Navigating Inside a Cell.
Keyboard Interaction For Layout Grids
The following keys provide grid navigation by moving focus among cells of the grid.
These key commands are available by default after an element in the grid receives focus.
-
Right Arrow: Moves focus one cell to the right.
Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row.
If focus is on the last cell in the grid, focus does not move.
-
Left Arrow: Moves focus one cell to the left.
Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row.
If focus is on the first cell in the grid, focus does not move.
-
Down Arrow: Moves focus one cell down.
Optionally, if focus is on the bottom cell in the column, focus may move to the top cell in the following column.
If focus is on the last cell in the grid, focus does not move.
-
Up Arrow: Moves focus one cell up.
Optionally, if focus is on the top cell in the column, focus may move to the bottom cell in the previous column.
If focus is on the first cell in the grid, focus does not move.
-
Page Down (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows.
If focus is in the last row of the grid, focus does not move.
-
Page Up (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows.
If focus is in the first row of the grid, focus does not move.
-
Home: moves focus to the first cell in the row that contains focus.
Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the first cell in the grid.
-
End: moves focus to the last cell in the row that contains focus.
Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the last cell in the grid.
- Control + Home (optional): moves focus to the first cell in the first row.
- Control + End (Optional): moves focus to the last cell in the last row.
-
When the above grid navigation keys move focus, whether the focus is sett on an element inside the cell or the grid cell depends on cell content.
See Whether to Focus on a Cell or an Element Inside It.
-
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell.
If this functionality is needed, see Editing and Navigating Inside a Cell.
- If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as control + End, may move focus to the last row in the DOM rather than the last available row in the back-end data.
It would be unusual for a layout grid to provide functions that require cell selection. If it did, though, the following keys are commonly used for these functions.
- Control + Space: selects the column that contains the focus.
-
Shift + Space: Selects the row that contains the focus.
If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.
- Control + A: Selects all cells.
- Shift + Right Arrow: Extends selection one cell to the right.
- Shift + Left Arrow: Extends selection one cell to the left.
- Shift + Down Arrow: Extends selection one cell down.
- Shift + Up Arrow: Extends selection one cell Up.
See Global Recommendations for cut, copy and paste key assignments.
Keyboard Interaction - Setting Focus and Navigating Inside Cells
This section describes two important aspects of keyboard interaction design shared by both data and layout grid patterns:
- Choosing whether a cell or an element inside a cell receives focus in response to grid navigation key events.
- Enabling grid navigation keys to be used to interact with elements inside of a cell.
Whether to Focus on a Cell Or an Element Inside IT
For assistive technology users, the quality of experience when navigating a grid heavily depends on both what a cell contains and on where keyboard focus is set.
For example, if a cell contains a button and a grid navigation key places focus on the cell instead of the button, screen readers announce the button label but do not tell users a button is present.
There are two optimal cell design and focus behavior combinations:
-
A cell contains one widget whose operation does not require arrow keys and grid navigation keys set focus on that widget.
Examples of such widgets include link, button, menubutton, toggle button, radio button (not radio group), switch, and checkbox.
- A cell contains text or a single graphic and grid navigation keys set focus on the cell.
While any combination of widgets, text, and graphics may be included in a single cell, grids that do not follow one of these two cell design and focus movement patterns add complexity for authors or users or both.
The reference implementations included in the example section below demonstrate some strategies for making other cell designs as accessible as possible, but the most widely accessible experiences are likely to come by applying the above two patterns.
Editing and Navigating Inside a Cell
While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to perform actions like operate a combobox or move an editing caret inside of a cell. The user may need keys that are used for grid navigation to operate
elements inside a cell if a cell contains:
- Editable content.
- Multiple widgets.
- A widget that utilizes arrow keys in its interaction model, such as a radio group or slider.
Following are common keyboard conventions for disabling and restoring grid navigation functions.
-
Enter: Disables grid navigation and:
- If the cell contains editable content, places focus in an input field, such as a textbox. If the input is a single-line text field, a subsequent press of Enter may either restore grid navigation
functions or move focus to an input field in a neighboring cell.
- If the cell contains one or more widgets, places focus on the first widget.
-
F2:
- If the cell contains editable content, places focus in an input field, such as a textbox. A subsequent press of F2 restores grid navigation functions.
- If the cell contains one or more widgets, places focus on the first widget. A subsequent press of F2 restores grid navigation functions.
- Alphanumeric keys: If the cell contains editable content, places focus in an input field, such as a textbox.
When grid navigation is disabled, conventional changes to navigation behaviors include:
- Escape: restores grid navigation. If content was being edited, it may also undo edits.
-
Right Arrow or Down Arrow: If the cell contains multiple widgets, moves focus to the next widget inside the cell, optionally wrapping to the first widget if focus is on the last widget.
Otherwise, passes the key event to the focused widget.
-
Left Arrow or Up Arrow: If the cell contains multiple widgets, moves focus to the previous widget inside the cell, optionally wrapping to the first widget if focus is on the last widget.
Otherwise, passes the key event to the focused widget.
-
Tab: moves focus to the next widget in the grid.
Optionally, the focus movement may wrap inside a single cell or within the grid itself.
-
Shift + Tab: moves focus to the previous widget in the grid.
Optionally, the focus movement may wrap inside a single cell or within the grid itself.
WAI-ARIA Roles, States, and Properties
- The grid container has role grid.
- Each row container has role row and is either a DOM descendant of or owned by the
grid element or an element with role rowgroup.
- Each cell is either a DOM descendant of or owned by a
row element and has one of the following roles:
- columnheader if the cell contains a title or header information for the column.
- rowheader if the cell contains title or header information for the row.
- gridcell if the cell does not contain column or row header information.
-
If there is an element in the user interface that serves as a label for the grid, aria-labelledby is set on the grid element with a value that refers to the labeling element.
Otherwise, a label is specified for the grid element using aria-label.
- If the grid has a caption or description, aria-describedby is set on the grid element with a value refering to the element containing the description.
- If the grid provides sort functions, aria-sort is set to an appropriate value on the header cell element for the sorted column or row as described in the section on grid and table properties.
- If the grid supports selection, when a cell or row is selected, the selected element has aria-selected set
true.
-
If the grid provides content editing functionality and contains cells that may have edit capabilities disabled in certain conditions, aria-readonly may be set
true on cells where editing is disabled.
If edit functions are disabled for all cells, aria-readonly may be set true on the grid element.
Grids that do not provide editing functions do not include the aria-readonly attribute on any of their elements.
-
If there are conditions where some rows or columns are hidden or not present in the DOM, e.g., data is dynamically loaded when scrolling or the grid provides functions for hiding rows or columns, the following properties are applied as described in the section on grid and table properties.
- If the grid includes cells that span multiple rows or multiple columns, and if the
grid role is NOT applied to an HTML table element, then aria-rowspan or aria-colspan is applied as described in grid and table properties.
-
If the element with the
grid role is an HTML table element, then it is not necessary to use ARIA roles for rows and cells because the HTML elements have implied ARIA semantics.
For example, an HTML <TR> has an implied ARIA role of row.
A grid built from an HTML table that includes cells that span multiple rows or columns must use HTML rowspan and colspan and must not use aria-rowspan or aria-colspan.
-
If rows or cells are included in a grid via aria-owns, they will be presented to assistive technologies after the DOM descendants of the
grid element unless the DOM descendants are also included in the aria-owns attribute.
See using aria-owns for a detailed explaination.
Examples
- Data Grids: Three example implementations of grid that include features relevant to presenting tabular information, such as content editing, sort, and column hiding.
- Layout Grids: Three example implementations of grids that are used to lay out widgets, including a collection of navigation links, a message recipients list, and a set of search results.
Developing a Keyboard Interface
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.
It covers:
- Understanding fundamental principles of focus movement conventions used in ARIA design patterns.
- Maintaining visible focus, predictable focus movement, and distinguishing between keyboard focus and the selected state.
- Managing movement of keyboard focus between components, e.g., how the focus moves when the Tab and Shift+Tab keys are pressed.
- Managing movement of keyboard focus inside components that contain multiple focusable elements, e.g., two different methods for programatically exposing focus inside widgets like radio groups, menus, listboxes, trees, and grids.
- Managing focus for modal and non-modal dialogs.
- Determining when to make disabled interactive elements focusable.
- Assigning and revealing keyboard shortcuts, including guidance on how to avoid problematic conflicts with keyboard commands of assistive technologies, browsers, and operating systems.
- Addressing macro navigation concerns, i.e., methods for enabling efficient keyboard access to different sections of a page or site.
Fundamental Keyboard Navigation Conventions
ARIA roles, states, and properties model accessibility behaviors and features shared among GUI components of popular desktop GUIs, including Microsoft Windows, Mac OS X, and GNOME.
Similarly, ARIA design patterns borrow user expectations and keyboard conventions from those platforms, consistently incorporating common conventions with the aim of facilitating easy learning and efficient operation of keyboard interfaces across the web.
For a web page to be accessible, all interactive elements must be operable via the keyboard.
In addition, consistent application of the common GUI keyboard interface conventions described in the ARIA design patterns is important, especially for assistive technology users.
Consider, for example, a screen reader user operating a tree.
Just as familiar visual styling helps users discover how to expand a tree branch with a mouse, ARIA attributes give the tree the sound and feel of a tree in a desktop application.
So, screen reader users will commonly expect that pressing the right arrow key will expand a collapsed node.
Because the screen reader knows the element is a tree, it also has the ability to instruct a novice user how to operate it.
Similarly, voice recognition software can implement commands for expanding and collapsing branches because it recognizes the element as a tree and can execute appropriate keyboard commands.
All this is only possible if the tree implements the GUI keyboard conventions as described in the ARIA tree pattern.
A primary keyboard navigation convention common across all platforms is that the tab and shift+tab keys move focus from one UI component to another while other keys, primarily the arrow keys, move focus inside of components that include multiple focusable elements.
The path that the focus follows when pressing the tab key is known as the tab sequence or tab ring.
Common examples of UI components that contain multiple focusable elements are radio groups, tablists, menus, and grids.
A radio group, for example, contains multiple radio buttons, each of which is focusable.
However, only one of the radio buttons is included in the tab sequence.
After pressing the Tab key moves focus to a radio button in the group, pressing arrow keys moves focus among the radio buttons in the group, and pressing the Tab key moves focus out of the radio group to the next element in the tab sequence.
The ARIA specification refers to a discrete UI component that contains multiple
focusable elements as a composite
widget. The process of controlling focus movement inside a composite is called
managing focus. Following are some ARIA design patterns with example implementations
that demonstrate focus management:
Discernable and Predictable Keyboard Focus
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.
- Visibility of the focus indicator: Users need to be able to easily distinguish the keyboard focus indicator from other features of the visual design. Just as a mouse user may move the mouse to help find the mouse pointer, a keyboard user may press a navigation key to watch for movement. If visual changes in response to focus movement are subtle, many users will lose track of focus and be unable to operate. Authors are advised to rely on the default focus indicators provided by browsers. If overriding the default, consider:
- something about ... Colors and gradients can disappear in high contrast modes.
- Users need to be able to easily distinguish between focus and selection as described in , especially when a component that contains selected elements does not contain the focus.
- ... other considerations to be added ...
-
Persistence of focus: It is essential that there is always a component within the user interface that is active (document.activeElement is not null or is not the body element) and that the active element has a visual focus indicator.
Authors need to manage events that effect the currently active element so focus remains visible and moves logically.
For example, if the user closes a dialog or performs a destructive operation like deleting an item from a list, the active element may be hidden or removed from the DOM.
If such events are not managed to set focus on the button that triggered the dialog or on the list item following the deleted item, browsers move focus to the body element, affectively causing a loss of focus within the user interface.
-
Predictability of movement: Usability of a keyboard interface is heavily influenced by how readily users can guess where focus will land after a navigation key is pressed.
Some possible approaches to optimizing predictability include:
-
Move focus in a pattern that matches the reading order of the page's language. In left to right languages, for example, create a tab sequence that moves focus left to right and then top to bottom.
-
Incorporate all elements of a section of the page in the tab sequence before moving focus to another section. For instance, in a page
with multiple columns that has content in a left side bar, center region, and right side bar, build a tab sequence that covers all elements in the left sidebar before focus moves to the first focusable element in the center column.
-
When the distance between two consecutive elements in the tab sequence is significant, avoid movement that would be perceived as backward.
For example, on a page with a left to right language, a jump from the last element in the bottom right of the main content to the top element in a left-hand sidebar is likely to be less predictable and more difficult to follow, especially for users with a narrow field of view.
-
Follow consistent patterns across a site.
The keyboard experience is more predictable when similar pages have similar focus movement patterns.
- Do not set initial focus when the page loads except in cases where:
- The page offers a single, primary function that nearly all users employ immediately after page load.
- Any given user is likely to use the page often.
Focus VS Selection and the Perception of Dual Focus
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 aria-selected="true".
With respect to focus and the selected state, the most important considerations for designers and developers are:
- The visual focus indicator must always be visible.
- The selected state must be visually distinct from the the focus indicator.
Keyboard Navigation Between Components (The Tab Sequence)
As explained in section , 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 .
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.
- tabindex is not present or does not have a valid value
-
The element has its default focus behavior.
In HTML, only form controls and anchors with an HREF attribute are included in the tab sequence.
- tabindex="0"
- The element is included in the tab sequence based on its position in the DOM.
- tabindex="-1"
- The element is not included in the tab sequence but is focusable with element.focus().
- tabindex="X" where X is an integer in the range 1 <= X <= 32767
-
Authors are strongly advised NOT to use these values.
The element is placed in the tab sequence based on the value of tabindex.
Elements with a tabindex value of 0 and elements that are focusable by default will be in the sequence after elements with a tabindex value of 1 or greater.
Keyboard Navigation Inside Components
As described in section , 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 .
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 element that had focus the last time the composite contained focus.
Or, if the composite has not yet contained the focus, the first element.
Widgets that usually employ this pattern include grid and tree grid.
-
The selected element. Or, if there is no selected element, the first element.
Widgets where this pattern is commonly implemented include radio groups, tabs, list boxes, and trees.
Note: For radio groups, this pattern is referring to the checked radio button; the selected state is not supported for radio buttons.
-
The first element.
Components that typically follow this pattern include menubars and toolbars.
The following sections explain two strategies for managing focus inside composite elements: creating a roving tabindex and using the aria-activedescendant property.
Managing Focus Within Components Using a Roving tabindex
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.
- When the component container is loaded or created, set
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.
-
When the component contains focus and the user presses a navigation key that moves focus within the component, such as an arrow key:
- set
tabindex="-1" on the element that has tabindex="0".
- Set
tabindex="0" on the element that will become focused as a result of the key event.
- Set focus,
element.focus(), on the element that has tabindex="0".
-
If the design calls for a specific element to be focused the next time the user moves focus into the composite with Tab or Shift+Tab, check if that target element 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 tabindex="0".
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.
Managing Focus in Composites Using aria-activedescendant
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.
-
When the container element that has a role that supports aria-activedescendant is loaded or created, ensure that:
- The container element is included in the tab sequence as described in or it is otherwise focusable as described in .
-
It has
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.
-
When the container element receives DOM focus, draw a visual focus indicator on the active element and ensure the active element is scrolled into view.
See section Managing Focus with Scroll below for more information.
-
When the composite widget contains focus and the user presses a navigation key that moves focus within the widget, such as an arrow key:
- Change the value of aria-activedescendant on the container to refer to the element that should be reported to assistive technologies as active.
- Move the visual focus indicator and, if necessary, scrolled the active element into view.
-
If the design calls for a specific element to be focused the next time a user moves focus into the composite with Tab or Shift+Tab, check if aria-activedescendant is referring to that target element when the container loses focus.
If it is not, set aria-activedescendant to refer to the target element.
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.
- The element referenced as active is a DOM descendant of the focused referencing element.
- The focused referencing element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
-
The focused referencing element has role of textbox and has aria-controls property referring to an element with a role that supports aria-activedescendant and either:
- The element referenced as active is a descendant of the controlled element.
- The controlled element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
Nested Composite Components - Composites and Toolbars That Contain Composites
to be written
Managing Focus in Dialogs
MCK: unedited content pulled together from the old guide that needs a significant re-write.
Please ignore this section for now.
WAI-ARIA provides for two dialog roles - dialog and alertdialog. When authors simulate dialogs on a web page they often limit their interaction considerations to the mouse.
Unlike Graphical User Interface dialog boxes on a desktop computer, a user during keyboard navigation could accidentally navigate outside the dialog box and become disoriented.
This can happen when the user is tabbing in the dialog.
A modal dialog prevents the user from setting focus outside of the dialog until the dialog is closed.
Mouse clicks outside of the dialog must be ignored and the user must not be able to tab into or out of the dialog itself.
All WAI-ARIA enabled dialog boxes should be modal.
This section describes how.
Mouse clicks outside of the dialog can be prevented by creating a CSS positioned element that is the size of the viewport to append as a child of the body element.
Set the CSS z-index of this element so that it is above all other elements on the page except for the dialog element.
Set the tabindex of the underlay element to tabindex="-1" to prevent it from receiving focus via a keyboard event or mouse click.
You may lower the opacity of the underlay element in order to emphasize that the dialog itself is modal and has focus.
Depending upon the action to be performed by the dialog, the object with focus before the dialog box is opened should be saved.
This will allow restoring focus to this element when the dialog box is closed.
When the dialog box is opened, focus should be set to the first tab focusable element within the dialog.
If there is no tab focusable element within the dialog box contents, set the focus to the item that is used to cancel or close the dialog.
There must be some element within the dialog which can accept focus in order for the screen reader to speak the dialog title and information when it is opened.
In order to prevent keyboard focus from leaving the dialog, determine the first and last tab focusable elements in the dialog and trap keyboard events within the document.
Search the contents of the dialog container to find the first and last tab focusable elements.
This can be implemented by walking the DOM tree of the dialog container to find all visible and enabled anchor elements, input elements, and all elements that have a tabindex value greater than or equal to 0.
Remember that elements with a tabindex > 0 will appear in the tab order before all other focusable elements in ascending order by tabindex.
Store the first and last tab focusable items within variables in the scope of the dialog box code.
Before the dialog is shown, create and display the dialog underlay.
Connect an onkeypress event handler to the DOM document.documentElement.
This will catch all keystrokes on the document and allow trapping keyboard focus within the dialog.
Size and position the dialog box in the viewport above the underlay, make it visible and set focus to the first tab focusable item in the dialog box.
The onkeypress handler will catch all key presses within the document.
This onkeypress event handler should be within the scope of the dialog box code so that it has access to the first and last tab focusable elements within the dialog.
In the onkeypress handler determine the target of the keypress event.
In addition, determine if there is only a single focusable item within the dialog box.
In this instance the first tab navigable object will equal the last tab navigable object.
If key presses within the dialog box may create, destroy, enable, disable, or change the visibility of tab focusable elements, then determine the first and last tab-focusable items each time a keypress is received.
Based on the event target and the key pressed take the following actions:
-
If the keypress is a Shift + Tab key and the target == the first tab navigable object, then set focus to the last tab-navigable object and stop the key press event. If there is only a single tab focusable item, then focus does not have to be set, but the key press event must be stopped.
-
If the keypress is a Tab key and the target == the last tab navigable object, then set focus to the first tab-navigable object and stop the keypress event. If there is only a single tab-focusable item, then focus does not have to be set but the keypress event must must be stopped.
-
If the keypress is an Escape key and the target node is the container node for the dialog box, then close the dialog box and hide or destroy the dialog underlay.
Determine if the target node of the keypress is within the dialog box container. This can be done using a while loop to walk the parent chain of the target node until the container node of the dialog box is found. Other than those outlined above, all key presses from within the dialog box should be allowed to execute so that the user can interact with the controls in the dialog box.
If the target node is not within the dialog box, the keypress is from the documentElement and the keypress event should be stopped unless it is a Tab key press. Allowing a Tab key press from the document element will enable tabbing back into the dialog box if, for some reason, focus on the dialog box is lost. This can happen due to timing issues when the dialog box is first loaded and focus does not properly get set to the first tab-focusable item within the dialog.
The dialog box itself should contain buttons or other mechanisms to cancel the dialog box or execute the dialog box functions and close the dialog box.
Here is a pseudo code onkeypress handler for a modal dialog box. Pseudo code is used to focus on the actions in the handler rather than on the differences in browser event handling. Assume that the event object, evt, has been normalized between browsers and the helper object is a library of functions that handle browser differences. The keys object is a set of key definition variables. Dialog is the dialog box object, which has a function to cancel the dialog.
_onKey: function(/*Normalized Event*/ evt){
// summary:
// Handles the keyboard events for accessibility reasons
if(evt.charOrCode){
var node = evt.target; // get the target node of the keypress event
if (evt.charOrCode === keys.TAB){
// find the first and last tab focusable items in the hierarchy of the dialog container node
// do this every time if the items may be added / removed from the the dialog may change visibility or state
var focusItemsArray = helper.getFocusItems(dialogContainerNode);
dialog.firstFocusItem = focusItemsArray[0];
dialog.lastFocusItem = focusItemsArray[focusItemsArray.length-1];
}
// assumes firstFocusItem and lastFocusItem maintained by dialog object
var singleFocusItem = (dialog.firstFocusItem == dialog.lastFocusItem);
// see if we are shift-tabbing from first focusable item on dialog
if(node == dialog.firstFocusItem && evt.shiftKey && evt.charOrCode === keys.TAB){
if(!singleFocusItem){
dialog.lastFocusItem.focus(); // send focus to last item in dialog
}
helper.stopEvent(evt); //stop the tab keypress event
}
// see if we are tabbing from the last focusable item
else if(node == dialog.lastFocusItem && evt.charOrCode === keys.TAB && !evt.shiftKey){
if (!singleFocusItem){
dialog.firstFocusItem).focus(); // send focus to first item in dialog
}
helper.stopEvent(evt); //stop the tab keypress event
}
else{
// see if the key is for the dialog
while(node){
if(node == dialogContainerNode){ // if this is the container node of the dialog
if(evt.charOrCode == keys.ESCAPE){ // and the escape key was pressed
dialog.cancel(); // cancel the dialog
}else{
return; // just let it go
}
}
node = node.parentNode;
}
// this key is for the document window
if(evt.charOrCode !== keys.TAB){ // allow tabbing into the dialog
helper.stopEvent(evt); //stop the event if not a tab keypress
}
} // end of if evt.charOrCode
} // end of function
Focusability of disabled controls
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 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.
- For elements that are in the tab sequence when enabled, remove them from the tab sequence when disabled.
-
For the following composite widget elements, keep them focusable when disabled:
-
For elements contained in a toolbar, make them focusable if discoverability is a concern. Here are two examples to aid with this judgment.
-
A toolbar with buttons for moving, removing, and adding items in a list includes buttons for "Up", "Down", "Add", and "Remove".
The "Up" button is disabled and its focusability is removed when the first item in the list is selected.
Given the presence of the "Down" button, discoverability of the "Up" button is not a concern.
-
A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard.
It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.
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 .
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:
- Understanding how keyboard shortcuts augment a keyboard interface and whether to make a particular shortcut move focus, perform a function, or both.
- Making key assignments and avoiding assignment conflicts with assistive technologies, browsers, and operating systems.
- Exposing and documenting key assignments.
Designing the Scope and Behavior of Keyboard Shortcuts
This section explains the following factors when determining which elements and features to assign keyboard shortcuts and what behavior to give each shortcut:
- Ensuring discovery through navigation; keyboard shortcuts enhance, not replace, standard keyboard access.
-
Effectively choosing from among the following behaviors:
- Navigation: Moving focus to an element.
- Activation: Performing an operation associated with an element that does not have focus and might not be visible.
- Navigation and activation: Both moving focus to an element and activating it.
- Balancing efficiency and cognitive load: lack of a shortcut can reduce efficiency while too many shortcuts can increase cognitive load and clutter the experience.
Ensure Basic Access Via Navigation
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 primary means of making functions and their shortcuts discoverable is by making the target elements focusable and revealing key assignments on the element itself.
- If people who rely on the keyboard have to read documentation to learn which keys are required to use an interface, the interface may technically meet some accessibility standards but in practice is only accessible to the small subset of them who have the knowledge that such documentation exists, have the extra time available, and the ability to retain the necessary information.
- Not all devices that depend on keyboard interfaces can support keyboard shortcuts.
Choose Appropriate Shortcut Behavior
The following conventions may help identify the most advantageous behavior for a keyboard shortcut.
-
Move focus when the primary objective is to make navigation more efficient, e.g., reduce the number of times the user must press Tab or the arrow keys.
This behavior is commonly expected when assigning a shortcut to a text box, toolbar, or composite, such as a listbox, tree, grid, or menubar.
This behavior is also useful for moving focus to a section of a page, such as the main content or a complementary landmark section.
-
Activate an element without moving focus when the target context of the funtion is the context that contains the focus.
This behavior is most common for command buttons and for functions associated with elements that are not visible, such as a "Save" option that is accessible via a menu.
For example, if the focus is on an option in a listbox and a toolbar contains buttons for moving and removing options, it is most benefitial to keep focus in the listbox when the user presses a key shortcut for one of the buttons in the toolbar.
This behavior can be particularly important for screen reader users because it provides confirmation of the action performed and makes performing multiple commands more efficient.
For instance, when a screen reader user presses the shortcut for the "Up" button, the user will be able to hear the new position of the option in the list since it still has the focus.
Similarly, when the user presses the shortcut for deleting an option, the user can hear the next option in the list and immediately decide whether to press the delete shortcut again.
-
Move focus and activate when the target of the shortcut has a single function and the context of that function is the same as the target.
This behavior is typical when a shortcut is assigned to a button that opens a menu or dialog, to a checkbox, or to a navigation link or button.
Choose Where to Add Shortcuts
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:
- To be written ... stream of consciousness includes frequency of use, repetitive operations, amount of benefit (key presses saved), minimizing the number with placement, e.g., focus on a menubar with first letter nav vs assigning shortcuts to individual menuitems.
Assigning Keyboard Shortcuts
When choosing the keys to assign to a shortcut, there are many factors to consider.
- Making the shortcut easy to learn and remember by using a mnemonic (e.g., "S" for "Save") or following a logical or spacial pattern.
- Localizing the interface, including for differences in which keys are available and how they behave and for language considerations that could impact mnemonics.
- Avoiding and managing conflicts with key assignments used by an assistive technology, the browser, or the operating system.
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.
Operating System Key Conflicts
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.
- Any modifier keys + any of Tab, Enter, Space, or Escape.
- Meta key + any other single key (there are exceptions, but they can be risky as these keys can change across versions of operating systems).
- Alt + a function key.
In addition, there are some important application level features that most applications, including browsers, generally support.
These include:
- Zoom
- Copy/Paste
- ... to be continued ...
Assistive Technology Key Connflicts
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.
- Caps Lock + any other combination of keys.
- Insert + any combination of other keys.
- Scroll Lock + any combination of other keys.
- Mac OS only: Control+Option + any combination of other keys.
Browser Key Connflicts
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:
- Address or location bar
- Notification bar
- Page refresh
- Bookmark and history functions
- Find functions
Mitigating Key Connflict Likelihood and Impact
Intentional Key Conflicts
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:
- A web application has a frequently used function that is similar to a browser function.
- Users will often want to execute the web application function.
- Users will rarely execute the browser function.
- There is an efficient, alternative path to the browser function.
For example, consider a save function that is available when the focus is in an editor. Most browsers use ... to be continued ...
Exposing and Documenting Keyboard Shortcuts
This is where we will talk about how the keyshortcuts property exposes shortcuts to assistive technology, visual exposure via tooltips, and the like.
We will also cover making it easy to find documentation, such as in an accessibility section in help or a keyboard shortcuts option in a help menu.
Implementing keyboard shortcuts
Not sure if we will have this section ... could include some js tips and note about access keys ... accesskey behave differently in different browsers.
Other Keyboard Interface Development Tips
MCK: this section is a collection of keyboard related old content with a yet undecided fate.
Miscelaneous stuff we might or might not keep
-
Use focus and blur events (or event delegation) to monitor changes to the current focus -
focus and blur events can now be used with every element.
Don't assume that all focus changes will come via key and mouse events, because assistive technologies such as screen readers can set the focus to any focusable element, and that needs to be handled elegantly by the JavaScript widget.
Techniques such as "event delegation" (for example, intercepting events on a list rather than on every listitem) can improve performance.
-
Follow keydowns to move focus - A keydown event handler can determine the next object to receive focus and call that element's focus() method.
-
Use onkeydown to trap key events, not onkeypress - Key press events do not fire for all keys and they vary across browsers.
-
Use element.focus() to set focus - Do not use createEvent(), initEvent() and dispatchEvent() to send focus to an element, because these functions do not change the focus. DOM focus events are informational only, generated by the user agent after an element has acquired focus, but not used themselves to set focus.
-
The use of :focus pseudo-class selectors to style the keyboard focus is not supported in many versions of Internet Explorer. Authors should use the :active pseudo-class (which older versions of IE treat like :focus) in conjunction with the :focus pseudo-class. Example: a:focus, a:active { text-decoration: underline; }
If the related CSS pseudo-classes are not appropriate or not supported in all browsers, authors can use JavaScript techniques to indicate an appropriate focus alternative, such as using focus and blur events to toggle a classname on an element.
-
Always draw the focus for tabindex="-1" items and elements that receive focus programmatically when supporting versions of Internet Explorer older than 8 - Choose between changing the background color via something like this.style.backgroundColor = "gray"; or add a dotted border via this.style.border = "1px dotted invert". In the dotted border case, you will need to make sure those elements have an invisible 1px border to start with, so that the element doesn't grow when the border style is applied (borders take up space, and IE doesn't implement CSS outlines).
-
Prevent used key events from performing browser functions - If a key such as an arrow key is used, prevent the browser from using the key to do something (such as scrolling) by using code like the following:
<span tabindex="-1" onkeypress="return handleKeyPress();">
If handleKeyDown() returns false, the event will be consumed, preventing the browser from performing any action based on the keystroke.
In addition to the return value the browser must call the event methods that will prevent the default action, for IE this is setting the event property "returnValue=false", and for other browsers supporting the W3C event model this means calling the "preventDefault" method of the event object.
-
Use key event handlers to enable activation of the element - For every mouse event handler, a keyboard event handler is required.
For example, if you have an onclick="doSomething()" you may also need onkeydown="return event.keyCode != 13 || doSomething();" in order to allow the Enter key to activate that element.
There are user agent-specific considerations for key event handling.