ARIA: grid role - Accessibility 编辑

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.

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

Description

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 to true, multiple items in the grid can be selected. The default value is false.

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 to true. The default value is false.

For many use cases, an HTML table element is sufficient as it and its 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.

If cells, rows, or columns can be selected, the following key combination are commonly used:

Examples

Calendar example

HTML

<table role="grid" aria-labelledby="calendarheader" aria-readonly=true>
  <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>
    <tr role="row">
      <th scope="row" role="rowheader">Week 37</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 38</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 39</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 40</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

body {
  margin: 2rem;
  font-family: "Helvetica Neue", sans-serif;
}

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();
});

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

• Data Grid Examples
• Layout Grids Examples
• W3C/WAI Tutorial: Tables

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

Screen reader support

TBD

See also

• ARIA composite role
• ARIA table role
• ARIA treegrid role
• ARIA row role
• ARIA rowgroup role
• ARIA: gridcell role
• ARIA: rowheader role
• ARIA: columnheader role
• HTML table element
• aria-level
• aria-multiselectable
• aria-readonly