ARIA: grid role
The grid role is for a widget that contains one or more rows of cells. The position of each cell is significant and can be focused using keyboard input.
Description
Thegrid role is a composite widget containing a collection of one or more rows with one or more cells where some or all cells in the grid are focusable by using methods of two-dimensional navigation, such as directional arrow keys.
<table role="grid" aria-labelledby="id-select-your-seat"> <caption> Select your seat </caption> <tbody role="presentation"> <tr role="presentation"> <td></td> <th>Row A</th> <th>Row B</th> </tr> <tr> <th scope="row">Aisle 1</th> <td tabindex="0"> <button tabindex="-1">1A</button> </td> <td tabindex="-1"> <button tabindex="-1">1B</button> </td> <!-- More Columns --> </tr> <tr> <th scope="row">Aisle 2</th> <td tabindex="-1"> <button tabindex="-1">2A</button> </td> <td tabindex="-1"> <button tabindex="-1">2B</button> </td> <!-- More Columns --> </tr> </tbody></table>A grid widget contains one or more rows with one or more cells of thematically related interactive content. While it does not imply a specific visual presentation, it implies a relationship among elements. Uses 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. SeeARIA Authoring Practices Guide for more details.
Cell elements have the rolegridcell, unless they are a row or column header, in which case, the elements arerowheader andcolumnheader, respectively. Cell elements need to be owned by elements with arow role. Rows can be grouped using therowgroup role.
If the grid is used as an interactive widget,keyboard interactions need to be implemented.
Associated ARIA roles, states, and properties
Roles
- treegrid (subclass)
If a grid has columns that can expanded or collapsed, a treegrid can be used.
- row
A row inside the grid.
- rowgroup
A group containing one or multiplerows.
States and properties
- aria-level
Indicates the hierarchical level of the grid within other structures.
- aria-multiselectable
If
aria-multiselectableis set totrue, multiple items in the grid can be selected. The default value isfalse.- aria-readonly
If the user can navigate the grid but not change the value or values of the grid, the
aria-readonlyshould be set totrue. The default value isfalse.
Note:For many use cases, an HTML<table> element is sufficient as it and the various table elements already include many ARIA roles.
Keyboard interactions
When a keyboard user encounters a grid, they navigate the rows and columns using theleft,right,top anddown keys. To activate the interactive component, they will use thereturn andspace keys.
| Key | Action |
|---|---|
| → | Moves focus one cell to the right. Optionally (layout grids), 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. |
| ← | Moves focus one cell to the left. Optionally (layout grids), 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. |
| ↓ | Moves focus one cell down. Optionally (layout grids), 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. |
| ↑ | Moves focus one cell up. Optionally (layout grids), 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 | 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. |
| ctrl +Home | Moves focus to the first cell in the first row. |
| ctrl +End | Moves focus to the last cell in the last row. |
If cells, rows, or columns can be selected, the following key combination are commonly used:
| Key combination | Action |
|---|---|
| ctrl +Space | Select the column that contains the focus. |
| shift +Space | Selects the row that contains the focus. If the grid includes a column with checkboxes to select rows, this key combination can be used to check that box even if the focus is not on the checkbox. |
| ctrl +A | Selects all cells. |
| shift +→ | Extends selection one cell to the right. |
| shift +← | Extends selection one cell to the left. |
| shift +↓ | Extends selection one cell down. |
| shift +↑ | Extends selection one cell up. |
Examples
Calendar example
HTML
<table role="grid" aria-labelledby="calendarheader"> <caption> September 2018 </caption> <thead role="rowgroup"> <tr role="row"> <td></td> <th role="columnheader" aria-label="Sunday">S</th> <th role="columnheader" aria-label="Monday">M</th> <th role="columnheader" aria-label="Tuesday">T</th> <th role="columnheader" aria-label="Wednesday">W</th> <th role="columnheader" aria-label="Thursday">T</th> <th role="columnheader" aria-label="Friday">F</th> <th role="columnheader" aria-label="Saturday">S</th> </tr> </thead> <tbody role="rowgroup"> <tr role="row"> <th scope="row" role="rowheader">Week 1</th> <td>26</td> <td>27</td> <td>28</td> <td>29</td> <td>30</td> <td>31</td> <td role="gridcell" tabindex="-1">1</td> </tr> <tr role="row"> <th scope="row" role="rowheader">Week 2</th> <td role="gridcell" tabindex="-1">2</td> <td role="gridcell" tabindex="-1">3</td> <td role="gridcell" tabindex="-1">4</td> <td role="gridcell" tabindex="-1">5</td> <td role="gridcell" tabindex="-1">6</td> <td role="gridcell" tabindex="-1">7</td> <td role="gridcell" tabindex="-1">8</td> </tr> <tr role="row"> <th scope="row" role="rowheader">Week 3</th> <td role="gridcell" tabindex="-1">9</td> <td role="gridcell" tabindex="-1">10</td> <td role="gridcell" tabindex="-1">11</td> <td role="gridcell" tabindex="-1">12</td> <td role="gridcell" tabindex="-1">13</td> <td role="gridcell" tabindex="-1">14</td> <td role="gridcell" tabindex="-1">15</td> </tr> <tr role="row"> <th scope="row" role="rowheader">Week 4</th> <td role="gridcell" tabindex="-1">16</td> <td role="gridcell" tabindex="-1">17</td> <td role="gridcell" tabindex="-1">18</td> <td role="gridcell" tabindex="-1">19</td> <td role="gridcell" tabindex="-1">20</td> <td role="gridcell" tabindex="-1">21</td> <td role="gridcell" tabindex="-1">22</td> </tr> <tr role="row"> <th scope="row" role="rowheader">Week 5</th> <td role="gridcell" tabindex="-1">23</td> <td role="gridcell" tabindex="-1">24</td> <td role="gridcell" tabindex="-1">25</td> <td role="gridcell" tabindex="-1">26</td> <td role="gridcell" tabindex="-1">27</td> <td role="gridcell" tabindex="-1">28</td> <td role="gridcell" tabindex="-1">29</td> </tr> <tr role="row"> <th scope="row" role="rowheader">Week 6</th> <td role="gridcell" tabindex="-1">30</td> <td>1</td> <td>2</td> <td>3</td> <td>4</td> <td>5</td> <td>6</td> </tr> </tbody></table>CSS
table { margin: 0; border-collapse: collapse; font-variant-numeric: tabular-nums;}tbody th,tbody td { padding: 5px;}tbody td { border: 1px solid black; text-align: right; color: #767676;}tbody td[role="gridcell"] { color: black;}tbody td[role="gridcell"]:hover,tbody td[role="gridcell"]:focus { background-color: #f6f6f6; outline: 3px solid blue;}JavaScript
const selectables = document.querySelectorAll('table td[role="gridcell"]');selectables[0].setAttribute("tabindex", 0);const trs = document.querySelectorAll("table tbody tr");let rowIndex = 0;let colIndex = 0;let maxRow = trs.length - 1;let maxCol = 0;trs.forEach((row) => { row.querySelectorAll("td").forEach((el) => { el.dataset.row = rowIndex; el.dataset.col = colIndex; colIndex++; }); if (colIndex > maxCol) { maxCol = colIndex - 1; } colIndex = 0; rowIndex++;});function moveTo(newRow, newCol) { const tgt = document.querySelector( `[data-row="${newRow}"][data-col="${newCol}"]`, ); if (tgt?.getAttribute("role") !== "gridcell") { return false; } document.querySelectorAll("[role=gridcell]").forEach((el) => { el.setAttribute("tabindex", "-1"); }); tgt.setAttribute("tabindex", "0"); tgt.focus(); return true;}document.querySelector("table").addEventListener("keydown", (event) => { const col = parseInt(event.target.dataset.col, 10); const row = parseInt(event.target.dataset.row, 10); switch (event.key) { case "ArrowRight": { const newRow = col === 6 ? row + 1 : row; const newCol = col === 6 ? 0 : col + 1; moveTo(newRow, newCol); break; } case "ArrowLeft": { const newRow = col === 0 ? row - 1 : row; const newCol = col === 0 ? 6 : col - 1; moveTo(newRow, newCol); break; } case "ArrowDown": moveTo(row + 1, col); break; case "ArrowUp": moveTo(row - 1, col); break; case "Home": { if (event.ctrlKey) { let i = 0; let result; do { let j = 0; do { result = moveTo(i, j); j++; } while (!result); i++; } while (!result); } else { moveTo(row, 0); } break; } case "End": { if (event.ctrlKey) { let i = maxRow; let result; do { let j = maxCol; do { result = moveTo(i, j); j--; } while (!result); i--; } while (!result); } else { moveTo( row, document.querySelector( `[data-row="${event.target.dataset.row}"]:last-of-type`, ).dataset.col, ); } break; } case "PageUp": { let i = 0; let result; do { result = moveTo(i, col); i++; } while (!result); break; } case "PageDown": { let i = maxRow; let result; do { result = moveTo(i, col); i--; } while (!result); break; } case "Enter": { console.log(event.target.textContent); break; } } event.preventDefault();});More examples
Accessibility concerns
Even if the keyboard use is properly implemented, some users might not be aware that they have to use the arrow keys. Make sure that the functionality and interaction needed can be best achieved using the grid role.
Specifications
| Specification |
|---|
| Accessible Rich Internet Applications (WAI-ARIA) # grid |