Abstract

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.

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 https://www.w3.org/TR/.

This is an editor's 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 draft includes only a portion of content planned for WAI-ARIA Authoring Practices 1.1. To see plans for the complete guide, 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 public-aria@w3.org (comment archive).

This document was published by the Accessible Rich Internet Applications Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to public-aria@w3.org (subscribe, archives).

Publication as an Editor's 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.

This document is governed by the 1 March 2017 W3C Process Document.

1. Introduction§

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].

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.

2. 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.

Note

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.

2.1 Generally Applicable Keyboard Recommendations §

The following keyboard conventions are applicable to many of the patterns described in subsequent sections.

2.2 Accordion (Sections With Show/Hide Functionality)§

An accordion is a vertically stacked set of elements, such as labels or thumbnails, that allow the user to toggle the display of sections of content. Each labeling element can be expanded or collapsed to reveal or hide its associated content. Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page.

Terms for understanding accordions include:

Accordion Header:
Label for or thumbnail representing a section of content that also serves as a control for showing, and in some implementations, hiding the section of content.
Accordion Panel:
Section of content associated with an accordion header.

In some accordions, there are additional elements that are always visible adjacent to the accordion header. For instance, a menubutton may accompany each accordion header to provide access to actions that apply to that section. And, in some cases, a snippet of the hidden content may also be visually persistent.

Example§

Accordion Example: demonstrates a form divided into three sections using an accordion to show one section at a time.

Keyboard Interaction§

  • Enter or Space:
    • When focus is on the accordion header for a collapsed panel, expands the associated panel. If the implementation allows only one panel to be expanded, and if another panel is expanded, collapses that panel.
    • When focus is on the accordion header for an expanded panel, collapses the panel if the implementation supports collapsing. Some implementations require one panel to be expanded at all times and allow only one panel to be expanded; so, they do not support a collapse function.
  • Down Arrow (Optional): If focus is on an accordion header, moves focus to the next accordion header. If focus is on the last accordion header, either does nothing or moves focus to the first accordion header.
  • Up Arrow (Optional): If focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, either does nothing or moves focus to the last accordion header.
  • Home (Optional): When focus is on an accordion header, moves focus to the first accordion header.
  • End (Optional): When focus is on an accordion header, moves focus to the last accordion header.
  • Control + Page Down (Optional): If focus is inside an accordion panel or on an accordion header, moves focus to the next accordion header. If focus is in the last accordion header or panel, either does nothing or moves focus to the first accordion header.
  • Control + Page Up (Optional): If focus is inside an accordion panel, moves focus to the header for that panel. If focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, either does nothing or moves focus to the last accordion header.

WAI-ARIA Roles, States, and Properties:§

  • The title of each accordion header is contained in an element with role button.
  • Each accordion header button is wrapped in an element with role heading that has a value set for aria-level that is appropriate for the information architecture of the page.
    • If the native host language has an element with an implicit heading and aria-level, such as an HTML heading tag, a native host language element may be used.
    • The button element is the only element inside the heading element. That is, if there are other visually persistent elements, they are not included inside the heading element.
  • If the accordion panel associated with an accordion header is visible, the header button element has aria-expanded set to true. If the panel is not visible, aria-expanded is set to false.
  • The accordion header button element has aria-controls set to the ID of the element containing the accordion panel content.
  • If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true.
  • Optionally, each element that serves as a container for panel content has role region and aria-labelledby with a value that refers to the button that controls display of the panel.
    • Avoid using the region role in circumstances that create landmark region proliferation, e.g., in an accordion that contains more than approximately 6 panels that can be expanded at the same time.
    • Role region is especially helpful to the perception of structure by screen reader users when panels contain heading elements or a nested accordion.

2.3 Alert§

An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes.

Because alerts are intended to provide important and potentially time-sensitive information without interfering with the user's ability to continue working, it is crucial they do not affect keyboard focus. The alert dialog is designed for situations where interrupting work flow is necessary.

It is also important to avoid designing alerts that disappear automatically. An alert that disappears too quickly can lead to failure to meet WCAG 2.0 success criterion 2.2.3. Another critical design consideration is the frequency of interruption caused by alerts. Frequent interruptions inhibit usability for people with visual and cognitive disabilities, which makes meeting the requirements of WCAG 2.0 success criterion 2.2.4 more difficult.

Example§

Alert Example

Keyboard Interaction§

An alert (WAI-ARIA live region) does not require any keyboard interaction.

WAI-ARIA Roles, States, and Properties§

The widget has a role of alert.

2.4 Alert and Message Dialogs§

An alert dialog is a modal dialog that interrupts the user's workflow to communicate an important message and acquire a response. Examples include action confirmation prompts and error message confirmations. The alertdialog role enables assistive technologies and browsers to distinguish alert dialogs from other dialogs so they have the option of giving alert dialogs special treatment, such as playing a system alert sound.

Example§

Developing an example implementation of this pattern is issue 101.

Keyboard Interaction§

See the keyboard interaction section for the modal dialog pattern.

WAI-ARIA Roles, States, and Properties§

  • The element that contains all elements of the dialog, including the alert message and any dialog buttons, has role alertdialog.
  • The element with role alertdialog has either:
    • A value for aria-labelledby that refers to the element containing the title of the dialog if the dialog has a visible title.
    • A value for aria-label if the dialog does not have a visible title.
  • The element with role alertdialog has a value set for aria-describedby that refers to the element containing the alert message.

2.6 Button§

A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation. A common convention for informing users that a button launches a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…".

In addition to the ordinary button widget, WAI-ARIA supports 2 other types of buttons:

Note

The types of actions performed by buttons are distinctly different from the function of a link (see link pattern). It is important that both the appearance and role of a widget match the function it provides. Nevertheless, elements occasionally have the visual style of a link but perform the action of a button. In such cases, giving the element role button helps assistive technology users understand the function of the element. However, a better solution is to adjust the visual design so it matches the function and ARIA role.

Examples§

Button Examples: Examples of clickable HTML div and span elements made into accessible command and toggle buttons.

Keyboard Interaction§

When the button has focus:

  • Space: Activates the button.
  • Enter: Activates the button.
  • Following button activation, focus is set depending on the type of action the button performs. For example:
    • If activating the button opens a dialog, the focus moves inside the dialog. (see dialog pattern)
    • If activating the button closes a dialog, focus typically returns to the button that opened the dialog unless the function performed in the dialog context logically leads to a different element. For example, activating a cancel button in a dialog returns focus to the button that opened the dialog. However, if the dialog were confirming the action of deleting the page from which it was opened, the focus would logically move to a new context.
    • If activating the button does not dismiss the current context, then focus typically remains on the button after activation, e.g., an Apply or Recalculate button.
    • If the button action indicates a context change, such as move to next step in a wizard or add another search criteria, then it is often appropriate to move focus to the starting point for that action.
    • If the button is activated with a shortcut key, the focus usually remains in the context from which the shortcut key was activated. For example, if Alt + U were assigned to an "Up" button that moves the currently focused item in a list one position higher in the list, pressing Alt + U when the focus is in the list would not move the focus from the list.

WAI-ARIA Roles, States, and Properties§

  • The button has role of button.
  • The button has an accessible label. By default, the accessible name is computed from any text content inside the button element. However, it can also be provided with aria-labelledby" or aria-label.
  • If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.
  • When the action associated with a button is unavailable, the button has aria-disabled set to true.
  • If the button is a toggle button, it has an aria-pressed state. When the button is toggled on, the value of this state is true, and when toggled off, the state is false.

2.7 Checkbox§

WAI-ARIA supports two types of checkbox widgets:

  1. Dual-state: The most common type of checkbox, it allows the user to toggle between two choices -- checked and not checked.
  2. Tri-state: This type of checkbox supports an additional third state known as partially checked.

One common use of a tri-state checkbox can be found in software installers where a single tri-state checkbox is used to represent and control the state of an entire group of install options. And, each option in the group can be individually turned on or off with a dual state checkbox.

The user can use the tri-state checkbox to change all options in the group with a single action:

Examples§

Keyboard Interaction§

When the checkbox has focus, pressing the Space key changes the state of the checkbox.

WAI-ARIA Roles, States, and Properties§

  • The checkbox has role checkbox.
  • The checkbox has an accessible label, preferably provided by a visible label associated using aria-labelledby.
  • When checked, the checkbox element has state aria-checked set to true.
  • When not checked, it has state aria-checked set to false.
  • When partially checked, it has state aria-checked set to mixed.
  • If a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role group that has the property aria-labelledby set to the ID of the element containing the label.
  • If the presentation includes additional descriptive static text relevant to a checkbox or checkbox group, the checkbox or checkbox group has the property aria-describedby set to the ID of the element containing the description.

