WAI-ARIA: Role=Grid

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.

Description

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.

The grid role does not imply a specific visual, e.g., tabular, presentation. It describes relationships among elements. It may be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application.

The cell elements of a grid have role gridcell. Authors MAY designate a cell as a row or column header by using either the rowheader or columnheader role in lieu of the gridcell role. Authors MUST ensure elements with role gridcell, columnheader, or rowheader are owned by elements with role row, which are in turn owned by an element with role rowgroup, or grid.

To be keyboard accessible, authors SHOULD manage focus of descendants of a grid as described in Managing Focus. When a user is navigating the grid content with a keyboard, authors SHOULD set focus as follows:

• If a gridcell contains a single interactive widget that will not consume arrow key presses when it receives focus, such as a checkbox, button, or link, authors MAY set focus on the interactive element contained in that cell. This allows the contained widget to be directly operable.
• Otherwise, authors SHOULD ensure the element that receives focus is a gridcell, rowheader, or columnheader element.

Authors SHOULD provide a mechanism for changing to an interaction or edit mode that allows users to navigate and interact with content contained inside a focusable cell if that focusable cell contains any of the following:

• a widget that requires arrow keys to operate, e.g., a compensation bobox or radiogroup
• multiple interactive elements
• editable content

For example, if a cell in a spreadsheet contains a combobox or editable text, the Enter key might be used to activate a cell interaction or editing mode when that cell has focus so the directional arrow keys can be used to operate the contained combobox or textbox. Depending on the implementation, pressing Enter again, Tab, Escape, or another key may switch the application back to the grid navigation mode.

Authors MAY use a gridcell to display the result of a formula, which could be editable by the user. In a spreadsheet application, for example, a gridcell may show a value calculated from a formula until the user activates the gridcell for editing when a textbox appears in the gridcell containing the formula in an editable state.

If aria-readonly is set on an element with role grid, user agents MUST propagate the value to all gridcell elements owned by the grid and expose the value in the accessibility API. An author MAY override the propagated value of aria-readonly for an individual gridcell element.

In a grid that provides cell content editing functions, if the content of a focusable gridcell element is not editable, authors MAY set aria-readonly to true on the gridcell element. However, the value of aria-readonly, whether specified for a grid or individual cells, only indicates whether the content contained in cells is editable. It does not represent availability of functions for navigating or manipulating the grid itself.

An unspecified value for aria-readonly does not imply that a grid or a gridcell contains editable content. For example, if a grid presents a collection of elements that are not editable, such as a collection of link elements representing dates in a datepicker, it is not necessary for the author to specify a value for aria-readonly.

Authors MAY indicate that a focusable gridcell is selectable as the object of an action with the aria-selected attribute. If the grid allows multiple gridcells to be selected, the author SHOULD set aria-multiselectable to true on the element with role grid.

Since WAI-ARIA can augment an element of the host language, a grid can reuse the elements and attributes of a native table, such as an HTML table element. For example, if an author applies the grid role to an HTML table element, the author does not need to apply the row and gridcell roles to the descendant HTML tr and td elements because the user agent will automatically make the appropriate translations. When the author is reusing a native host language table element and needs a gridcell element to span multiple rows or columns, the author SHOULD apply the appropriate host language attributes instead of WAI-ARIA aria-rowspan or aria-colspan properties.

Screen Reader Support For Role=Grid

Role=Grid Example

HTML Example

The following example shows a grid with 16 columns, of which columns 2, 3, 4, and 9 are displayed to the user.

<div role="grid" aria-colcount="16">
  <div role="rowgroup">
    <div role="row">
      <span role="columnheader" aria-colindex="2">First Name</span> <span role="columnheader" aria-colindex="3">Last Name</span> <span role="columnheader" aria-colindex="4">Company</span> <span role="columnheader" aria-colindex="9">Phone</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="gridcell" aria-colindex="2">Fred</span> <span role="gridcell" aria-colindex="3">Jackson</span> <span role="gridcell" aria-colindex="4">Acme, Inc.</span> <span role="gridcell" aria-colindex="9">555-1234</span>
    </div>
    <div role="row">
      <span role="gridcell" aria-colindex="2">Sara</span> <span role="gridcell" aria-colindex="3">James</span> <span role="gridcell" aria-colindex="4">Acme, Inc.</span> <span role="gridcell" aria-colindex="9">555-1235</span>
    </div>…
  </div>
</div>

HTML Example 2

<table role="grid">
  <thead>
    <!-- etc -->
  </thead>
  <tbody>
    <!-- etc -->
  </tbody>
</table>

Characteristics

Superclass Role

• composite
• table

Subclass Role

• treegrid

Base Concept

• HTML table

Required Owned Elements

• row
• rowgroup → row

Supported States and Properties

• aria-level
• aria-multiselectable
• aria-readonly

Inherited States and Properties

• aria-activedescendant
• aria-atomic
• aria-busy (state)
• aria-colcount
• aria-controls
• aria-current (state)
• aria-describedby
• aria-details
• aria-disabled (state)
• aria-dropeffect
• aria-errormessage
• aria-expanded (state)
• aria-flowto
• aria-grabbed (state)
• aria-haspopup
• aria-hidden (state)
• aria-invalid (state)
• aria-keyshortcuts
• aria-label
• aria-labelledby
• aria-live
• aria-owns
• aria-relevant
• aria-roledescription
• aria-rowcount

Name From

• author

Accessible Name Required

• True

Semantic HTML

No HTML element equivalent.

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on role=grid.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for role=grid.