ARIA: treeitem role

A tree is a hierarchical list with parent and child nodes that can expand and collapse. A treeitem is a node in a tree. The root of the tree is tree, but all tree nodes are treeitem elements, even if they themselves have nested treeitem nodes.

An example of a tree is a file system selection user interface: a tree view displaying folders and files. Each folder and file is a treeitem. Folder items, which are treeitem elements, can be expanded to reveal the contents of the folder—which may be files, folders, or both, and are all treeitems—and collapsed, hiding its contents.

In a tree hierarchy, the root node has the role tree. All other nodes, other than the root node, have the role of treeitem, whether or not they have children. A treeitem that is a parent is a parent node. A treeitem that is not a parent is an end node.

Tree items that have children can be expanded or collapsed, showing and hiding their children. A parent node that is expanded so its child nodes are visible is an open node. A parent node that is collapsed so the child nodes are not visible is a closed node.

Each parent node contains or owns an element with role group. A parent node is an expandable collection of treeitem elements. These child nodes are not direct descendants of the parent node: rather, they should be enclosed in an element with the group role.

Each parent node should include the aria-expanded attribute. It is set to false when closed true when open. End nodes should not have the aria-expanded attribute included as the presence of the attribute indicates to assistive technologies that the node is a parent.

Any element with a treeitem role must be nested in, or owned by, an element with role tree. Tree items can be a child of tree, treeitem, or an element with role group that is contained in, or owned by, an element with role tree or treeitem. If a treeitem is not nested within a tree, or nested in a group that is owned by a tree, include the id of the treeitem in the aria-owns attribute value on the owning tree, treeitem or group element.

Trees can be "single-select", allowing users to choose just one treeitem for an action, or "multi-select", where users are able to select more than one treeitem nodes for an action. In both cases, to be keyboard accessible, focus must be managed for all tree descendants.

In single-select trees, only one treeitem can have aria-selected (or aria-checked) set to true. When a single-select tree receives focus, if no treeitem is selected before the tree receives focus, focus is set on the first treeitem. If a treeitem is selected before the tree receives focus, focus is set on the single treeitem that has aria-selected="true" set.

All nodes that are selectable but not selected have either aria-selected or aria-checked set to false. If the tree contains nodes that are not selectable, do not include either aria-selected or aria-checked, as the presence of either attribute indicates to assistive technologies the node is selectable.

No more than one node can be selected at a time unless the tree node has aria-multiselectable="true" set.

When a multi-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first treeitem. If one or more tree items are selected before the tree receives focus, focus is set on the first selected treeitem.

In multi-select trees, all selected tree items have either aria-selected="true" (or aria-checked="true") set. All tree item nodes that are selectable but not currently selected should have aria-selected="false" (or aria-checked="false") set.

Either aria-selected or aria-checked can be used to indicate selection for treeitem elements. Some user interfaces indicate selection with aria-selected in single-select trees and with aria-checked in multi-select trees.

Using both aria-selected and aria-checked in the same tree is strongly discouraged. Don't use both aria-selected and aria-checked on treeitems in a single tree unless the meaning and purpose of aria-selected is different from the meaning and purpose of aria-checked, the meaning and purpose of each state apparent, and the user interface provides a separate method for controlling each state.

In multi-select trees, the selected state should be independent of the focus. For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. The visual design should make it clear which items are selected and which item has focus.

If the complete set of available treeitems is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each treeitem should have aria-level, aria-setsize, and aria-posinset specified.

A treeitem is required to have an accessible name. Generally, that name comes from the treeitem's contents. The accessible name can also be set via aria-label or aria-labelledby.

tree role

The root node for the hierarchical list of parent and child treeitem nodes that can expand and collapse

group role

Identifies a set of treeitem child nodes.

aria-expanded

Set on the root tree and on group nodes that are parents of treeitem nodes, to indicate whether the tree view is expanded (true) or collapsed (false).

aria-selected

Set to true or false, indicates a treeitem is selectable, and whether or not it is currently selected.

aria-checked

Set to true or false, indicates the treeitem can be checked, and whether or not it is currently checked.

For a vertically oriented tree, which is the default orientation:

* Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes

There are two interaction models for multi-select trees: While you can require that users press a modifier key, such as Shift or Control while navigating the list in order to avoid losing selection states, the model that does not require the user to hold a modifier key is recommended.

Recommended multi user select model

The following is how one might mark up a directory listing of web development courses as a tree view:

<div>
  <h3 id="treeLabel">Developer Learning Path</h3>
  <ul role="tree" aria-labelledby="treeLabel">
    <li role="treeitem" aria-expanded="true">
      <span>Web</span>
      <ul role="group">
        <li role="treeitem" aria-expanded="false">
          <span>Languages</span>
          <ul role="group">
            <li role="treeitem" aria-expanded="false">
              <span>HTML</span>
              <ul role="group">
                <li role="treeitem">Document structure</li>
                <li role="treeitem">Head elements</li>
                <li role="treeitem">Semantic elements</li>
                <li role="treeitem">Attributes</li>
                <li role="treeitem">Web forms</li>
              </ul>
            </li>
            <li role="treeitem">CSS</li>
            <li role="treeitem">JavaScript</li>
          </ul>
        </li>
        <li role="treeitem" aria-expanded="false">
          <span>Accessibility</span>
          <ul role="group">
            <li role="treeitem" aria-label="accessibility object model">AOM</li>
            <li role="treeitem">WCAG</li>
            <li role="treeitem">ARIA</li>
          </ul>
        </li>
        <li role="treeitem" aria-expanded="false">
          <span>Web Performance</span>
          <ul role="group">
            <li role="treeitem">Load time</li>
          </ul>
        </li>
        <li role="treeitem">APIs</li>
      </ul>
    </li>
  </ul>
</div>

The above provides the semantics for a tree view, but does not provide any of the interactivity. That must be added in with JavaScript.

If the tree items aren't by default focusable, JavaScript can be used tabIndex="-1" to all the treeitems except the one that should receive focus when the user tabs into the tree which should be set to tabIndex="0".

All the keyboard functionality in Keyboard interactions and all pointer events need to be programmed, including focus management, going up and down the tree, expanding and collapsing parent nodes, and selection management.

If the tree has more than 7 tree items, including type ahead functionality is recommended.