Skip to content

Treegrid Email Inbox Example

Treegrid Email Inbox Example

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.

About This Example

The following example demonstrates how the Treegrid Pattern can be used to make an interactive tree that enables users to both navigate the hierarchical structure of email conversations and also navigate elements that describe each email, such as subject and sender.

Similar examples include:

Example Usage Options

This example demonstrates three different ways of implementing the keyboard navigation specified in the treegrid pattern. The following links change the behavior of the navigation keys:

  • Rows are focused first, but cells can be focused:
    Useful when the desired experience is for the treegrid to act primarily like a tree where each row is treated like a node in a tree, but it is still possible for users to navigate across the cells in a row.
  • Cells are focused first, but rows can be focused:
    Useful when the desired experience is for the treegrid to act primarily like a grid where arrow keys move among cells, but it is still possible for users to focus a row and then start navigating the structure like a tree.
  • Only cells can be focused:
    Useful when the desired experience is that the treegrid act primarily like a grid and there is no need to focus complete rows.

Note: A row-only option is not provided. A treegrid where cells cannot be focused would be implemented as a tree view. A treeview that has columns in its visual presentation may be appropriate when all the following conditions are present:

  • Columns are guaranteed to fit horizontally (no horizontal scrolling necessary).
  • Columns are merely for attractive presentation; there is no need to navigate them individually.
  • A screen reader user can easily understand the UI when all information in a row is announced as a single string without any separation.

Example

Subject Summary Email
Treegrids are awesome Want to learn how to use them? aaron@thegoogle.rocks
re: Treegrids are awesome I agree with you, they are the shizzle joe@blahblahblah.blahblah

Keyboard Support

NOTE: The following table includes descriptions of how keyboard commands move focus among cells and rows in the treegrid implementation on this page. In the example 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 keyboard command description says a command moves focus to a cell, the command may either focus the cell or a widget inside the cell.

Key Function
Right Arrow
  • If a row is focused, and it is collapsed, expands the current row.
  • If a row is focused, and it is expanded, focuses the first cell in the row.
  • If a cell is focused, moves one cell to the right.
  • If focus is on the right most cell, focus does not move.
Left Arrow
  • If a row is focused, and it is expanded, collapses the current row.
  • If a row is focused, and it is collapsed, moves to the parent row (if there is one).
  • If a cell in the first column is focused, focuses the row.
  • If a cell in a different column is focused, moves focus one cell to the left.
Down Arrow
  • Moves focus one row or one cell down, depending on whether a row or cell is currently focused.
  • If focus is on the bottom row, focus does not move.
Up Arrow
  • Moves focus one row or one cell up, depending on whether a row or cell is currently focused.
  • If focus is on the top row, focus does not move.
Tab
  • Moves focus to the next interactive widget in the current row.
  • If there are no more interactive widgets in the current row, moves focus out of the treegrid.
Shift + Tab
  • If a cell is focused, moves focus to the previous interactive widget in the current row.
  • If a row is focused, moves focus out of the treegrid.
Home
  • If a row is focused, moves to the first row.
  • If a cell is focused, moves focus to the first cell in the row containing focus.
End
  • If a row is focused, moves to the last row.
  • If a cell is focused, moves focus to the last cell in the row containing focus.
Control + Home
  • If a row has focus, moves focus to the first row.
  • If a cell has focus, moves focus to the cell in the first row in the same column as the cell that had focus.
Control + End
  • If a row has focus, moves focus to the last row.
  • If a cell has focus, moves focus to the cell in the last row in the same column as the cell that had focus.
Enter
  • Performs default action associated with row or cell that has focus, e.g. opens message or navigate to link.
  • If focus is on the cell with the expand/collapse button, and there is no other action, will toggle expansion of the current row.

Role, Property, State, and Tabindex Attributes

Role Attribute Element Usage
treegrid table Identifies the element as a treegrid.
aria-label="Inbox" table Provides an accessible name for the treegrid.
row tr
  • Identifies the element as a row.
  • The row role is not an implicit semantic for the tr element when in a treegrid.
tabindex="-1" tr or td
  • Makes the element focusable without including it in the tab sequence of the page.
  • All row and gridcell elements are focusable, but only one is included in the tab sequence.
tabindex="0" tr or td
  • Includes the element in the tab sequence.
  • Only one row or gridcell in the treegrid has tabindex="0".
  • In this implementation, the first row in the treegrid is included in the tab sequence when the page loads.
  • When the user moves focus in the treegrid, the element included in the tab sequence changes to the element with focus as described in the practice for Managing Focus Within Components Using a Roving tabindex.
aria-expanded="false" tr or td
  • Applied only to parent row or first cell of parent row, i.e., next set of rows are responses to the message in this row
  • Indicates the parent row is closed, i.e., the descendant rows are not visible.
  • The visual indication of the collapsed state is synchronized by a CSS attribute selector.
  • When the treegrid is configured to support focus on rows aria-expanded is on the tr elements, but when the treegrid is configured to support focus on cells only, aria-expanded is on the first td element contained in each row.
aria-expanded="true" tr or td
  • Applied only to parent rows or the first cell in parent rows, i.e., next set of rows are responses to the message in this row
  • Indicates the parent row is open, i.e., the descendant rows are visible.
  • The visual indication of the open state is synchronized by a CSS attribute selector.
  • When the treegrid is configured to support focus on rows aria-expanded is on the tr elements, but when the treegrid is configured to support focus on cells only, aria-expanded is on the first td element contained in each row.
aria-level="number" tr
  • Defines the level of the row in the hierarchical treegrid structure.
  • Counting is one-based.
  • Root rows have aria-level=“1”.
aria-setsize="number" tr Defines the number of rows in the set of rows that are in the same branch and at the same level within the hierarchy.
aria-posinset="number" tr
  • Defines the position of the row within the set of other rows that are in the same branch and at the same level within the hierarchy.
  • Counting is one-based, not zero-based.
gridcell td
  • Identifies the element as a gridcell.
  • The gridcell role is not an implicit semantic for the td element when in a treegrid.

NOTE: Due to an error in the ARIA 1.1 specification, the aria-posinset and aria-setsize properties are not supported on row elements. This is being corrected in ARIA 1.2. Consequently, when validating the HTML in this example, errors are generated.

JavaScript and CSS Source Code

HTML Source Code

Back to Top

This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.