ARIA: tree role

A tree widget is a hierarchical list with parent and child nodes that can expand and collapse. Any item in the hierarchy may have child tree items, set with role="treeitem". Tree items that have children can be expanded or collapsed, showing and hiding their children.

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

ARIA tree views are navigated primarily with arrow keys on the keyboard instead of the Tab. This form of navigation is not common for most browser content, though normal and expected for native applications. For this reason, before creating a tree view, consider alternative options to address the functionality you need.

Trees can be "single-select", allowing users to choose just one item for an action, or "multi-select", where users are able to select more than one item for an action. In multi-select trees, the tree has aria-multiselectable set to true. Otherwise, aria-multiselectable is either set to false or the default value of false is implied. In both cases, to be keyboard accessible, focus must be managed for all tree descendants.

In some implementations of single-select tree, the focused item also has a selected state; this is known as "selection follows focus". When a single-select tree receives focus, if none of the tree items are selected before the tree receives focus, focus is set on the first node. If a tree item is selected before the tree receives focus, focus is set on the selected tree item. In single-select trees, aria-selected is set to true for the selected tree items and it is not present on any other tree item in the tree.

In multi-select trees, all selected tree items have aria-selected="true" set and all tree item nodes that are selectable but not currently selected have aria-selected="false" set. Do not includes the aria-selected attribute on tree items that are not selectable.

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 tree item. If one or more tree items are selected before the tree receives focus, focus is set on the first selected node.

In multi-select trees, the selected state is always 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.

In a tree view, the tree node is the root node; it can have child, grandchild, and further descendant treeitem nodes.

Each element serving as a tree node has role treeitem, except for the root tree node which has a role of tree. A tree does not have a parent tree node - it is the root node. If a node is both nested in a tree and has descendant tree items, then it has the role treeitem and the aria-expanded attribute; aria-expanded="false" is set when the node is in a closed state, aria-expanded="true" is set when the node is in an open state.

treeitem nodes can be direct children of the tree root node, nested within a treeitem node, or, optionally nested in a group element, which, when nested in a tree is an expandable collections of treeitem elements.

Do not include aria-expanded on end nodes — those without tree item children — as that would incorrectly describe the node as a parent node to assistive technologies.

All treeitems are contained in or owned by an element with role tree. If there are any tree items that are not direct descendants of the tree in the markup, include aria-owns on the owning tree container to include elements that are not DOM children of the container. These non-child owned elements will appear in the reading order in the sequence they are referenced and after any tree items that are DOM children. Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order.

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

The tree must be provided with an accessible name. Either reference a visible label referenced with aria-labelledby or specify a label with aria-label.

Elements with the role tree have an implicit aria-orientation value of vertical. If the tree element is horizontally oriented, include aria-orientation="horizontal".

role="treeitem"

An item in a tree.

role="group"

An expandable collection of tree items.

aria-labelledby

Identifies the element (or elements) that labels the tree providing the required accessible name when a visible label is present. Otherwise use aria-label.

aria-label

Defines a string value that labels the tree when no visible label is present.

aria-orientation

indicates whether the tree orientation is horizontal or vertical; defaults to vertical if omitted.

aria-multiselectable

When set to true, indicates the user may select more than one tree item from the tree's current selectable descendants.

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

Alternative multi-selection model

The alternative multi-selection model is a modifier key model in which moving focus without holding a modifier key such as Shift or Control unselects all selected nodes except for the focused node: