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
The grid
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 id="id-select-your-seat">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 id="1a" tabindex="-1">1A</button>
</td>
<td tabindex="-1">
<button id="1b" tabindex="-1">1B</button>
</td>
<!-- More Columns -->
</tr>
<tr>
<th scope="row">Aisle 2</th>
<td tabindex="-1">
<button id="2a" tabindex="-1">2A</button>
</td>
<td tabindex="-1">
<button id="2b" 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. See ARIA Authoring practices for more details
Cell elements have the role gridcell
, unless they are a row or column header. Then the elements are rowheader
and columnheader
, respectively. Cell elements need to be owned by elements with a row
role. Rows can be grouped using rowgroups
.
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 multiple rows.
States and properties
- aria-level
-
Indicates the hierarchical level of the grid within other structures.
- aria-multiselectable
-
If
aria-multiselectable
is 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-readonly
should 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 the left, right, top and down keys. To activate the interactive component, they will use the return and space keys.
Key | Action |
---|---|
β | Moves focus one cell to the right. If focus is on the right-most cell in the row, focus does not move. |
β | Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move. |
β | Moves focus one cell down. If focus is on the bottom cell in the column, focus does not move. |
β | 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. |
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 id="calendarheader">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 35</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 36</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>
<!-- β¦ Additional Rows β¦ -->
</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 #000;
text-align: right;
color: #767676;
}
tbody td[role="gridcell"] {
color: #000;
}
tbody td[role="gridcell"]:hover, tbody td[role="gridcell"]:focus {
background-color: #f6f6f6; outline: 3px solid blue;
}
JavaScript
var selectables = document.querySelectorAll('table td[role="gridcell"]');
selectables[0].setAttribute('tabindex', 0);
var trs = document.querySelectorAll('table tbody tr'),
row = 0,
col = 0,
maxrow = trs.length - 1,
maxcol = 0;
Array.prototype.forEach.call(trs, function(gridrow, i){
Array.prototype.forEach.call(gridrow.querySelectorAll('td'), function(el, i){
el.dataset.row = row;
el.dataset.col = col;
col = col + 1;
});
if (col>maxcol) { maxcol = col - 1; }
col = 0;
row = row + 1;
});
function moveto(newrow, newcol) {
var tgt = document.querySelector('[data-row="' + newrow + '"][data-col="' + newcol + '"]');
if (tgt && (tgt.getAttribute('role')==='gridcell') ) {
Array.prototype.forEach.call(document.querySelectorAll('[role=gridcell]'), function(el, i){
el.setAttribute('tabindex', '-1');
});
tgt.setAttribute('tabindex', '0');
tgt.focus();
return true;
} else {
return false;
}
}
document.querySelector('table').addEventListener("keydown", function(event) {
switch (event.key) {
case "ArrowRight":
moveto(parseInt(event.target.dataset.row, 10), parseInt(event.target.dataset.col, 10) + 1);
break;
case "ArrowLeft":
moveto(parseInt(event.target.dataset.row, 10), parseInt(event.target.dataset.col, 10) - 1);
break;
case "ArrowDown":
moveto(parseInt(event.target.dataset.row, 10) + 1, parseInt(event.target.dataset.col, 10));
break;
case "ArrowUp":
moveto(parseInt(event.target.dataset.row, 10) - 1, parseInt(event.target.dataset.col, 10));
break;
case "Home":
if (event.ctrlKey) {
var i = 0;
var result;
do {
var j = 0;
var result;
do {
result = moveto(i, j);
j++;
} while (result == false);
i++;
} while (result == false);
} else {
moveto(parseInt(event.target.dataset.row, 10), 0);
}
break;
case "End":
if (event.ctrlKey) {
var i = maxrow;
var result;
do {
var j = maxcol;
do {
result = moveto(i, j);
j--;
} while (result == false);
i--;
} while (result == false);
} else {
moveto(parseInt(event.target.dataset.row, 10), document.querySelector('[data-row="' + event.target.dataset.row + '"]:last-of-type').dataset.col);
}
break;
case "PageUp":
var i = 0;
var result;
do {
result = moveto(i, event.target.dataset.col);
i++;
} while (result == false);
break;
case "PageDown":
var i = maxrow;
var result;
do {
result = moveto(i, event.target.dataset.col);
i--;
} while (result == false);
break;
case "Enter":
alert(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 | Status |
---|---|
Accessible Rich Internet Applications (WAI-ARIA) 1.1 The definition of 'Role Grid' in that specification. |
Recommendation |
WAI-ARIA Authoring Practices 1.2 The definition of 'Role Grid' in that specification. |
Working Draft |