This document provides readers with an understanding of how to use WAI-ARIA 1.1 [WAI-ARIA] to create accessible rich internet applications. It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties. This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers.
This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at //www.tf5x.com.cn/TR/.
This is the WAI-ARIA Authoring Practices 1.1 Working Group Note by the Accessible Rich Internet Applications Working Group. It supports the Accessible Rich Internet Applications 1.1 W3C Recommendation [wai-aria-1.1], providing detailed advice and examples beyond what would be appropriate to a technical specification but which are important to understand the specification.
WAI-ARIA Authoring Practices 1.1 was previously published as a Working Group Note in December 2017, to accompany the WAI-ARIA 1.1 Recommendation, and was republished in July 2018 with additional design pattern and examples. Since then, the group has added further design patterns, and improved the quality of many of the other design patterns and examples, to improve the support for WAI-ARIA 1.1. Details of changes are described in the change log. Separately, WAI-ARIA Authoring Practices 1.2 includes the improvements in this document plus additional features specific to WAI-ARIA 1.2.
To comment, file an issue in the W3C ARIA Practices GitHub repository, or if that is not possible, send email to [email protected] (comment archive).
This document was published by the Accessible Rich Internet Applications Working Group as a Working Group Note.
Publication as a Working Group Note 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 W3C Patent Policy.
This document is governed by the 1 February 2018 W3C Process Document.
This section is informative.
WAI-ARIA Authoring Practices is a guide for understanding how to use WAI-ARIA 1.1 to create an accessible Rich Internet Application. It provides guidance on the appropriate application of WAI-ARIA, describes recommended WAI-ARIA usage patterns, and explains concepts behind them.
After a brief
Read Me First section, the guide begins with ARIA implementation patterns for common widgets that both enumerate expected behaviors and demonstrate those behaviors with working code.
The implementation patterns and examples refer to detailed explanations of supporting concepts in subsequent guidance sections.
The guidance sections cover more general topics such as use of ARIA landmarks, practices for keyboard interfaces, grid and table properties, and the effects of role
Functionally, ARIA roles, states, and properties are analogous to a CSS for assistive technologies. For screen reader users, ARIA controls the rendering of their non-visual experience. Incorrect ARIA misrepresents visual experiences, with potentially devastating effects on their corresponding non-visual experiences.
Before using ARIA or any of the guidance in this document, please take time to understand the following two essential principles.
<div role="button">Place Order</div>
Is a promise that the author of that
Unlike HTML input elements, ARIA roles do not cause browsers to provide keyboard behaviors or styling.
Using a role without fulfilling the promise of that role is similar to making a "Place Order" button that abandons an order and empties the shopping cart.
One of the objectives of this guide is to define expected behaviors for each ARIA role.
The information assistive technologies need about the meaning and purpose of user interface elements is called accessibility semantics. From the perspective of assistive technologies, ARIA gives authors the ability to dress up HTML and SVG elements with critical accessibility semantics that the assistive technologies would not otherwise be able to reliably derive.
Some of ARIA is like a cloak; it covers up, or overrides, the original semantics or content.
<a role="menuitem">Assistive tech users perceive this element as an item in a menu, not a link.</a> <a aria-label="Assistive tech users can only perceive the contents of this aria-label, not the link text">Link Text</a>
On the other hand, some uses of ARIA are more like suspenders or belts; they add meaning that provides essential support to the original content.
This is the power of ARIA. It enables authors to describe nearly any user interface component in ways that assistive technologies can reliably interpret, thus making components accessible to assistive technology users.
This is also the danger of ARIA. Authors can inadvertently override accessibility semantics.
<table role="log"> <!-- Table that assistive technology users will not perceive as a table. The log role tells browser this is a log, not a table. --> </table> <ul role="navigation"> <!-- This is a navigation region, not a list. --> <li><a href="uri1">nav link 1</li> <li><a href="uri2">nav link 2</li> <!-- ERROR! Previous list items are not in a list! --> </ul>
Testing assistive technology interoperability is essential before using code from this guide in production. Because the purpose of this guide is to illustrate appropriate use of ARIA 1.1 as defined in the ARIA specification, the design patterns, reference examples, and sample code intentionally do not describe and implement coding techniques for working around problems caused by gaps in support for ARIA 1.1 in browsers and assistive technologies. It is thus advisable to test implementations thoroughly with each browser and assistive technology combination that is relevant within a target audience.
Except in cases where the ARIA Working Group and other contributors have overlooked an error, examples in this guide that do not function well in a particular browser or with a specific assistive technology are demonstrating browser or assistive technology bugs. Browser and assistive technology developers can thus utilize code in this guide to help assess the quality of their support for ARIA 1.1.
Currently, this guide does not indicate which examples are compatible with mobile browsers or touch interfaces. While some of the examples include specific features that enhance mobile and touch support, some ARIA features are not supported in any mobile browser. In addition, there is not yet a standardized approach for providing touch interactions that work across mobile browsers.
More guidance about touch and mobile support is planned for future releases of the guide.
This section demonstrates how to make common rich internet application patterns and widgets accessible by applying WAI-ARIA roles, states, and properties and implementing keyboard support.
Unlike native HTML form elements, browsers do not provide keyboard support for graphical user interface (GUI) components that are made accessible with ARIA; authors have to provide the keyboard support in their code. This section describes the principles and methods for making the functionality of a web page that includes ARIA widgets, such as menus and grids, as well as interactive components, such as toolbars and dialogs, operable with a keyboard. Along with the basics of focus management, this section offers guidance toward the objective of providing experiences to people who rely on a keyboard that are as efficient and enjoyable as the experiences available to others.
This section covers:
Work to complete this section is tracked by issue 217.
When operating with a keyboard, two essentials of a good experience are the abilities to easily discern the location of the keyboard focus and to discover where focus landed after a navigation key has been pressed. The following factors affect to what extent a web page affords users these capabilities.
Occasionally, it may appear as if two elements on the page have focus at the same time. For example, in a multi-select list box, when an option is selected it may be greyed. Yet, the focus indicator can still be moved to other options, which may also be selected. Similarly, when a user activates a tab in a tablist, the selected state is set on the tab and its visual appearance changes. However, the user can still navigate, moving the focus indicator elsewhere on the page while the tab retains its selected appearance and state.
Focus and selection are quite different. From the keyboard user's perspective, focus is a pointer, like a mouse pointer; it tracks the path of navigation. There is only one point of focus at any time and all operations take place at the point of focus. On the other hand, selection is an operation that can be performed in some widgets, such as list boxes, trees, and tablists. If a widget supports only single selection, then only one item can be selected and very often the selected state will simply follow the focus when focus is moved inside of the widget. That is, in some widgets, moving focus may also perform the select operation. However, if the widget supports multiple selection, then more than one item can be in a selected state, and keys for moving focus do not perform selection. Some multi-select widgets do support key commands that both move focus and change selection, but those keys are different from the normal navigation keys. Finally, when focus leaves a widget that includes a selected element, the selected state persists.
From the developer's perspective, the difference is simple -- the focused element is the active element (document.activeElement).
Selected elements are elements that have
With respect to focus and the selected state, the most important considerations for designers and developers are:
in composite widgets where only one element may be selected, such as a tablist or single-select listbox, moving the focus may also cause the focused element to become the selected element. This is called having selection follow focus. Having selection follow focus is often beneficial to users, but in some circumstances, it is extremely 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.
As explained in section § 5.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 macOS, where it includes only form elements. macOS 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 § 5.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.
As described in section § 5.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 § 3. 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.
When using roving tabindex to manage focus in a composite UI component, the element that is to be included in the tab sequence has tabindex of "0" and all other focusable elements contained in the composite have tabindex of "-1". The algorithm for the roving tabindex strategy is as follows.
tabindex="0"on the element that will initially be included in the tab sequence and set
tabindex="-1"on all other focusable elements it contains.
tabindex="-1"on the element that has
tabindex="0"on the element that will become focused as a result of the key event.
element.focus(), on the element that has
tabindex="0"when the composite loses focus. If it does not, set
tabindex="0"on the target element and set
tabindex="-1"on the element that previously had
One benefit of using roving tabindex rather than aria-activedescendant to manage focus is that the user agent will scroll the newly focused element into view.
If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. Instead, only the container element needs to be included in the tab sequence. When the container has DOM focus, the value of aria-activedescendant on the container tells assistive technologies which element is active within the widget. Assistive technologies will consider the element referred to as active to be the focused element even though DOM focus is on the element that has the aria-activedescendant property. And, when the value of aria-activedescendant is changed, assistive technologies will receive focus change events equivalent to those received when DOM focus actually moves.
The steps for using the aria-activedescendant method of managing focus are as follows.
aria-activedescendant="IDREF"where IDREF is the ID of the element within the container that should be identified as active when the widget receives focus. The referenced element needs to meet the DOM relationship requirements described below.
The specification for aria-activedescendant places important restrictions on the DOM relationship between the focused element that has the aria-activedescendant attribute and the element referenced as active by the value of the attribute. One of the following three conditions must be met.
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 § 3.15 Menu or Menu bar pattern, disabled items are focusable when navigating through a menu with the arrow keys.
Removing focusability from disabled elements can offer users both advantages and disadvantages. Allowing keyboard users to skip disabled elements usually reduces the number of key presses required to complete a task. However, preventing focus from moving to disabled elements can hide their presence from screen reader users who "see" by moving the focus.
Authors are encouraged to adopt a consistent set of conventions for the focusability of disabled elements. The examples in this guide adopt the following conventions, which both reflect common practice and attempt to balance competing concerns.
One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in § 5.9 Keyboard Shortcuts.
The following key assignments can be used in any context where their conventionally associated functions are appropriate. While the assignments associated with Windows and Linux platforms can be implemented and used in browsers running in macOS, replacing them with macOS assignments in browsers running on a macOS device can make the keyboard interface more discoverable and intuitive for those users. In some cases, it may also help avoid system or browser keyboard conflicts.
|Function||Windows/Linux Key||macOS Key|
|open context menu||Shift + F10|
|Copy to clipboard||Control + C||Command + C|
|Paste from clipboard||Control + V||Command + V|
|Cut to clipboard||Control + X||Command + X|
|undo last action||Control + Z||Command + Z|
|Redo action||Control + Y||Command + Shift + Z|
When effectively designed, keyboard shortcuts that focus an element, activate a widget, or both can dramatically enhance usability of frequently used features of a page or site. This section addresses some of the keyboard shortcut design and implementation factors that most impact their effectiveness, including:
This section explains the following factors when determining which elements and features to assign keyboard shortcuts and what behavior to give each shortcut:
Before assigning keyboard shortcuts, it is essential to ensure the features and functions to which shortcuts may be assigned are keyboard accessible without a keyboard shortcut. In other words, all elements that could be targets for keyboard shortcuts need to be focusable via the keyboard using the methods described in:
Do not use keyboard shortcuts as a substitute for access via navigation. This is essential to full keyboard access because:
The following conventions may help identify the most advantageous behavior for a keyboard shortcut.
Work to draft content for this section is tracked in issue 219.
The first goal when designing a keyboard interface is simple, efficient, and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient , attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.
Consider the following when deciding where to assign keyboard shortcuts:
When choosing the keys to assign to a shortcut, there are many factors to consider.
Methods for designing a key shortcut scheme that supports learning and memory is beyond the scope of this guide. Unless the key shortcut scheme is extensive, it is likely sufficient to mimic concepts that are familiar from common desktop software, such as browsers. Similarly, while localization is important, describing how to address it is left to other resources that specialize in that topic.
The remainder of this section provides guidance balancing requirements and concerns related to key assignment conflicts. It is typically ideal if key assignments do not conflict with keys that are assigned to functions in the user's operating system, browser, or assistive technology. Conflicts can block efficient access to functions that are essential to the user, and a perfect storm of conflicts can trap a user. At the same time, there are some circumstances where intentional conflicts are useful. And, given the vast array of operating system, browser, and assistive technology keys, it is almost impossible to be certain conflicts do not exist. So it is also important to employ strategies that mitigate the impact of conflicts whether they are intentional or unknown.
In the following sections, meta key refers to the Windows key on Windows-compatible keyboards and the Command key on MacOS-compatible keyboards.
It is essential to avoid conflicts with keys that perform system level functions, such as application and window management and display and sound control. In general, this can be achieved by refraining from the following types of assignments.
In addition, there are some important application level features that most applications, including browsers, generally support. These include:
Even though assistive technologies have collectively taken thousands of key assignments, avoiding conflicts is relatively easy. This is because assistive technologies have had to develop key assignment schemes that avoid conflicts with both operating systems and applications. They do this by hijacking specific keys as modifiers that uniquely define their key commands. For example, many assistive technologies use the Caps Lock key as a modifier.
Deflect assistive technology key conflicts by steering clear of the following types of assignments.
While there is considerable similarity among browser keyboard schemes, the patterns within the schemes are less 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:
While avoiding key conflicts is usually desirable, there are circumstances where intentionally conflicting with a browser function is acceptable or even desirable. This can occur when the following combination of conditions arises:
For example, consider a save function that is available when the focus is in an editor. Most browsers use ... to be continued ...
To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the grid pattern or table pattern, assistive technologies need to be able to determine:
Browsers automatically populate their accessibility tree with the number of rows and columns in a grid or table based on the rendered DOM. However, there are many situations where the DOM does not contain the whole grid or table, such as when the data set is too large to fully render. Additionally, some of this information, like skipped columns or rows and how data is sorted, cannot be derived from the DOM structure.
The below sections explain how to use the following properties that ARIA provides for grid and table accessibility.
||Defines the total number of columns in a
||Defines the total number of rows in a
||Defines the number of columns spanned by a cell or gridcell within a
||Defines the number of rows spanned by a cell or gridcell within a
||Indicates if items in a row or column are sorted in ascending or descending order.|
When the number of rows represented by the DOM structure is not the total number of rows available for a table, grid, or treegrid,
aria-rowcount property is used to communicate the total number of rows available,
and it is accompanied by the
aria-rowindex property to identify the row indices of the rows that are present in the DOM.
aria-rowcount is specified on the element with the
Its value is an integer equal to the total number of rows available, including header rows.
If the total number of rows is unknown, a value of
-1 may be specified.
Using a value of
-1 indicates that more rows are available to include in the DOM without specifying the size of the available supply.
aria-rowcount is used on a
a value for
aria-rowindex property is specified on each of its descendant rows, including any header rows.
The value of
aria-rowindex is an integer that is:
aria-rowindexon any previous rows.
WARNING! Missing or inconsistent values of
aria-rowindex could have devastating effects on assistive technology behavior.
For example, specifying an invalid value for
aria-rowindex or setting it on some but not all rows in a table, could cause screen reader table reading functions to skip rows or simply stop functioning.
The following code demonstrates the use of
aria-rowindex properties on a table containing a hypothetical class list.
<!-- aria-rowcount tells assistive technologies the actual size of the grid is 463 rows even though only 4 rows are present in the markup. --> <table role="grid" aria-rowcount="463"> aria-label="Student roster for history 101" <thead> <tr aria-rowindex="1"> <th>Last Name</th> <th>First Name</th> <th>E-mail</th> <th>Major</th> <th>Minor</th> <th>Standing</th> </tr> </thead> <tbody> <!-- aria-rowindex tells assistive technologies that this row is row 51 in the grid of 463 rows. --> <tr aria-rowindex="51"> <td>Henderson</td> <td>Alan</td> <td>[email protected]</td> <td>Business</td> <td>Spanish</td> <td>Junior</td> </tr> <!-- aria-rowindex tells assistive technologies that this row is row 52 in the grid of 463 rows. --> <tr aria-rowindex="52"> <td>Henderson</td> <td>Alice</td> <td>[email protected]</td> <td>Engineering</td> <td>none</td> <td>Sophomore</td> </tr> <!-- aria-rowindex tells assistive technologies that this row is row 53 in the grid of 463 rows. --> <tr aria-rowindex="53"> <td>Henderson</td> <td>Andrew</td> <td>[email protected]</td> <td>General Studies</td> <td>none</td> <td>Freshman</td> </tr> </tbody> </table>
When the number of columns represented by the DOM structure is not the total number of columns available for a table, grid, or treegrid,
aria-colcount property is used to communicate the total number of columns available,
and it is accompanied by the
aria-colindex property to identify the column indices of the columns that are present in the DOM.
aria-colcount is specified on the element with the
Its value is an integer equal to the total number of columns available.
If the total number of columns is unknown, a value of
-1 may be specified.
Using a value of
-1 indicates that more columns are available to include in the DOM without specifying the size of the available supply.
aria-colcount is used on a
a value for
aria-colindex property is either specified on each of its descendant rows or on every cell in each descendant row, depending on whether the columns are contiguous as described below.
The value of
aria-colindex is an integer that is:
WARNING! Missing or inconsistent values of
aria-colindex could have devastating effects on assistive technology behavior.
For example, specifying an invalid value for
aria-colindex or setting it on some but not all cells in a row, could cause screen reader table reading functions to skip cells or simply stop functioning.
aria-colindexWhen Column Indicies Are Contiguous
When all the cells in a row have column index numbers that are consecutive integers,
aria-colindex can be set on the row element with a value equal to the index number of the first column in the set.
Browsers will then compute a column number for each cell in the row.
The following code shows a grid with 16 columns, of which columns 2 through 5 are displayed to the user.
Because the set of columns is contiguous,
aria-colindex can be placed on each row.
<div role="grid" aria-colcount="16"> <div role="rowgroup"> <div role="row" aria-colindex="2"> <span role="columnheader">First Name</span> <span role="columnheader">Last Name</span> <span role="columnheader">Company</span> <span role="columnheader">Address</span> </div> </div> <div role="rowgroup"> <div role="row" aria-colindex="2"> <span role="gridcell">Fred</span> <span role="gridcell">Jackson</span> <span role="gridcell">Acme, Inc.</span> <span role="gridcell">123 Broad St.</span> </div> <div role="row" aria-colindex="2"> <span role="gridcell">Sara</span> <span role="gridcell">James</span> <span role="gridcell">Acme, Inc.</span> <span role="gridcell">123 Broad St.</span> </div> … </div> </div>
aria-colindexWhen Column Indicies Are Not Contiguous
When the cells in a row have column index numbers that are not consecutive integers,
aria-colindex needs to be set on each cell in the row.
The following example shows a grid for an online grade book where the first two columns contain a student name and subsequent columns contain scores.
In this example, the first two columns with the student name are shown, but the score columns have been scrolled to show columns 10 through 13.
Columns 3 through 9 are not visible so are not in the DOM.
<table role="grid" aria-rowcount="463" aria-colcount="13"> aria-label="Student grades for history 101" <!-- aria-rowcount and aria-colcount tell assistive technologies the actual size of the grid is 463 rows by 13 columns, which is not the number rows and columns found in the markup. --> <thead> <tr aria-rowindex="1"> <!-- aria-colindex tells assistive technologies that the following columns represent columns 1 and 2 of the total data set. --> <th aria-colindex="1">Last Name</th> <th aria-colindex="2">First Name</th> <!-- aria-colindex tells users of assistive technologies that the following columns represent columns 10, 11, 12, and 13 of the overall data set of grades. --> <th aria-colindex="10">Homework 4</th> <th aria-colindex="11">Quiz 2</th> <th aria-colindex="12">Homework 5</th> <th aria-colindex="13">Homework 6</th> </tr> </thead> <tbody> <tr aria-rowindex="50"> <!-- every cell needs to define the aria-colindex attribute --> <td aria-colindex="1">Henderson</td> <td aria-colindex="2">Alan</td> <td aria-colindex="10">8</td> <td aria-colindex="11">25</td> <td aria-colindex="12">9</td> <td aria-colindex="13">9</td> </tr> <tr aria-rowindex="51"> <td aria-colindex="1">Henderson</td> <td aria-colindex="2">Alice</td> <td aria-colindex="10">10</td> <td aria-colindex="11">27</td> <td aria-colindex="12">10</td> <td aria-colindex="13">8</td> </tr> <tr aria-rowindex="52"> <td aria-colindex="1">Henderson</td> <td aria-colindex="2">Andrew</td> <td aria-colindex="10">9</td> <td aria-colindex="11">0</td> <td aria-colindex="12">29</td> <td aria-colindex="13">8</td> </tr> </tbody> </table>
For tables, grids, and treegrids created using elements other than HTML
row and column spans are defined with the
The value of
aria-colspan is an integer that is:
The value of
aria-rowspan is an integer that is:
The following example grid has a two row header. The first two columns have headers that span both rows of the header. The subsequent 6 columns are grouped into 3 pairs with headers in the first row that each span two columns.
<div role="grid" aria-rowcount="463"> aria-label="Student grades for history 101" <div role="rowgroup"> <div role="row" aria-rowindex="1"> <!-- aria-rowspan and aria-colspan provide assistive technologies with the correct data cell header information when header cells span more than one row or column. --> <span role="columnheader" aria-rowspan="2">Last Name</span> <span role="columnheader" aria-rowspan="2">First Name</span> <span role="columnheader" aria-colspan="2">Test 1</span> <span role="columnheader" aria-colspan="2">Test 2</span> <span role="columnheader" aria-colspan="2">Final</span> </div> <div role="row" aria-rowindex="2"> <span role="columnheader">Score</span> <span role="columnheader">Grade</span> <span role="columnheader">Score</span> <span role="columnheader">Grade</span> <span role="columnheader">Total</span> <span role="columnheader">Grade</span> </div> </div> <div role="rowgroup"> <div role="row" aria-rowindex="50"> <span role="cell">Henderson</span> <span role="cell">Alan</span> <span role="cell">89</span> <span role="cell">B+</span> <span role="cell">72</span> <span role="cell">C</span> <span role="cell">161</span> <span role="cell">B-</span> </div> <div role="row" aria-rowindex="51"> <span role="cell">Henderson</span> <span role="cell">Alice</span> <span role="cell">94</span> <span role="cell">A</span> <span role="cell">86</span> <span role="cell">B</span> <span role="cell">180</span> <span role="cell">A-</span> </div> <div role="row" aria-rowindex="52"> <span role="cell">Henderson</span> <span role="cell">Andrew</span> <span role="cell">82</span> <span role="cell">B-</span> <span role="cell">95</span> <span role="cell">A</span> <span role="cell">177</span> <span role="cell">B+</span> </div> </div> </div>
Note: When using HTML
use the native semantics of the
td elements to define row and column spans
by using the
When rows or columns are sorted, the
aria-sort property can be applied to a column or row header to indicate the sorting method.
The following table describes allowed values for
||Data are sorted in ascending order.|
||Data are sorted in descending order.|
||Data are sorted by an algorithm other than ascending or descending.|
||Default (no sort applied).|
It is important to note that ARIA does not provide a way to indicate levels of sort for data sets that have multiple sort keys.
Thus, there is limited value to applying
aria-sort with a value other than
none to more than one column or row.
The following example grid uses
aria-sort to indicate the rows are sorted from the highest "Quiz 2" score to the lowest "Quiz 2" score.
<table role="grid" aria-rowcount="463" aria-colcount="13" aria-label="Student grades for history 101"> <thead> <tr aria-colindex="10" aria-rowindex="1"> <th>Homework 4</th> <!-- aria-sort indicates the column with the heading "Quiz 2" has been used to sort the rows of the grid. --> <th aria-sort="descending">Quiz 2</th> <th>Homework 5</th> <th>Homework 6</th> </tr> </thead> <tbody> <tr aria-colindex="10" aria-rowindex="50"> <td>8</td> <td>30</td> <td>9</td> <td>9</td> </tr> <tr aria-colindex="10" aria-rowindex="51"> <td>10</td> <td>29</td> <td>10</td> <td>8</td> </tr> <tr aria-colindex="10" aria-rowindex="52"> <td>9</td> <td>9</td> <td>27</td> <td>6</td> </tr> <tr aria-colindex="10" aria-rowindex="53"> <td>9</td> <td>10</td> <td>26</td> <td>8</td> </tr> <tr aria-colindex="10" aria-rowindex="54"> <td>9</td> <td>7</td> <td>24</td> <td>6</td> </tr> </tbody> </table>
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
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
, which serves as a synonym for
For example, consider a tabs widget built using an HTML
<ul role="tablist"> <li role="presentation"> <a role="tab" href="#">Tab 1</a> </li> <li role="presentation"> <a role="tab" href="#">Tab 2</a> </li> <li role="presentation"> <a role="tab" href="#">Tab 3</a> </li> </ul>
Because the list is declared to be a tablist, the list items are not in a list context. It
could confuse users if an assistive technology were to render those list items. Applying role
presentation to the
li elements tells browsers to leave those
elements out of their accessibility tree. Assistive technologies will thus be unaware of the
list item elements and see the tab elements as immediate children of the tablist.
Three common uses of role
role="presentation" is specified on an element, if a
condition that requires a browser to ignore the
does not exist, it has the following three effects.
display: noneor has
presentationis applied to a
olelement, each child
lielement inherits the
presentationrole because ARIA requires the
listitemelements to have the parent
listelement. So, the
lielements are not exposed to assistive technologies, but elements contained inside of those
lielements, including nested lists, are visible to assistive technologies.
presentationis applied to a
tableelement, the descendant
tdelements inherit role
presentationand are thus not exposed to assistive technologies. But, elements inside of the
tdelements, including nested tables, are exposed to assistive technologies.
presentationto be Ignored
role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:
<ul role="presentation"> <li>Date of birth:</li> <li>January 1, 3456</li> </ul>
when parsed by a browser, is equivalent to the following from the perspective of a screen reader or other assistive technology that relies on the browser's accessibility tree:
<div>Date of birth:</div> <div>January 1, 3456</div>
There are some types of user interface components that, when represented in a platform
accessibility API, can only contain text. For example, accessibility APIs do not have a way of
representing semantic elements contained in a button. To deal with this limitation, WAI-ARIA
requires browsers to automatically apply role
presentation to all descendant
elements of any element with a role that cannot support semantic children.
The roles that require all children to be presentational are:
For instance, consider the following tab element, which contains a heading.
<li role="tab"><h3>Title of My Tab</h3></li>
Because WAI-ARIA requires descendants of tab to be presentational, the following code is equivalent.
<li role="tab"><h3 role="presentation">Title of My Tab</h3></li>
And, from the perspective of anyone using a technology that relies on an accessibility API, such as a screen reader, the heading does not exist since the previous code is equivalent to the following.
<li role="tab">Title of My Tab</li>
section about role
for a detailed explanation of what it does.
Browser and Assistive Technology Supportsection of
Read Me First
Report Issuepage in the Github repository
Related Issueslisted in the Github project for the example
Design Patternsection that applies to the example
While WAI-ARIA Authoring Practices 1.1 is the work of the entire Authoring Practices Task Force and also benefits from many people throughout the open source community who both contribute significant work and provide valuable feedback, special thanks goes to the following people who provided distinctly large portions of the content and code in version 1.1.
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.