2.8 Combo Box§

Drafting this section is issue 31.

2.9 Dialog (Modal)§

A dialog is a window overlayed on either the primary window or another dialog window. Windows under a modal dialog are inert. That is, users cannot interact with content outside an active dialog window. Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern, and in some implementations, attempts to interact with the inert content cause the dialog to close.

Like non-modal dialogs, modal dialogs contain their tab sequence. That is, Tab and Shift + Tab do not move focus outside the dialog. However, unlike most non-modal dialogs, modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog.

The alertdialog role is a special-case dialog role designed specifically for dialogs that divert users' attention to a brief, important message. Its usage is described in the alert dialog design pattern.

Example§

Modal Dialog Example

Keyboard Interaction§

In the following description, the term tabbable element refers to any element with a tabindex value of zero or greater. Note that values greater than 0 are strongly discouraged.

  • When a dialog opens, focus moves to an element inside the dialog. See notes below regarding initial focus placement.
  • Tab:
    • Moves focus to the next tabbable element inside the dialog.
    • If focus is on the last tabbable element inside the dialog, moves focus to the first tabbable element inside the dialog.
  • Shift + Tab:
    • Moves focus to the previous tabbable element inside the dialog.
    • If focus is on the first tabbable element inside the dialog, moves focus to the last tabbable element inside the dialog.
  • Escape: Closes the dialog.
Note
  1. When a dialog opens, focus placement depends on the nature and size of the content.
    • In all circumstances, focus moves to an element contained in the dialog.
    • Unless a condition where doing otherwise is advisable, focus is initially set on the first focusable element.
    • If content is large enough that focusing the first interactive element could cause the beginning of content to scroll out of view, it is advisable to add tabindex=-1 to a static element at the top of the dialog, such as the dialog title or first paragraph, and initially focus that element.
    • If a dialog contains the final step in a process that is not easily reversible, such as deleting data or completing a financial transaction, it may be advisable to set focus on the least destructive action, especially if undoing the action is difficult or impossible. The Alert Dialog Pattern is often employed in such circumstances.
    • If a dialog is limited to interactions that either provide additional information or continue processing, it may be advisable to set focus to the element that is likely to be most frequently used, such as an OK or Continue button.
  2. When a dialog closes, focus returns to the element that invoked the dialog unless either:
    • The invoking element no longer exists. Then, focus is set on another element that provides logical work flow.
    • The work flow design includes the following conditions that can occasionally make focusing a different element a more logical choice:
      1. It is very unlikely users need to immediately re-invoke the dialog.
      2. The task completed in the dialog is directly related to a subsequent step in the work flow.
      For example, a grid has an associated toolbar with a button for adding rows. the Add Rows button opens a dialog that prompts for the number of rows. After the dialog closes, focus is placed in the first cell of the first new row.
  3. It is strongly recommended that the tab sequence of all dialogs include a visible element with role button that closes the dialog, such as a close icon or cancel button.

WAI-ARIA Roles, States, and Properties§

  • The element that serves as the dialog container has a role of dialog.
  • All elements required to operate the dialog are descendants of the element that has role dialog.
  • The dialog container element has aria-modal set to true.
  • The dialog has either:
  • Optionally, the aria-describedby property is set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Specifying descriptive elements enables screen readers to announce the description along with the dialog title and initially focused element when the dialog opens.
Note
  • Because marking a dialog modal by setting aria-modal to true can prevent users of some assistive technologies from perceiving content outside the dialog, users of those technologies will experience severe negative ramifications if a dialog is marked modal but does not behave as a modal for other users. So, mark a dialog modal only when both:
    1. Application code prevents all users from interacting in any way with content outside of it.
    2. Visual styling obscures the content outside of it.
  • The aria-modal property introduced by ARIA 1.1 replaces aria-hidden for informing assistive technologies that content outside a dialog is inert. However, in legacy dialog implementations where aria-hidden is used to make content outside a dialog inert for assistive technology users, it is important that:
    1. aria-hidden is set to true on each element containing a portion of the inert layer.
    2. The dialog element is not a descendant of any element that has aria-hidden set to true.

2.10 Dialog (Non-Modal)§

Drafting content for this section is tracked by issue 59.

2.11 Disclosure (Show/Hide)§

Drafting content for this section is tracked by issue 9.

Write description of disclosure pattern here.

Examples§

Keyboard Interaction§

When the disclosure control has focus:

  • Enter: activates the disclosure control and toggles the visibility of the disclosure content.
  • Space: activates the disclosure control and toggles the visibility of the disclosure content.

WAI-ARIA Roles, States, and Properties§

2.12 Feed§

Note

This section contains an early draft of new content. Feedback is welcome in issue 245.

A feed is a section of a page that automatically loads new content as the user reads. Content in a feed is segmented into article elements. Thus, it can be thought of as a dynamic list of articles that often appears to scroll infinitely.

The primary difference between a feed and other ARIA patterns that support loading data as users scroll, e.g., a grid, is that a feed is a structure, not a widget. This means assistive technologies with a reading mode, such as screen readers, will default to reading mode when interacting with feed content, making the feed pattern most useful for blocks of unstructured information that may contain links or other interactive elements.

For example, a product page on a shopping site may have a related products section that displays five products at a time. As the user scrolls, more products are requested and loaded into the DOM. While a static design might include a next button for loading five more products, a dynamic implementation that automatically loads data as needed simplifies the user experience and reduces the inertia associated with viewing more than the first five product suggestions.

Unfortunately, when web pages load content dynamically based on scroll events, it creates interoperability difficulties for users of assistive technologies that cannot sufficiently mimic visual scrolling. Even if the page also observes focus movements in order to identify when more content is needed, there can still be problems because requiring assistive technologies to move DOM focus in response to every reading cursor movement, regardless of context, can also negatively impact a screen reading experience.

The feed pattern enables reliable assistive technology reading mode interaction by establishing the following interoperability agreement between the web page and assistive technologies:

  1. In the context of a feed, the web page code is responsible for:
    • Appropriate visual scrolling of the content based on which article contains DOM focus.
    • Loading or removing feed articles based on which article contains DOM focus.
  2. In the context of a feed, assistive technologies with a reading mode are responsible for:
    • Indicating which article contains the reading cursor by ensuring the article element or one of its descendants has DOM focus.
    • providing reading mode keys that move DOM focus to the next and previous articles.
    • Providing reading mode keys for moving the reading cursor and DOM focus past the end and before the start of the feed.

Thus, implementing the feed pattern allows a screen reader to reliably read and trigger the loading of feed content while staying in its reading mode.

Another feature of the feed pattern is its ability to facilitate skim reading for assistive technology users. Web page authors may provide both an accessible name and description for each article. By identifying the elements inside of an article that provide the title and the primary content, assistive technologies can provide functions that enable users to jump from article to article and efficiently discern which articles may be worthy of more attention.

Example§

Example Implementation of Feed Pattern

Keyboard Interaction§

The feed pattern is not based on a desktop GUI widget so the feed role is not associated with any well-established keyboard conventions. Supporting the following, or a similar, interface is recommended.

When focus is inside the feed:

  • Page Down: Move focus to next article.
  • Page Up: Move focus to previous article.
  • Control + End: Move focus to the first focusable element after the feed.
  • Control + Home: Move focus to the first focusable element before the feed.
Note
  1. Due to the lack of convention, providing easily discoverable keyboard interface documentation is especially important.
  2. In some cases, a feed may contain a nested feed. For example, an article in a social media feed may contain a feed of comments on that article. To navigate the nested feed, users first move focus inside the nested feed. Options for supporting nested feed navigation include:
    • Users move focus into the nested feed from the content of the containing article with Tab. This may be slow if the article contains a significant number of links, buttons, or other widgets.
    • Provide a key for moving focus from the elements in the containing article to the first item in the nested feed, e.g., Alt + Page Down.
    • To continue reading the outer feed, Control + End moves focus to the next article in the outer feed.
  3. In the rare circumstance that a feed article contains a widget that uses the above suggested keys, the feed navigation key will operate the contained widget, and the user needs to move focus to an element that does not utilize the feed navigation keys in order to navigate the feed.

