Tree View Component

Tree view

Tree view is a hierarchical list of items that may have a parent-child relationship where children can be toggled into view by expanding or collapsing their parent item.

file tree outline view folder tree expandable list directory structure hierarchy viewer

Anatomy

Tree view anatomy diagram
1
2
3
4
5
6
7
  1. Parent node: A node that hides and shows child nodes by expanding and collapsing
  2. End node: A node with no children
  3. Nesting level indicator lines: Each line represents a level of nesting depth
  4. Chevron: Toggles a parent node expanded or collapsed and indicates expanded/collapsed state
  5. Leading visual (optional): A visual cue for additional context
  6. Node label: The text label for the node
  7. Trailing visual (optional): Same as a leading visual, but at the end

Interactive Example

File Explorer

src
index.ts

Content

Node label

Node labels should be a succinct title for whatever entity the node represents. For example, a file name. By default, labels are truncated to a single line. However, node labels may be wrapped to multiple lines in cases where the entire label must always be visible.

Single line truncation example

Single line truncation

Multi-line label example

Wrapping node label text

Leading and trailing visuals

Leading and trailing visuals may be used as visual cues that communicate more information about a node. Either all nodes have leading visuals, or no nodes have leading visuals. Leading visuals must be accompanied by a text label.

✓ Do
Consistent leading visuals

Render all nodes with leading visuals and text labels or just with text labels

✗ Don't
Mixed leading visuals

Don't have a tree where only some nodes have leading visuals

Interaction

Keyboard users can expand or collapse nodes without activating them by using the left and right arrow keys. To give cursor users an equivalent experience, there are two click areas:

  • clicking the chevron only expands or collapses the node
  • clicking anywhere else will activate the node
Two click areas

Two click areas - toggle expanded or activate link

One click area

One click area - toggle expanded

States

Default state
Hover state
Selected state
Focused state

Asynchronously loading child nodes

Show placeholder nodes (preferred)

Loading folder
Loading...
Loading...

Accessibility

Keyboard navigation

Key(s) Description
Enter Performs the default action (e.g. onclick event) for the focused node which is to activate the link.
Tab Moves focus outside of the tree view to the next focusable node.
ArrowDown Moves focus to the next node that is focusable without opening or closing a node.
ArrowUp Moves focus to the previous node that is focusable without opening or closing a node.
ArrowRight When focus is on a closed node, opens the node; focus does not move. When focus is on an open node, moves focus to the first child node.
ArrowLeft When focus is on an open node, closes the node. When focus is on a child node, moves focus to its parent node.
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.

Usage

Tree views are only for hierarchical lists

A tree view solves a very specific problem. It's not a multi-purpose tool like an action list or meant for site navigation like a nav list. Tree views are used to communicate a hierarchical list of items, and allow a user to navigate through, select, and take action on one or more items.

Before reaching for a tree view, first make sure that the items represent a list, have a parent-child relationship with more than 1 level of nesting, and that the expand/collapse behavior aids navigation.
✓ Good use cases
  • Navigating the file structure of a repo
  • Navigating a codebase's symbols organized by scope hierarchy
✗ Not appropriate for
  • Global sidebar navigation
  • An FAQ that collapses answers under question headings