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.

There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. Testing code based on this example with assistive technologies is essential before considering use in production systems.
The ARIA and Assistive Technologies Project is developing measurements of assistive technology support for APG examples.
Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

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:

Data Grid Examples: Three example implementations of grid that include features relevant to presenting tabular information, such as content editing, sort, and column hiding.
File Directory Treeview using computed properties
File Directory Treeview using declared properties
Navigation Treeview Example

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
re: Treegrids are awesome	They are great for showing a lot of data, like a grid	billy@dangerous.fish
re: Treegrids are awesome	Cool, we've been needing an example and documentation	doris@rufflazydogs.sleep
re: Treegrids are awesome	I hear the Fancytree library is going to align with this example!	someone@please-do-it.company
re: Treegrids are awesome	Sometimes they are more like trees, others are more like grids	mari@beingpractical.com
re: Treegrids are awesome	Cool, when it's a tree, let's keep left/right to collapse/expand	issie@imadeadcatsadly.wascute
re: Treegrids are awesome	I see, sometimes right arrow moves by column	kitten@kittenseason.future

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

CSS: treegrid-1.css
Javascript: treegrid-1.js

HTML Source Code

To copy the following HTML code, please open it in CodePen.