WAI-ARIA Roles, States, and Properties§

  • The element that contains the set of feed articles has role feed.
  • If the feed has a visible title, the feed element has aria-labelledby referring to the element containing the title. Otherwise, the feed element has a label specified with aria-label.
  • Each unit of content in a feed is contained in an element with role article. All content inside the feed is contained in an article element.
  • Each article element has aria-labelledby referring to elements inside the article that can serve as a distinguishing label.
  • It is optional but strongly recommended for Each article element to have aria-describedby referring to one or more elements inside the article that serve as the primary content of the article.
  • Each article element has aria-posinset set to a value that represents its position in the feed.
  • Each article element has aria-setsize set to a value that represents either the total number of articles that have been loaded or the total number in the feed, depending on which value is deemed more helpful to users. If the total number in the feed is undetermined, it can be represented by a aria-setsize value of -1.
  • When article elements are being added to or removed from the feed container, and if the operation requires multiple DOM operations, the feed element has aria-busy set to true during the update operation. Note that it is extremely important that aria-busy is set to false when the operation is complete or the changes may not become visible to some assistive technology users.

2.13 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 pater or the table pattern.

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.

Examples§

  • Layout Grid Examples: 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.
  • Data Grid Examples: Three example implementations of grid that include features relevant to presenting tabular information, such as content editing, sort, and column hiding.
  • Advanced Data Grid Example: Example of a grid with behaviors and features similar to a typical spreadsheet, including cell and row selection.

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 unknowingly 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.
Note
  • 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.
Note

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. Approaches 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.
Note
  • 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.
Note

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:

  1. Choosing whether a cell or an element inside a cell receives focus in response to grid navigation key events.
  2. 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:

  1. 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.
  2. 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:

  1. Editable content.
  2. Multiple widgets.
  3. 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 referring 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.
Note
  • 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 explanation.
Note

Editor's Note - Guidance for aria-owns has not yet been created. A link to it will be added above once created.

2.15 Listbox§

A listbox widget presents a list of options and allows a user to select one or more of them. A listbox that allows a single option to be chosen is a single-select listbox; one that allows multiple options to be selected is a multi-select listbox.

When screen readers present a listbox, they may render the name, state, and position of each option in the list. The name of an option is a string calculated by the browser, typically from the content of the option element. As a flat string, the name does not contain any semantic information. Thus, if an option contains a semantic element, such as a heading, screen reader users will not have access to the semantics. In addition, the interaction model conveyed by the listbox role to assistive technologies does not support interacting with elements inside of an option. Because of these traits of the listbox widget, it does not provide an accessible way to present a list of interactive elements, such as links, buttons, or checkboxes. To present a list of interactive elements, see the grid pattern.

Avoiding very long option names facilitates understandability and perceivability for screen reader users. The entire name of an option is spoken as a single unit of speech when the option is read. When too much information is spoken as the result of a single key press, it is difficult to understand. Long names inhibit perception by increasing the impact of interrupted speech because users typically have to re-read the entire option. And, if the user does not understand what is spoken, reading the name by character, word, or phrase may be a difficult operation for many screen reader users in the context of a listbox widget.

Sets of options where each option name starts with the same word or phrase can also significantly degrade usability for keyboard and screen reader users. Scrolling through the list to find a specific option becomes inordinately time consuming for a screen reader user who must listen to that word or phrase repeated before hearing what is unique about each option. For example, if a listbox for choosing a city were to contain options where each city name were preceded by a country name, and if many cities were listed for each country, a screen reader user would have to listen to the country name before hearing each city name. In such a scenario, it would be better to have 2 list boxes, one for country and one for city.

Examples§

Listbox Examples: Two examples of the listbox pattern demonstrating differences between single-select and multi-select implementation as well as the use of action buttons with key shortcuts for arranging items in a list.

Keyboard Interaction§

