Navigation Treeview 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

Caution!

Before considering use of the Tree View Pattern for site navigation, it is important to understand:

Correct implementation of the tree role requires implementation of complex functionality that is not needed for typical site navigation that is styled to look like a tree with expandable sections.
A pattern more suited for typical site navigation with expandable groups of links is the disclosure pattern.

The below example demonstrates how the Tree View Pattern can be used to build a navigation tree for a set of hierarchically organized web pages. It illustrates navigation of a mythical university web site that is comparable to the navigation illustrated in the Example Disclosure Navigation Menu. As noted above, the disclosure pattern is better suited for most web sites because few sites need the additional keyboard functionality required to support the ARIA tree role.

This example relies on the browser to compute values for aria-setsize, aria-posinset, and aria-level. The ARIA specification for these properties states that browsers can, but are not required to, compute their values. So, some browser and assistive technology combinations may not compute or report correct position and level information if it is not explicitly declared. If testing reveals gaps in support for these properties, override automatic computation by explicitly declaring their values as demonstrated in the example of a File Directory Treeview Example Using Declared Properties.

Similar examples include:

Example

Mythical University

Accessibility Features

Focus Movement After Content Load

An important aspect of designing a navigation tree experience is the behavior of keyboard focus when an item in the tree is activated. If activating a tree item changes content on the page without triggering a browser page load, i.e., works like typical single-page apps, the focus position after the content load significantly affects efficiency for keyboard and assistive technology users. Accessible navigation trees typically implement one of the following two behaviors:

Activating a tree item moves focus to the beginning of the new content, ideally a level one heading with content that matches the name of the tree item that was activated. Focusing on the heading informs screen reader users that navigation is complete and confirms the destination. This behavior is appropriate when common or important use case scenarios assume users want to start interacting with the loaded content after activating the tree item. Note: Keyboard users will need to navigate back to the navigation tree to view other pages. To optimize keyboard efficiency, design a layout that logically locates the tree immediately before the content display area in the Tab sequence.
Activating an item in the tree keeps focus on the activated item in the tree. In this case, the movement of aria-current to the currently focused tree item informs screen reader users that navigation is complete and confirms the destination. This behavior is appropriate when common or important use case scenarios assume users are likely to need to peruse content from multiple nodes in the tree before deciding to interact with the loaded content. Note: screen reader users will need to navigate to the content to read it. In some cases, it might be possible to help screen reader users more quickly perceive the nature of the loaded content without navigating to it by referencing a portion of the content with an aria-describedby attribute on the tree item.

The example on this page illustrates the first technique of focusing the level one heading in the newly loaded content.

Assistive Technology Support Features

Since the tree presents a site navigation system, it is wrapped in a navigation region implemented with a nav element that has an aria-label that matches the label on the tree.
To ensure assistive technology users can identify and easily locate the tree item associated with the currently displayed page:
- The aria-current="page" attribute is applied to the item in the tree associated with the currently displayed page.
- The tree item with aria-current is also the only item with tabindex="0". That is, when tabbing into the tree, focus always lands on the item representing the current page.
- When focus leaves the tree, if the item representing the current page is in a branch that has been collapsed, that branch is expanded to ensure the current page item is both visible and exposed as active to assistive technologies.

Visual design and high contrast features

To help communicate that the arrow keys are available for navigation within the tree, a border is added to the tree container when focus is within the tree.
To support operating system high contrast settings:
- Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused and other elements. Instead of using transparency, the focused element has a thicker border and less padding. When an element receives focus, its border changes from 1 to 3 pixels and padding is reduced by 2 pixels. When an element loses focus, its border changes from 3 pixels to 1 and padding is increased by 2 pixels.
- To ensure the arrow icons used to indicate the expanded or collapsed state have sufficient contrast with the background when high contrast settings invert colors, the CSS currentcolor value for the fill and stroke properties of the SVG polygon element is used to synchronize the color with text content. If specific colors are used to specify the fill and stroke properties, these colors will remain the same in high contrast mode, which could lead to insufficient contrast between the icon and the background or even make the icon invisible if its color matches the high contrast mode background.

Terms Used to Describe Trees

A tree item that can be expanded to reveal child items is called a parent node. It is a closed node when the children are hidden and an open node when it is expanded. An end node does not have any children. For a complete list of terms and definitions, see the Tree View Pattern.

Keyboard Support

