Skip to content

Navigation Treeview Example

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.

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

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:

  1. 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.
  2. 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 an 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
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

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/.