For a vertically oriented listbox:

  • When a single-select listbox receives focus:
    • If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected.
    • If an option is selected before the listbox receives focus, focus is set on the selected option.
  • When a multi-select listbox receives focus:
    • If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state.
    • If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected.
  • Down Arrow: Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus.
  • Up Arrow: Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus.
  • Home (Optional): Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
  • End (Optional): Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
  • Type-ahead is recommended for all listboxes, especially those with more than seven options:
    • Type a character: focus moves to the next item with a name that starts with the typed character.
    • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.
  • Multiple Selection: Authors may implement either of two interaction models to support multiple selection: a recommended model that does not require the user to hold a modifier key, such as Shift or Control, while navigating the list or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states.
    • Recommended selection model -- holding modifier keys is not necessary:
      • Space: changes the selection state of the focused option .
      • Shift + Down Arrow (Optional): Moves focus to and toggles the selected state of the next option.
      • Shift + Up Arrow (Optional): Moves focus to and toggles the selected state of the previous option.
      • Shift + Space (Optional): Selects contiguous items from the most recently selected item to the focused item.
      • Control + Shift + Home (Optional): Selects the focused option and all options up to the first option.
      • Control + Shift + End (Optional): Selects the focused option and all options down to the last option.
      • Control + A (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.
    • Alternative selection model -- moving focus without holding a Shift or Control modifier unselects all selected nodes except the focused node:
      • Shift + Down Arrow: Moves focus to and toggles the selection state of the next option.
      • Shift + Up Arrow: Moves focus to and toggles the selection state of the previous option.
      • Control + Down Arrow: Moves focus to the next option without changing its selection state.
      • Control + Up Arrow: Moves focus to the previous option without changing its selection state.
      • Control + Space Changes the selection state of the focused option.
      • Shift + Space (Optional): Selects contiguous items from the most recently selected item to the focused item.
      • Control + Shift + Home (Optional): Selects the focused option and all options up to the first option.
      • Control + Shift + End (Optional): Selects the focused option and all options down to the last option.
      • Control + A (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.
Note
  1. DOM focus (the active element) is functionally distinct from the selected state. For more details, see this description of differences between focus and selection.
  2. The listbox role supports the aria-activedescendant property, which provides an alternative to moving DOM focus among treeitem elements when implementing keyboard navigation. For details, see Managing Focus in Composites Using aria-activedescendant.
  3. In a single-select listbox, moving focus may optionally unselect the previously selected option and select the newly focused option. This model of selection is known as "selection follows focus". Having selection follow focus can be very helpful in some circumstances and can severely degrade accessibility in others. For additional guidance, see Deciding When to Make Selection Automatically Follow Focus.
  4. If selecting or unselecting all options is an important function, implementing separate controls for these actions, such as buttons for "Select All" and "Unselect All", significantly improves accessibility.
  5. If the options in a listbox are arranged horizontally:
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
    2. Up Arrow performs as Left Arrow is described above, and vice versa.

WAI-ARIA Roles, States, and Properties§

  • An element that contains or owns all the listbox options has role listbox.
  • Each option in the listbox has role option and is a DOM descendant of the element with role listbox or is referenced by an aria-owns property on the listbox element.
  • If the listbox is not part of another widget, then it has a visible label referenced by aria-labelledby on the element with role listbox.
  • In a single-select listbox, the selected option has aria-selected set to true.
  • if the listbox supports multiple selection:
  • If the complete set of available options is not present in the DOM due to dynamic loading as the user scrolls, their aria-setsize and aria-posinset attributes are set appropriately.
  • If options are arranged horizontally, the element with role listbox has aria-orientation set to horizontal. The default value of aria-orientation for listbox is vertical.

2.18 Radio Group§

A radio group is a set of checkable buttons, known as radio buttons, where only one button in the set may be in a checked state.

Examples§

Keyboard Interaction§

  • When a radio group receives focus:
    • If a radio button is checked, focus is set on the checked button.
    • If none of the radio buttons are checked, focus is set on the first radio button in the group.
  • Space: checks the focused radio button if it is not already checked.
  • Right Arrow and Down Arrow: move focus to the next radio button in the group, uncheck the previously focused button, and check the newly focused button. If focus is on the last button, focus moves to the first button.
  • Left Arrow and Up Arrow: move focus to the previous radio button in the group, uncheck the previously focused button, and check the newly focused button. If focus is on the first button, focus moves to the last button.
Note

The initial focus behavior described above differs slightly from the behavior provided by some browsers for native HTML radio groups. In some browsers, if none of the radio buttons are selected, moving focus into the radio group with Shift+Tab will place focus on the last radio button instead of the first radio button.

WAI-ARIA Roles, States, and Properties§

  • The radio buttons are contained in or owned by an element with role radiogroup .
  • Each radio button element has role radio .
  • If a radio button is checked, the radio element has aria-checked set to true. If it is not checked, it has aria-checked set to false.
  • Each radio element is labeled by its content, has a visible label referenced by aria-labelledby , or has a label specified with aria-label .
  • The radiogroup element has a visible label referenced by aria-labelledby or has a label specified with aria-label .
  • If elements providing additional information about either the radio group or each radio button are present, those elements are referenced by the radiogroup element or radio elements with the aria-describedby property.

2.19 Slider§

A slider is an input where the user selects a value from within a given range. Sliders typically have a slider thumb that can be moved along a bar or track to change the value of the slider.

Examples§

Keyboard Interaction§

  • Right Arrow: Increase the value of the slider by one step.
  • Up Arrow: Increase the value of the slider by one step.
  • Left Arrow: Decrease the value of the slider by one step.
  • Down Arrow: Decrease the value of the slider by one step.
  • Home: Set the slider to the first allowed value in its range.
  • End: Set the slider to the last allowed value in its range.
  • Page Up (Optional): Increment the slider by an amount larger than the step change made by Up Arrow.
  • Page Down (Optional): Decrement the slider by an amount larger than the step change made by Down Arrow.
Note
  1. Focus is placed on the slider (the visual object that the mouse user would move, also known as the thumb.
  2. In some circumstances, reversing the direction of the value change for the keys specified above, e.g., having Up Arrow decrease the value, could create a more intuitive experience.

WAI-ARIA Roles, States, and Properties§

  • The element serving as the focusable slider control has role slider.
  • The slider element has the aria-valuenow property set to a decimal value representing the current value of the slider.
  • The slider element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the slider.
  • The slider element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the slider.
  • If the value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the aria-valuetext property is set to a string that makes the slider value understandable, e.g., "Monday".
  • If the slider has a visible label, it is referenced by aria-labelledby on the slider element. Otherwise, the slider element has a label provided by aria-label.
  • If the slider is vertically oriented, it has aria-orientation set to vertical. The default value of aria-orientation for a slider is horizontal.

2.20 Slider (Multi-Thumb)§

Work on this design pattern is in progress and is tracked in issue 221. Please provide any feedback in that issue.

A multi-thumb slider is a slider with two or more thumbs that each set a value in a group of related values. Many two-thumb sliders set a maximum and minimum value for a range, and the thumbs are not allowed to pass one another. That is, the mthumb that sets the upper value of the range can not be set lower than the thumb that controls the lower value of the range. However, in some multi-thumb sliders, each thumb sets a value that does not depend on the other thumb values.

Example§

Work to develop an example multi-thumb slider is tracked in issue 124.

Keyboard Interaction§

  • Each thumb is in the page tab sequence and has the same keyboard interaction as a single-thumb slider.
  • The tab order remains constant regardless of thumb value and visual position within the slider. For example, if the value of a thumb changes such that it moves past one of the other thumbs, the tab order does not change.

WAI-ARIA Roles, States, and Properties§

  • Each element serving as a focusable slider thumb has role slider.
  • Each slider element has the aria-valuenow property set to a decimal value representing the current value of the slider.
  • Each slider element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the slider.
  • Each slider element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the slider.
  • If a value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the aria-valuetext property is set to a string that makes the slider value understandable, e.g., "Monday".
  • If a slider has a visible label, it is referenced by aria-labelledby on the slider element. Otherwise, the slider element has a label provided by aria-label.
  • If a slider is vertically oriented, it has aria-orientation set to vertical. The default value of aria-orientation for a slider is horizontal.

2.21 Spinbutton§

A spinbutton is an input widget that restricts its value to a set or range of discrete values. For example, in a widget that enables users to set an alarm, a spinbutton could allow users to select a number from 0 to 59 for the minute of an hour.

Spinbuttons often have three components, including a text field that displays the current value, an increment button, and a decrement button. The text field is usually the only focusable component because the increment and decrement functions are keyboard accessible via arrow keys. Typically, the text field also allows users to directly edit the value.

If the range is large, a spinbutton may support changing the value in both small and large steps. For instance, in the alarm example, the user may be able to move by 1 minute with Up Arrow and Down Arrow and by 10 minutes with Page Up and Page Down.

Example§

Work to develop a spinbutton example is tracked by issue 125.

Keyboard Interaction§

  • Text editing keys: If the spinbutton text field allows directly editing the value, the following keys are supported.
    • Standard single line text field keys, such as Left Arrow, Right Arrow, Shift + Left Arrow, Shift + Right Arrow, and Delete, for cursor movement, selecting text, and text deletion.
    • Characters that are permitted to be part of the value. For example, an hour-and-minute spinner would allow only integer values from 0 to 59, the colon ':', and the letters 'AM' and 'PM'. Any other character input does not change the contents of the text field nor the value of the spinbutton.
  • Up Arrow: Increases the value.
  • Down Arrow: Decreases the value.
  • Home: Sets the spinbutton to the minimum value.
  • End: Sets the spinbutton to the maximum value.
  • Page Up (Optional): Increases the value by a larger step than Up Arrow.
  • Page Down (Optional): Decreases the value by a larger step than Down Arrow.
Note

Focus remains on the text field during operation.

WAI-ARIA Roles, States, and Properties§

  • The focusable element serving as the spinbutton has role spinbutton. This is typically an element that supports text input.
  • The spinbutton element has the aria-valuenow property set to a decimal value representing the current value of the spinbutton.
  • The spinbutton element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the spinbutton if it has a known minimum value.
  • The spinbutton element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the spinbutton if it has a known maximum value.
  • If the value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the aria-valuetext property is set on the spinbutton element to a string that makes the spinbutton value understandable, e.g., "Monday".
  • If the spinbutton has a visible label, it is referenced by aria-labelledby on the spinbutton element. Otherwise, the spinbutton element has a label provided by aria-label.

2.22 Table§

Work on drafting this section is tracked by issue 90.

This is a place holder for a to-be-written section about data tables. The grid pattern includes text describing how to choose between using grid and table, and it links to this section. This section does not necessarily have to be part of the design pattern section.

2.23 Tabs§

Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. Each tab panel has an associated tab element, that when activated, displays the panel. The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge.

Terms used to describe this design pattern include:

Tabs or Tabbed Interface
A set of tab elements and their associated tab panels.
Tab List
A set of tab elements contained in a tablist element.
tab
An element in the tab list that serves as a label for one of the tab panels and can be activated to display that panel.
tabpanel
The element that contains the content associated with a tab.

When a tabbed interface is initialized, one tab panel is displayed and its associated tab is styled to indicate that it is active. When the user activates one of the other tab elements, the previously displayed tab panel is hidden, the tab panel associated with the activated tab becomes visible, and the tab is considered "active".

Examples§

Keyboard Interaction§

For the tab list:

  • Tab: When focus moves into the tab list, places focus on the active tab element . When the tab list contains the focus, moves focus to the next element in the page tab sequence outside the tablist, which is typically either the first focusable element inside the tab panel or the tab panel itself.
  • When focus is on a tab element in a horizontal tab list:
    • Left Arrow: moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Optionally, activates the newly focused tab (See note below).
    • Right Arrow: Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab. Optionally, activates the newly focused tab (See note below).
  • When focus is on a tab in a tablist with either horizontal or vertical orientation:
    • Space or Enter: Activates the tab if it was not activated automatically on focus.
    • Home (Optional): Moves focus to the first tab
    • End (Optional): Moves focus to the last tab.
    • Shift + F10: If the tab has an associated pop-up menu, opens the menu.
    • Delete (Optional): If deletion is allowed, deletes (closes) the current tab element and its associated tab panel. If any tabs remain, sets focus to the tab following the tab that was closed and activates the newly focused tab. Alternatively, or in addition, the delete function is available in a context menu.
Note
  1. It is recommended that tabs activate automatically when they receive focus as long as their associated tab panels are displayed without noticeable latency. This typically requires tab panel content to be preloaded. Otherwise, automatic activation slows focus movement, which significantly hampers users' ability to navigate efficiently across the tab list. For additional guidance, see 4.4 Deciding When to Make Selection Automatically Follow Focus.
  2. If the tabs in a tab list are arranged vertically:
    1. Down Arrow performs as Right Arrow is described above.
    2. Up Arrow performs as Left Arrow is described above.
  3. If the tab list is horizontal, it does not listen for Down Arrow or Up Arrow so those keys can provide their normal browser scrolling functions even when focus is inside the tab list.

WAI-ARIA Roles, States, and Properties§

  • The element that serves as the container for the set of tabs has role tablist.
  • Each element that serves as a tab has role tab and is contained within the element with role tablist.
  • Each element that contains the content panel for a tab has role tabpanel.
  • Each element with role tab has the property aria-controls referring to its associated tabpanel element.
  • The active tab element has the state aria-selected set to true and all other tab elements have it set to false.
  • Each element with role tabpanel has the property aria-labelledby referring to its associated tab element.
  • If a tab element has a pop-up menu, it has the property aria-haspopup set to true.
  • If the tablist element is vertically oriented, it has the property aria-orientation set to vertical. The default value of aria-orientation for a tablist element is horizontal.

2.24 Toolbar§

A toolbar is a container for grouping a set of controls, such as buttons, menubuttons, or checkboxes.

When a set of controls is visually presented as a group, the toolbar role can be used to communicate the presence and purpose of the grouping to screen reader users. Grouping controls into toolbars can also be an effective way of reducing the number of tab stops in the keyboard interface.

To optimize the benefit of toolbar widgets:

  1. Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar.
  2. Avoid including controls that require arrow keys to operate, such as textbox or radio group. If unavoidable, include only one such control and make it the last element .
  3. Use toolbar as a grouping element only if the group contains 3 or more controls.

Example§

Toolbar Example: A toolbar including buttons, links, and checkboxes that uses roving tabindex to manage focus.

Keyboard Interaction§

  • When the toolbar receives focus, focus is set on the first control that is not disabled. Optionally, if the toolbar has previously contained focus, focus is set on the control that last had focus.
  • For a horizontal toolbar (the default):
    • Left Arrow: Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element.
    • Right Arrow: Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element.
  • Home (Optional): Moves focus to first element.
  • End (Optional): Moves focus to last element.
Note
  1. If the items in a toolbar are arranged vertically:
    1. Down Arrow performs as Right Arrow is described above.
    2. Up Arrow performs as Left Arrow is described above.
  2. Typically, disabled elements are not focusable when navigating with a keyboard. However, in circumstances where discoverability of a function is crucial, it may be helpful if disabled controls are focusable so screen reader users are more likely to be aware of their presence. For additional guidance, see 4.7 Focusability of disabled controls.
  3. In applications where quick access to a toolbar is important, such as accessing an editor's toolbar from its text area, a documented shortcut key for moving focus from the relevant context to its corresponding toolbar is recommended.

WAI-ARIA Roles, States, and Properties§

  • The element that serves as the toolbar container has role toolbar.
  • If the toolbar has a visible label, it is referenced by aria-labelledby on the toolbar element. Otherwise, the toolbar element has a label provided by aria-label.
  • If the controls are arranged vertically, the toolbar element has aria-orientation set to vertical. The default orientation is horizontal.

2.25 Tooltip Widget§

Work on this design pattern is in progress and tracked by issue 128. Please provide feedback in that issue.

A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. It typically appears after a small delay and disappears when Escape is pressed or on mouse out.

Tooltip widgets do not receive focus. A hover that contains focusable elements can be made using the a non-modal dialog pattern.

Example§

Work to develop a tooltip example is tracked by issue 127.

Keyboard Interaction§

Escape: Dismisses the Tooltip.

Note
  1. Focus stays on the triggering element while the tooltip is displayed.
  2. If the tooltip is invoked when the trigger element receives focus, then it is dismissed when it no longer has focus (onBlur). If the tooltip is invoked with mouseIn, then it is dismissed with on mouseOut.

WAI-ARIA Roles, States, and Properties§

  • The element that serves as the tooltip container has role tooltip.
  • The element that triggers the tooltip references the tooltip element with aria-describedby.

2.26 Tree View§

A tree view widget presents a hierarchical list. Any item in the hierarchy may have child items, and items that have children may be expanded or collapsed to show or hide the children. For example, in a file system navigator that uses a tree view to display folders and files, an item representing a folder can be expanded to reveal the contents of the folder, which may be files, folders, or both.

Terms for understanding tree views include:

Node
An item in a tree.
Root Node
Node at the base of the tree; it may have one or more child nodes but does not have a parent node.
Child Node
Node that has a parent; any node that is not a root node is a child node.
End Node
Node that does not have any child nodes; an end node may be either a root node or a child node.
Parent Node
Node with one or more child nodes. It can be open (expanded) or closed (collapsed).
Open Node
Parent node that is expanded so its child nodes are visible.
Closed Node
Parent node that is collapsed so the child nodes are not visible.

When using a keyboard to navigate a tree, a visual keyboard indicator informs the user which node is focused. If the tree allows the user to choose just one item for an action, then it is known as a single-select tree, and the item with focus also has a selected state. However, in multi-select trees, which enable the user to select more than one item for an action, the selected state is independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. It is important that the visual design distinguish between items that are selected and the item that has focus. For more details, see this description of differences between focus and selection.

Examples§

Keyboard Interaction§

For a vertically oriented tree:

  • When a single-select tree receives focus:
    • If none of the nodes are selected before the tree receives focus, focus is set on the first node.
    • If a node is selected before the tree receives focus, focus is set on the selected node.
  • When a multi-select tree receives focus:
    • If none of the nodes are selected before the tree receives focus, focus is set on the first node.
    • If one or more nodes are selected before the tree receives focus, focus is set on the first selected node.
  • Right arrow:
    • When focus is on a closed node, opens the node; focus does not move.
    • When focus is on a open node, moves focus to the first child node.
    • When focus is on an end node, does nothing.
  • Left arrow:
    • When focus is on an open node, closes the node.
    • When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node.
    • When focus is on a root node that is also either an end node or a closed node, does nothing.
  • Down Arrow: Moves focus to the next node that is focusable without opening or closing a node.
  • Up Arrow: Moves focus to the previous node that is focusable without opening or closing a node.
  • Home: Moves focus to the first node in the tree without opening or closing a node.
  • End: Moves focus to the last node in the tree that is focusable without opening a node.
  • Enter: activates a node, i.e., performs its default action. For parent nodes, one possible default action is to open or close the node. In single-select trees where selection does not follow focus (see note below), the default action is typically to select the focused node.
  • Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes:
    • Type a character: focus moves to the next node with a name that starts with the typed character.
    • Type multiple characters in rapid succession: focus moves to the next node with a name that starts with the string of characters typed.
  • * (Optional): Expands all siblings that are at the same level as the current node.
  • Selection in multi-select trees: Authors may implement either of two interaction models to support multiple selection: a recommended model that does not require the user to hold a modifier key, such as Shift or Control, while navigating the list or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states.
    • Recommended selection model -- holding a modifier key while moving focus is not necessary:
      • Space: Toggles the selection state of the focused node.
      • Shift + Down Arrow (Optional): Moves focus to and toggles the selection state of the next node.
      • Shift + Up Arrow (Optional): Moves focus to and toggles the selection state of the previous node.
      • Shift + Space (Optional): Selects contiguous nodes from the last selected node to the current node.
      • Control + Shift + Home (Optional): Selects the node with focus and all nodes up to the first node.
      • Control + Shift + End (Optional): Selects the node with focus and all nodes down to the last node.
      • Control + A (Optional): Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.
    • Alternative selection model -- Moving focus without holding the Shift or Control modifier unselects all selected nodes except for the focused node:
      • Shift + Down Arrow: Moves focus to and toggles the selection state of the next node.
      • Shift + Up Arrow: Moves focus to and toggles the selection state of the previous node.
      • Control + Down Arrow: Without changing the selection state, moves focus to the next node.
      • Control + Up Arrow: Without changing the selection state, moves focus to the previous node.
      • Control + Space: Toggles the selection state of the focused node.
      • Shift + Space (Optional): Selects contiguous nodes from the most recently selected node to the current node.
      • Control + Shift + Home (Optional): Selects the node with focus and all nodes up to the first node.
      • Control + Shift + End (Optional): Selects the node with focus and all nodes down to the last node.
      • Control + A (Optional): Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.
Note
  1. DOM focus (the active element) is functionally distinct from the selected state. For more details, see this description of differences between focus and selection.
  2. The tree role supports the aria-activedescendant property, which provides an alternative to moving DOM focus among treeitem elements when implementing keyboard navigation. For details, see Managing Focus in Composites Using aria-activedescendant.
  3. In a single-select tree, moving focus may optionally unselect the previously selected node and select the newly focused node. This model of selection is known as "selection follows focus". Having selection follow focus can be very helpful in some circumstances and can severely degrade accessibility in others. For additional guidance, see Deciding When to Make Selection Automatically Follow Focus.
  4. If selecting or unselecting all nodes is an important function, implementing separate controls for these actions, such as buttons for "Select All" and "Unselect All", significantly improves accessibility.
  5. If the nodes in a tree are arranged horizontally:
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
    2. Up Arrow performs as Left Arrow is described above, and vice versa.

WAI-ARIA Roles, States, and Properties§

  • All tree nodes are contained in or owned by an element with role tree.
  • Each element serving as a tree node has role treeitem.
  • Each root node is contained in the element with role tree or referenced by an aria-owns property set on the tree element.
  • Each parent node contains or owns an element with role group.
  • Each child node is contained in or owned by an element with role group that is contained in or owned by the node that serves as the parent of that child.
  • Each element with role treeitem that serves as a parent node has aria-expanded set to false when the node is in a closed state and set to true when the node is in an open state. End nodes do not have the aria-expanded attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes.
  • If the tree supports selection of more than one node, the element with role tree has aria-multiselectable set to true. Otherwise, aria-multiselectable is either set to false or the default value of false is implied.
  • If the tree does not support multiple selection, aria-selected is set to true for the selected node and it is not present on any other node in the tree.
  • if the tree supports multiple selection:
  • The element with role tree has either a visible label referenced by aria-labelledby or a value specified for aria-label.
  • If the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has aria-level, aria-setsize, and aria-posinset specified.
  • If the tree element is horizontally oriented, it has aria-orientation set to horizontal. The default value of aria-orientation for a tree is vertical.
Note

If aria-owns is set on the tree container to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order.

2.27 Window Splitter§

Work is in progress on this design pattern and is tracked by issue 129.

A window splitter is a moveable separator between two sections, or panes, of a window that enables users to change the relative size of the panes. A Window Splitter can be either variable or fixed. A fixed splitter toggles between two positions whereas a variable splitter can be adjusted to any position within an allowed range.

A window splitter has a value that represents the size of one of the panes, which, in this pattern, is called the primary pane. When the splitter has its minimum value, the primary pane has its smallest size and the secondary pane has its largest size. The splitter also has an accessible name that matches the name of the primary pane.

For example, consider a book reading application with a primary pane for the table of contents and a secondary pane that displays content from a section of the book. The two panes are divided by a vertical splitter labeled "Table of Contents". When the table of contents pane has its maximum size, the splitter has a value of 100, and when the table of contents is completely collapsed, the splitter has a value of 0.

Note that the term "primary pane" does not describe the importance or purpose of content inside the pane.

Example§

Work to develop an example window splitter widget is tracked by issue 130.

Keyboard Interaction§

  • Left Arrow: Moves a vertical splitter to the left.
  • Right Arrow: Moves a vertical splitter to the right.
  • Up Arrow: Moves a horizontal splitter up.
  • Down Arrow: Moves a horizontal splitter down.
  • Enter: If the primary pane is not collapsed, collapses the pane. If the pane is collapsed, restores the splitter to its previous position.
  • Home (Optional): Moves splitter to the position that gives the primary pane its smallest allowed size. This may completely collapse the primary pane.
  • End (Optional): Moves splitter to the position that gives the primary pane its largest allowed size. This may completely collapse the secondary pane.
  • F6 (Optional): Cycle through window panes.
Note

A fixed size splitter omits implementation of the arrow keys.

WAI-ARIA Roles, States, and Properties§

  • The element that serves as the focusable splitter has role separator.
  • The separator element has the aria-valuenow property set to a decimal value representing the current position of the separator.
  • The separator element has the aria-valuemin property set to a decimal value that represents the position where the primary pane has its minimum size. This is typically 0.
  • The separator element has the aria-valuemax property set to a decimal value that represents the position where the primary pane has its maximum size . This is typically 100.
  • If the primary pane has a visible label, it is referenced by aria-labelledby on the separator element. Otherwise, the separator element has a label provided by aria-label.
  • The separator element has aria-controls referring to the primary pane.

3. Landmark Regions§

ARIA landmark roles provide a powerful way to identify the organization and structure of a web page. By classifying and labeling sections of a page, they enable structural information that is conveyed visually through layout to be represented programmatically. Screen readers exploit landmark roles to provide keyboard navigation to important sections of a page. Landmark regions can also be used as targets for "skip links" and by browser extensions to enhanced keyboard navigation.

This section explains how HTML5 sectioning elements and ARIA landmark roles are used to make it easy for assistive technology users to understand the meaning of the layout of a page.

3.1 HTML5 Sectioning Elements§

Several HTML5 sectioning elements automatically create ARIA landmark regions. So, in order to provide assistive technology users with a logical view of a page, it is important to understand the effects of using HTML5 sectioning elements. More information on HTML5 element role mapping.

Default landmark roles for HTML5 sectioning elements
HTML5 Element Default Landmark Role
aside complementary
footer contentinfo when in context of the body element
header banner when in context of the body element
main main
nav navigation
section region when it has an accessible name using aria-labelledby or aria-label

3.2 General Principles of Landmark Design§

Including all content on a page in one of its landmark regions and giving each landmark region a semantically meaningful role is one of the most effective ways of ensuring assistive technology users will not overlook information that is relevant to their needs.

Step 1: Identify the logical structure

Step 2: Assign landmark roles to each area

Step 3: Label areas

3.3 Landmark Roles§

3.3.1 Banner§

A banner landmark identifies site-oriented content at the beginning of each page within a website. Site-oriented content typically includes things such as the logo or identity of the site sponsor, and site-specific search tool. A banner usually appears at the top of the page and typically spans the full width.

  • Each page may have one banner landmark.
  • The banner landmark should be a top-level landmark.
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one banner landmark.
  • If a page includes more than one banner landmark, each should have a unique label (see Step 3 above).
HTML5 Techniques§
  • The HTML5 header element defines a banner landmark when its context is the body element.
  • The HTML5 header element is not considered a banner landmark when it is descendant of any of following elements (see HTML Accessibility Mappings):
    • article
    • aside
    • main
    • nav
    • section
ARIA Techniques§

If the HTML5 header element technique is not being used, a role="banner" attribute should be used to define a banner landmark.

Examples§

Banner Landmark Example

3.3.2 Complementary§

A complementary landmark is a supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.

  • complementary landmarks should be top level landmarks (e.g. not contained within any other landmarks).
  • If the complementary content is not related to the main content, a more general role should be assigned (e.g. region).
  • If a page includes more than one complementary landmark, each should have a unique label (see Step 3 above).
HTML5 Technique§

Use the HTML5 aside element to define a complementary landmark.

ARIA Technique§

If the HTML5 aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.

Examples§

Complementary Landmark Example

3.3.3 Contentinfo§

A contentinfo landmark is a way to identify common information at the bottom of each page within a website, typically called the "footer" of the page, including information such as copyrights and links to privacy and accessibility statements.

  • Each page may have one contentinfo landmark.
  • The contentinfo landmark should be a top-level landmark.
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one contentinfo landmark.
  • If a page includes more than one contentinfo landmark, each should have a unique label (see Step 3 above).
HTML5 Techniques§
  • The HTML5 footer element defines a contentinfo landmark when its context is the body element.
  • The HTML5 footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings):
    • article
    • aside
    • main
    • nav
    • section
ARIA Technique§

If the HTML5 footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.

Examples§

Contentinfo Landmark Example

3.3.4 Form§

A form landmark identifies a region that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main or search).

  • Use the search landmark instead of the form landmark when the form is used for search functionality.
  • A form landmark should have a label to help users understand the purpose of the form.
  • A label for the form landmark should be visible to all users (e.g. an h1-h6 element).
  • If a page includes more than one form landmark, each should have a unique label (see Step 3 above).
  • Whenever possible, controls contained in a form landmark in an HTML document should use native host semantics:
    • button
    • input
    • select
    • textarea
HTML5 Techniques§

The HTML5 form element that defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

ARIA Technique§

Use the role="form" to identify a region of the page; do not use it to identify every form field.

Examples§

Form Landmark Example

3.3.5 Main§

A main landmark identifies the primary content of the page.

  • Each page should have one main landmark.
  • The main landmark should be a top-level landmark.
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one main landmark.
  • If a page includes more than one main landmark, each should have a unique label (see Step 3 above).
HTML5 Technique§

Use the HTML5 main element to define a main landmark.

ARIA Technique§

If the HTML5 main element technique is not being used, use a role="main" attribute to define a main landmark.

Examples§

Main Landmark Example

3.3.6 Navigation§

Navigation landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation.

  • If a page includes more than one navigation landmark, each should have a unique label (see Step 3 above).
  • If a navigation landmark has an identical set of links as another navigation landmark on the page, use the same label for each navigation landmark.
HTML5 Technique§

Use the HTML5 nav element to define a navigation landmark.

ARIA Technique§

If the HTML5 nav element technique is not being used, use a role="navigation" attribute to define a navigation landmark.

Examples§

Navigation Landmark Example

3.3.7 Region§

A region landmark is a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section.

  • A region landmark must have a label.
  • If a page includes more than one region landmark, each should have a unique label (see Step 3 above).
  • The region landmark can be used identify content that named landmarks do not appropriately describe.
HTML5 Technique§

Use the HTML5 section element to define a region landmark.

ARIA Technique§

If the HTML5 section element technique is not being used, use a role="region" attribute to define a region landmark.

Examples§

Region Landmark Example

4. Developing a Keyboard Interface§

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:

  1. Understanding fundamental principles of focus movement conventions used in ARIA design patterns.
  2. Maintaining visible focus, predictable focus movement, and distinguishing between keyboard focus and the selected state.
  3. Managing movement of keyboard focus between components, e.g., how the focus moves when the Tab and Shift+Tab keys are pressed.
  4. Managing movement of keyboard focus inside components that contain multiple focusable elements, e.g., two different methods for programmatically exposing focus inside widgets like radio groups, menus, listboxes, trees, and grids.
  5. Determining when to make disabled interactive elements focusable.
  6. Assigning and revealing keyboard shortcuts, including guidance on how to avoid problematic conflicts with keyboard commands of assistive technologies, browsers, and operating systems.

4.1 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:

4.2 Discernible and Predictable Keyboard Focus§

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.

  1. 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 4.3 Focus VS Selection and the Perception of Dual Focus, especially when a component that contains selected elements does not contain the focus.
    • ... other considerations to be added ...
  2. 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, effectively causing a loss of focus within the user interface.
  3. 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.

4.3 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:

4.4 Deciding When to Make Selection Automatically Follow Focus§

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 detrimental 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 devastating 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.

4.5 Keyboard Navigation Between Components (The Tab Sequence)§

As explained in section 4.1 Fundamental Keyboard Navigation Conventions, all interactive UI components need to be reachable via 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 Discernible 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.

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.

4.6 Keyboard Navigation Inside Components§

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 receives 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.

4.6.1 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.

4.6.2 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:
  • 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.
  • 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.

  1. The element referenced as active is a DOM descendant of the focused referencing element.
  2. The focused referencing element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
  3. 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:
    1. The element referenced as active is a descendant of the controlled element.
    2. The controlled element has a value specified for the aria-owns property that includes the ID of the element referenced as active.

4.6.3 Nested Composite Components - Composites and Toolbars That Contain Composites§

Work to draft content for this section is tracked by issue 218.

4.7 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 2.16 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.

  1. For elements that are in the tab sequence when enabled, remove them from the tab sequence when disabled.
  2. For the following composite widget elements, keep them focusable when disabled:
  3. For elements contained in a toolbar, make them focusable if discoverability is a concern. Here are two examples to aid with this judgment.
    1. 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.
    2. 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 4.8 Keyboard Shortcuts.

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:

  1. Understanding how keyboard shortcuts augment a keyboard interface and whether to make a particular shortcut move focus, perform a function, or both.
  2. Making key assignments and avoiding assignment conflicts with assistive technologies, browsers, and operating systems.
  3. Exposing and documenting key assignments.

4.8.1 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:

  1. Ensuring discovery through navigation; keyboard shortcuts enhance, not replace, standard keyboard access.
  2. Effectively choosing from among the following behaviors:
    1. Navigation: Moving focus to an element.
    2. Activation: Performing an operation associated with an element that does not have focus and might not be visible.
    3. Navigation and activation: Both moving focus to an element and activating it.
  3. Balancing efficiency and cognitive load: lack of a shortcut can reduce efficiency while too many shortcuts can increase cognitive load and clutter the experience.
4.8.1.1 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:

  1. 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.
  2. 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.
  3. Not all devices that depend on keyboard interfaces can support keyboard shortcuts.
4.8.1.2 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 function 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 beneficial 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.
4.8.1.3 Choose Where to Add Shortcuts §

Work to draft content for this section is tracked in issue 219.

The first goal when designing a keyboard interface is simple, efficient, 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:

  1. To be written.

4.8.2 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.

Note

In the following sections, meta key refers to the Windows key on Windows-compatible keyboards and the Command key on MacOS-compatible keyboards.

4.8.2.1 Operating System Key Conflicts§

It is essential to avoid conflicts with keys that perform system level functions, such as application and window management and display and sound control. In general, this can be achieved by refraining from the following types of assignments.

  1. Any modifier keys + any of Tab, Enter, Space, or Escape.
  2. Meta key + any other single key (there are exceptions, but they can be risky as these keys can change across versions of operating systems).
  3. Alt + a function key.

In addition, there are some important application level features that most applications, including browsers, generally support. These include:

  1. Zoom
  2. Copy/Paste
  3. ... to be continued ...
4.8.2.2 Assistive Technology Key Conflicts§

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.

  1. Caps Lock + any other combination of keys.
  2. Insert + any combination of other keys.
  3. Scroll Lock + any combination of other keys.
  4. Mac OS only: Control+Option + any combination of other keys.
4.8.2.3 Browser Key Conflicts§

While there is considerable similarity among browser keyboard schemes, the patterns within the schemes are less homogenous. 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:

  1. Address or location bar
  2. Notification bar
  3. Page refresh
  4. Bookmark and history functions
  5. Find functions
4.8.2.4 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 ...

4.8.3 Exposing and Documenting Keyboard Shortcuts§

Work to complete this section is tracked in issue 167.

5. Grid and Table Properties§

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.

6. Intentionally Hiding Semantics with the presentation Role§

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 presentation.

For example, consider a tabs widget built using an HTML ul element.

    <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 presentation are:

  1. Hiding a decorative image; it is equivalent to giving the image null alt text.
  2. Suppressing table semantics of tables used for layout in circumstances where the table semantics do not convey meaningful relationships.
  3. Eliminating semantics of intervening orphan elements in the structure of a composite widget, such as a tablist, menu, or tree as demonstrated in the example above.

6.1 Effects of Role presentation §

When 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.

  1. The element’s implied ARIA role and any ARIA states and properties associated with that role are hidden from assistive technologies.
  2. Text contained by the element, i.e., inner text, as well as inner text of all its descendant elements remains visible to assistive technologies except, of course, when the text is explicitly hidden, e.g., styled with display: none or has aria-hidden="true".
  3. The roles, states, and properties of each descendant element remains visible to assistive technologies unless the descendant requires the context of the presentational element. For example:
    • If presentation is applied to a ul or ol element, each child li element inherits the presentation role because ARIA requires the listitem elements to have the parent list element. So, the li elements are not exposed to assistive technologies, but elements contained inside of those li elements, including nested lists, are visible to assistive technologies.
    • Similarly, if presentation is applied to a table element, The descendant caption, thead, tbody, tfooter, tr, th, and td elements inherit role presentation and are thus not exposed to assistive technologies. But, elements inside of the th and td elements, including nested tables, are exposed to assistive technologies.

6.2 Conditions That Cause Role presentation to be Ignored §

Browsers ignore role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:

6.3 Examples Demonstrating Effects of the presentation Role §

This code:

        <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>
      

The 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.

7. Roles That Automatically Hide Semantics by Making Their Descendants Presentational§

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>
    

See the section about role presentation for a detailed explanation of what it does.

A. Appendices§

A.1 Understanding Screen Reader Document Reading and Application Reading Modes§

Drafting content for this section is issue 193.

Placeholder for a section covering this topic that is yet to be written.

A.2 Background on WAI-ARIA§

[Placeholder section that will be resolved by issue #84.]

A.3 Change History§

A.3.1 Changes in June 2017 Working Draft§

  • Added the following:
    • Modal dialog example
    • Disclosure design pattern
    • Example disclosure for FAQ
    • Example disclosure for image description
    • Draft of feed pattern
    • Example feed implementation
    • Example of menu button using aria-activedescendant
    • Example of tabs with manual activation
  • Design pattern section: moved examples subsection of each design pattern to be the first subsection.
  • Across all example pages:
    • Improved visual design of tables that document keyboard implementation, roles, states, and properties.
    • Improved consistency of editorial style.
  • Significant revisions of guidance and implementation were made to the following design patterns and example pages:
    • Accordion example
    • Alert example
    • Breadcrumb example
    • Button example
    • Checkbox examples
    • Dialog (modal) design pattern
    • Grid examples
    • Landmark examples
    • Link example
    • Listbox example
    • Menubar examples
    • Menu button examples
    • Radio group example
    • Slider design pattern
    • Slider example
    • Example of tabs with automatic activation
    • Tree view examples

Also see:

A.4 Acknowledgments§

This section is non-normative.

The following people contributed to the development of this document.

A.4.1 Participants active in the ARIA WG at the time of publication§

  • Ann Abbott (IBM Corporation)
  • Michiel Bijl (The Paciello Group)
  • Christy Blew (University of Illinois at Urbana-Champaign)
  • Teresa Boers (IBM Corporation)
  • David Bolter (Mozilla Foundation)
  • Michael Cooper (W3C/MIT)
  • James Craig (Apple Inc.)
  • Joanmarie Diggs (Igalia)
  • Fred Esch (IBM Corporation)
  • Steve Faulkner (The Paciello Group)
  • John Foliot (Invited Expert)
  • Bryan Garaventa (SSB BART Group)
  • Matt Garrish (DAISY Consortium)
  • Billy Gregory (The Paciello Group)
  • Karl Groves (The Paciello Group)
  • Jon Gunderson (University of Illinois at Urbana-Champaign)
  • Markus Gylling (DAISY Consortium)
  • Markku Hakkinen (Educational Testing Service)
  • Katie Haritos-Shea (Knowbility)
  • Susann Keohane (IBM Corporation)
  • Matthew King (Facebook)
  • Jason Kiss (Department of Internal Affairs, New Zealand Government)
  • Jamie Knight (British Broadcasting Corporation)
  • JaEun Jemma Ku (University of Illinois at Urbana-Champaign)
  • Shane McCarron (Invited Expert, Aptest)
  • Charles McCathie Nevile (Yandex)
  • Mary Jo Mueller (IBM Corporation)
  • James Nurthen (Oracle Corporation)
  • Ian Pouncey (The Paciello Group, LLC)
  • Mark Sadecki (Invited Expert)
  • Janina Sajka (Invited Expert, The Linux Foundation)
  • Joseph Scheuhammer (Invited Expert, Inclusive Design Research Centre, OCAD University)
  • Stefan Schnabel (SAP AG)
  • Richard Schwerdtfeger (IBM Corporation)
  • Lisa Seeman (Invited Expert)
  • Tzviya Siegman (Wiley)
  • Cynthia Shelly (Microsoft Corporation)
  • Alexander Surkov (Mozilla Foundation)
  • Léonie Watson (The Paciello Group)
  • Jason White (Educational Testing Service)
  • Gottfried Zimmermann (Invited Expert, Access Technologies Group)

A.4.2 Other ARIA contributors, commenters, and previously active participants§

  • Shadi Abou-Zahra (W3C)
  • Jim Allan (TSB)
  • Jonny Axelsson (Opera Software)
  • David Baron (Mozilla Foundation)
  • Art Barstow (Nokia Corporation)
  • Simon Bates
  • Chris Blouch (AOL)
  • Judy Brewer (W3C/MIT)
  • Mark Birbeck (Sidewinder Labs)
  • Sally Cain (Royal National Institute of Blind People (RNIB))
  • Gerardo Capiel (Benetech)
  • Ben Caldwell (Trace)
  • Sofia Celic-Li
  • Jaesik Chang (Samsung Electronics Co., Ltd.)
  • Alex Qiang Chen (University of Manchester)
  • Charles Chen (Google, Inc.)
  • Christian Cohrs
  • Deborah Dahl
  • Erik Dahlström (Opera Software)
  • Dimitar Denev (Frauenhofer Gesellschaft)
  • Micah Dubinko (Invited Expert)
  • Mandana Eibegger
  • Beth Epperson (Websense)
  • Donald Evans (AOL)
  • Chris Fleizach (Apple Inc.)
  • Kelly Ford (Microsoft Corporation)
  • Geoff Freed (Invited Expert, NCAM)
  • Christopher Gallelo (Microsoft Corporation)
  • Birkir Gunnarsson (Deque Systems, Inc.)
  • Kentarou Fukuda (IBM Corporation)
  • Bryan Garaventa
  • Guido Geloso
  • Ali Ghassemi
  • Becky Gibson (IBM)
  • Alfred S. Gilman
  • Andres Gonzalez (Adobe Systems Inc.)
  • Scott González (JQuery Foundation)
  • James Graham
  • Georgios Grigoriadis (SAP AG)
  • Jeff Grimes (Oracle)
  • Loretta Guarino Reid (Google, Inc.)
  • Barbara Hartel
  • James Hawkins (Google, Inc.)
  • Benjamin Hawkes-Lewis
  • Sean Hayes (Microsoft Corporation)
  • Mona Heath (University of Illinois at Urbana-Champaign)
  • Jan Heck
  • Shawn Henry
  • Tina Homboe
  • John Hrvatin (Microsoft Corporation)
  • Takahiro Inada
  • Masayasu Ishikawa (W3C)
  • Jim Jewitt
  • Kenny Johar (Microsoft Corporation)
  • Shilpi Kapoor (BarrierBreak Technologies)
  • Masahiko Kaneko (Microsoft Corporation)
  • Marjolein Katsma
  • George Kerscher (International Digital Publishing Forum)
  • Jason Kiss (New Zealand Government)
  • Todd Kloots
  • Johannes Koch
  • Sam Kuper
  • Earl Johnson (Sun)
  • Jael Kurz
  • Rajesh Lal (Nokia Corporation)
  • Diego La Monica (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  • Aaron Leventhal (IBM Corporation)
  • Gez Lemon (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  • Alex Li (SAP)
  • Chris Lilley
  • Thomas Logan (HiSoftware Inc.)
  • William Loughborough (Invited Expert)
  • Linda Mao (Microsoft)
  • David MacDonald (Invited Expert, CanAdapt Solutions Inc.)
  • Carolyn MacLeod
  • Anders Markussen (Opera Software)
  • Krzysztof Maczyński
  • Matthew May (Adobe Systems Inc.)
  • Dominic Mazzoni (Google, Inc.)
  • Alexandre Morgaut (4D)
  • Ann Navarro (Invited Expert)
  • Joshue O Connor (Invited Expert, CFIT)
  • Artur Ortega (Microsoft Corporation)
  • Sailesh Panchang (Deque)
  • Lisa Pappas (Society for Technical Communication (STC))
  • Marta Pawlowlska (Samsung Electronics Co., Ltd.)
  • Dave Pawson (RNIB)
  • Steven Pemberton (CWI Amsterdam)
  • Simon Pieters (Opera Software)
  • Jean-Bernard Piot (4D)
  • David Poehlman, Simon Pieters (Opera Software)
  • Sarah Pulis (Media Access Australia)
  • T.V. Raman (Google, Inc.)
  • Jan Richards
  • Gregory Rosmaita (Invited Expert)
  • Tony Ross (Microsoft Corporation)
  • Alex Russell (Dojo Foundation) (
  • Mark Sadecki (Invited Expert)
  • Mario Sánchez Prada (Samsung Electronics Co., Ltd. and Gnome Foundation)
  • Martin Schaus (SAP AG)
  • Doug Schepers (W3C)
  • Matthias Schmitt
  • Marc Silbey (Microsoft Corporation)
  • Leif Halvard Sili
  • Henri Sivonen (Mozilla)
  • Michael Smith (W3C)
  • Andi Snow-Weaver (IBM Corporation)
  • Ville Skyttä
  • Henny Swan (BBC)
  • Neil Soiffer (Design Science)
  • Vitaly Sourikov
  • Mike Squillace (IBM)
  • Maciej Stachowiak (Apple Inc.)
  • Christophe Strobbe
  • Suzanne Taylor (Pearson plc)
  • Terrill Thompson
  • David Todd
  • Gregg Vanderheiden (Invited Expert, Trace)
  • Anne van Kesteren
  • Wen He (Tencent)
  • Wu Wei (W3C / RITT)
  • Ryan Williams (Oracle)
  • Tom Wlodkowski
  • Sam White (Apple Inc.)
  • Marco Zehe (Mozilla Foundation)

A.4.3 Enabling funders§

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.

B. References§

B.1 Informative references§

[WAI-ARIA]
Accessible Rich Internet Applications (WAI-ARIA) 1.1. James Craig; Michael Cooper; Shane McCarron et al. W3C. W3C Working Draft. URL: http://www.w3.org/TR/wai-aria-1.1/
[WAI-ARIA-ROADMAP]
Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap). Richard Schwerdtfeger. W3C. 4 February 2008. W3C Working Draft. URL: https://www.w3.org/TR/wai-aria-roadmap/