Key	Function
`Enter` or `Space`	Performs the default action (e.g. onclick event) for the focused node which is to activate the link, opening its target page. Moves focus to the `h1` element in the newly loaded content. Note: Moving focus is optional behavior. Please read the above accessibility feature sections for details.
`Down arrow`	Moves focus to the next node that is focusable without opening or closing a node. If focus is on the last node, does nothing.
`Up arrow`	Moves focus to the previous node that is focusable without opening or closing a node. If focus is on the first node, does nothing.
`Right Arrow`	When focus is on a closed node, opens the node; focus does not move. When focus is on a open node, moves focus to the first child node. When focus is on an end node, does nothing.
`Left Arrow`	When focus is on an open node, closes the node. When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node. When focus is on a root node that is also either an end node or a closed node, does nothing.
`Home`	Moves focus to first node without opening or closing a node.
`End`	Moves focus to the last node that can be focused without expanding any nodes that are closed.
`a-z, A-Z`	Focus moves to the next node with a name that starts with the typed character. Search wraps to first node if a matching name is not found among the nodes that follow the focused node. Search ignores nodes that are descendants of closed nodes.
`*` (asterisk)	Expands all closed sibling nodes that are at the same level as the focused node. Focus does not move.

Role, Property, State, and Tabindex Attributes

Landmarks

Role	Attribute	Element	Usage
`banner`		`header`	Identifies the common content found at the top of most pages in a website. In a real web page the `header` element would typically not need `role="banner"` attribute to define the landmark, but in this example the `header` element is not in the proper scope of the `body` element to identify is as a banner landmark, so it must be explicitly identified using the role attribute.
`navigation`		`nav`	Identifies the region containing the navigation tree.
	`aria-label="navigation label"`	`nav`	The `aria-label` attribute provides an accessible name for the `navigation` landmark.
`region`		`section`	Identifies the main content region of the page in this example. In a real web page, this region would typically be identified with `main` landmark, but since the page containing this example already has a main landmark, this section is identified using the `region` landmark.
	`aria-labelledby="IDREFs"`	`section`	The `aria-labelledby` attribute provides an accessible name for the `region` landmark by concatenating the website and page titles.
`contentinfo`	`role="contentinfo"`	`footer`	Identifies the common content found at the bottom of most pages in a website. In a real web page the `footer` element would typically not need `role="contentinfo"` attribute to define the landmark, but in this example the `footer` element is not in the proper scope of the `body` element to identify is as a contentinfo landmark, so it must be explicitly identified using the role attribute.

Tree

Role	Attribute	Element	Usage
`tree`		`ul`	Identifies the `ul` element as a `tree` widget. The tree element is not focusable because it implements the practice described in Managing Focus Within Components Using a Roving tabindex.
	`aria-label="Mythical University"`	`ul`	Provides an accessible name for the `tree`.
`treeitem`		`a`	Identifies the element as a `treeitem`.
	`tabindex="-1"`	`a`	Makes the element with the `treeitem` role focusable without including it in the tab sequence of the page. All `treeitem` elements are focusable, but only one is included in the tab sequence.
	`tabindex="0"`	`a`	Includes the element with the `treeitem` role in the tab sequence. Only one `treeitem` in the `tree` has `tabindex="0"`. In this implementation `tabindex="0"` is always on the treeitem with `aria-current="page"`.
	`aria-current="page"`	`a`	Applied to the `treeitem` that is the link to the currently displayed page. The visual indication of the `treeitem` with `aria-current` is a vertical bar to the left of the treeitem label.
	`aria-expanded="false"`	`a`	Applied to `treeitem` elements that are parent nodes, i.e., they have `aria-owns` referencing a `ul` with role `group`. Indicates the parent node is closed, i.e., the descendant elements are not visible. The visual indication of the collapsed state is synchronized by a CSS attribute selector.
	`aria-expanded="true"`	`a`	Applied to `treeitem` elements that are parent nodes, i.e., they have `aria-owns` referencing a `ul` with role `group`. Indicates the parent node is open, i.e., the descendant elements are visible. The visual indication of the expanded state is synchronized by a CSS attribute selector.
	`aria-owns="IDREF"`	`a`	Refers to the element with role `group` that contains the set of child `treeitem` elements that belong to this parent `treeitem`.
`group`		`ul`	Identifies the `ul` element as a container of `treeitem` elements that form a branch of the tree. The group is owned by the element that serves as the parent `treeitem`. Browsers use the grouping to compute `aria-level`, `aria-setsize` and `aria-posinset` values for the nodes contained in the branch.
`none`		`li`	Hides the implicit `listitem` role of the `li` element from assistive technologies. A `listitem` is required to be contained by a `list`, but the containing element is no longer a `list`; it is a `tree` or a `group`. Removing the `listitem` semantic from the browser's accessibility tree eliminates the potential for confusing rendering by assistive technologies.

JavaScript and CSS Source Code

CSS: treeview-navigation.css
Javascript: treeview-navigation.js

HTML Source Code

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