Read This First
The code in this example is not intended for production environments.
Before using it for any purpose, read this to understand why.
This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.
- There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. Testing code based on this example with assistive technologies is essential before considering use in production systems.
- The ARIA and Assistive Technologies Project is developing measurements of assistive technology support for APG examples.
- Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.
About This Example
The following examples demonstrate how the grid design pattern can be used to group a collection of interactive widgets into a single tab stop. In these examples, each widget, such as a link or button, is in a separate cell of the grid, and the user can navigate between them with the arrow keys. While navigating with the arrow keys, widgets receive keyboard focus and can be activated with Space or Enter.
In addition to streamlining keyboard interfaces, these grids also convey logical grouping and semantic relationships for the elements they contain. For people who can see the screen, these groupings and relationships are visually communicated with layout and other elements of the visual design. And, by navigating the logical structure that a grid widget provides, screen reader users are also able to easily perceive the same semantic relationships.
The distinguishing feature of
grid that enables it to be used for grouping other widgets is that its cells are containers that preserve the semantics of their descendant elements.
That is, grid cells do not override or suppress the semantics of the elements they contain.
Thus, a link contained inside of a grid cell is presented to a screen reader as a link.
By contrast, a link inside of a menu is presented as a menuitem, and a link inside of a listbox is presented as an option.
Similar examples include:
- 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.
Example 1: Simple List of Links
This example presents a list of links titled "Related Documents" in a grid.
This grid includes three features to enhance perception of the availability of arrow key navigation:
- The focus indicator changes to a dotted blue box.
- When screen size is sufficiently large, A graphic of an arrow keypad appears in the page gutter on the bottom left.
The first time a user moves focus into the grid with Tab, a
NUX(new user experience helper) appears in the page tab sequence immediately following the grid. The NUX explains the meaning of the focus indicator and keypad graphic, and it remains visible until the user closes it.
- This grid is useful in a responsive design. It dynamically adjusts the number of cells per row based on screen size. As the grid structure changes, the arrow key behavior adjusts accordingly.
- Since all of the links are part of a single logical group, repeatedly pressing either Down Arrow or Right Arrow will move focus through all links in different sequences that depend on the visual arrangement.
- The Left Arrow and Up Arrow keys reverse Right Arrow and Down Arrow focus movement, respectively.
- The Home and End keys will move focus to the first and last links, respectively.
- The Page Down and Page Up keys are not supported since scrolling or row skipping functions are not needed with so few rows.
- The links can be activated with the keyboard when focused.
Example 2: Pill List For a List of Message Recipients
Add recipients by typing a string in the "New Recipient Name" field and pressing Enter or activating the "Add" button. See how this grid behaves as the number of elements increases.
- This grid demonstrates that logical rows do not have to be vertically stacked.
- Each logical row has two cells: one containing a recipient name link and one containing the remove icon for that recipient.
- There are multiple logical rows arranged in a line across the screen.
- As the number of recipients grows, new elements wrap to additional lines as needed.
- Down Arrow and Up Arrow move to the next and previous logical row.
- So for example, Down Arrow can move focus from recipient to recipient or from remove icon to remove icon.
- Like in example 1, Right Arrow can move focus to every element from beginning to end and vice versa with the Left Arrow.
- Pressing Enter when focus is in the add recipient input will activate the "Add" button.
- When recipients are added or removed, an off-screen live region informs screen reader users of the result of the action so they do not have to move focus to confirm that the action was completed.
Example 3: Scrollable Search Results
This example demonstrates how a grid can make moving through an infinitely large data set as easy and efficient for keyboard users as it is for mouse users. It presents a hypothetical set of search results for W3C resources about WAI-ARIA.
Search Results for "W3C WAI-ARIA"
- This example shows how a logical row can span multiple physical rows. All three cells for each result are in a row, and that row occupies multiple visual rows on the screen.
- In addition to the navigation keys supported in examples 1 and 2, Page Down and Page Up scroll the grid.
As navigating up or down scrolls the visible set of rows, the
aria-rowindexvalue of the row containing focus informs assistive technologies of the number of that row within the total set of rows.
This implementation of grid allows the following focus movement behaviors to be declared in the HTML.
- Whether to focus a cell or an element inside it when the cell is clicked or a navigation key is pressed:
- The section of the grid pattern on Setting Focus and Navigating Inside Cells describes how to design the focus placement strategy.
- Whether focus can wrap from the last column to the first column in the next row or from the first column to the last column in the previous row when Right Arrow and Left Arrow are pressed:
- This wrapping is expected in all grids except for those presenting tabular, i.e., spreadsheet-like, data. The data grid examples demonstrate grids where focus movement does not wrap at the ends of rows.
- Whether focus can wrap to the first row in the next column or the last row in the previous column when Down Arrow and Up Arrow are pressed:
- The only condition where this wrapping is appropriate is when every cell in the grid belongs to a single logical set. In other words, if presentation of all elements in a single row is logically equivalent to presenting the same elements in an arbitrary number of rows and columns, then it is appropriate for Down Arrow and Up Arrow to behave as if all cells are in a single column. For instance, in example 1, all cells contain a navigation link. That set of six links could be presented in a single row, a single column, or divided into two rows of three or three rows of two; all these presentations would be logically equivalent. Conversely, in example 3, each logical row contains three cells, and it would be bizarre for the focus to move from the last search result link to the organization cell of the first search result when Down Arrow is pressed.
- If a cell has
tabindex="-1", focus is placed on the cell. Otherwise, it is placed on a focusable element inside the cell.
data-wrap-cols="true": When this custom data attribute is on the grid, Right Arrow and Left Arrow move focus from column to column even across row boundaries to the column (cell) in the next or previous row. Setting it
falsewill disable this type of wrapping.
data-wrap-rows="true": When this custom data attribute is on the grid, Down Arrow and Up Arrow move focus from row to row even across column boundaries to the row (cell) in the next or previous column. Setting it
falsewill disable this type of wrapping.
NOTE: The following table describes keyboard commands that move focus among grid cells. In the examples on this page, some cells contain a single focusable widget, and if a cell contains a widget, the cell is not focusable; the widget receives focus instead of the cell. So, when a description says a command moves focus to a cell, the command may either focus the cell or a widget inside the cell.
|Page Down (Example 3)||
|Page Up (Example 3)||
|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.|
Role, Property, State, and Tabindex Attributes
||Identifies the element containing the grid widget. Because focus is managed using roving tabindex, the grid element is not focusable.|
||Refers to the element that labels the grid.|
||Identifies the element containing the content for a single cell.|
||Widgets inside cells||
||span, div, or if present, widget inside cell||