Components

Content tree

Uses a node and tree structure to combine and organize data. Content tree provides an expandable and selectable tree with configurable options to include elements such as identifiers, highlighted values, chevrons, text, icons, and dividers.

Overview

  • Available since: New York
  • A11Y: WCAG 2.1 AA

Content tree displays hierarchical data in a tree-like structure. It helps users navigate through complex information by expanding and collapsing nodes.

ServiceNow link
Content tree code documentation

UIB and developer guidance

Figma link
Content tree Figma component

Horizon components and styles library

Loading playground

When to use

Use content tree when you're dealing with structured, hierarchical data like file systems, organizational charts, or nested categories. It's great for contexts where users need to explore or understand the relationships between different levels of information.

When not to use

Don't use content tree if your data isn't hierarchical. If your information can be presented in a flat list or another simpler format, go with that instead.

Anatomy

Learn about the individual parts of content tree.

Content tree

anatomy of a content tree
  1. Root node: Topmost node in the tree structure
  2. Parent node: Node (excluding the root node) that connects to only one other node
  3. Child node: Subnode of any given parent node
  4. Leaf node: Node with no child nodes; it's the lowest node in the entire hierarchy

Note: The data set determines what nodes get passed into the content tree.

Content tree node

anatomy of a content tree node
  1. Expand or collapse control (optional): Opens and closes a node with attached child nodes
  2. Identifier (optional): Visual indicator in front of the label that provides additional context; indicators make nodes easily identifiable and scannable, which is helpful when a content tree contains multiple node types
  3. Label: Text description of the node
  4. Subcomponent area (optional): Can be an icon, badge, or presence indicator; subcomponents can either trigger a contextual action or behave as a visual indicator
  5. Highlighted value (optional): Styled value that communicates priority or status information
  6. Divider (optional): Line that creates a visual relationship between elements; the divider also improves the readability of the content tree

Subcomponent

See usage guidance for avatar

See usage guidance for highlighted value

See usage guidance for accordion

Usage

Use a content tree to categorize nodes in a logical hierarchy, with easy-to-read labels and familiar icons. Keep the hierarchy shallow to allow users to scan the information quickly and get to the information they need. You can simplify navigation in large hierarchies by allowing users to collapse and expand parent nodes. Drag and drop capabilities allow users to reorganize the content tree.

content tree used to help the user navigate their inbox on the left sidebar

Variants

Learn about content tree and find out how to use it in your design.

Sizes

The data set and your page structure determine the height of the content tree. Be sure to leave enough space in your design to limit the amount of horizontal scrolling.

Node sizes

Although the content tree doesn't have predetermined sizes, the nodes within a content tree have 2 different sizes. These sizes affect the size of the chevron, label, and elements in the node. Choose a size that best fits your individual use case.

Small

Medium

Configurations

Learn how to customize content tree by configuring the available properties.

Text

Use text to clearly and succinctly describe the node.

text label in a content tree node

Identifiers

Identifiers provide additional visual context to a specific text label. You can use either icons or avatars as identifiers.

Icons

An icon can supplement the label and provide a visual cue.

an outlined user icon that supplements the node text label

However, be cautious when using repetitive identifiers because they may cause visual noise. Always evaluate if identifiers are meaningful and necessary for users before using them.

Avatars

Instead of using an icon, you can use any type of avatar to identify an individual.

an avatar that supplements the node text label

Avatars are especially helpful when you want to build org charts using a content tree.

avatars in a content tree that shows an org chart

Highlighted values

highlighted values to the right of the content tree node label

The area dedicated for a highlighted value may require an adjustment if the longest highlighted value label exceeds the default width. In this example, you would have to adjust the width to fit the 'Connecting' label.

When you use a highlighted value with an actionable icon or icon, the highlighted value will appear to the right.

highlighted value in a node to the right of an info icon

Actions

Use an actionable node to trigger an event.

actionable blue text and icon in a content tree node

When an action is embedded in a node, the identifier and label appear in the actionable color.

Subcomponent selection

There are 3 types of subcomponents that can appear to the right of the label: an icon, a presence icon, or a badge. There is no limit to how many of these you can include next to the label. However, too many may visually overload the user. To reduce cognitive overload, you can also make the subcomponents appear only after the user hovers or focuses on a specific node.

presence icon in a node next to a more action menu and lock icon

In this example, the presence icon shows that the servers are online.

Presence indicators and badges don't have any actions and only display a status. However, icons can indicate a status or contain an action. If an icon is actionable, it always appears to the right of any status elements.

badge icon in a node next to the more action menu and a lock icon

In this example, a badge appears to show the total number of templates available.

Expand or collapse control

There are 3 options for the expand or collapse control trigger: chevron, caret and "plus or minus". It's recommended that you use the same type within a display or throughout a product to create a visually consistent experience.

Trigger Type Example
Chevron (default) now-content-tree
Caret now-content-tree
Plus or Minus now-content-tree

Dividers

You can also add divider to the content tree to help visually break up the nodes. Dividers are optional and aren't part of the default configuration.

a content tree with and without divider lines to visually separate nodes

Design recommendation

Learn how to apply content tree in your design.

content tree using different icon identifiers for all nodes
Do

Use an identifier when the data set contains multiple sets of unique items.

content tree using same user icon identifier for all nodes
Don’t

Using an identifier for known entities introduces more visual noise and doesn't provide clarity.

content tree label and highlighted value identifier contextually close
Do

In this example, the labels have a clear visual relationship with the highlighted values (the elements).

content tree label and highlighted value identifier far apart
Don’t

Avoid filling an entire space with a content tree because the distance between the labels and values makes it difficult to determine the relationship.

Alignment and positioning

The content tree always aligns to the left of its container. When a parent node expands to show the child nodes, the child nodes appear indented from the left to show the visual hierarchy.

UI text guidelines

These are some recommendations for using text within content tree:

  • If content tree node is closed by default, the label you use should help the person understand what will show if they open it 
  • Consider the hierarchy when organizing items in a content tree—based on the labels, the relationship between the items should be clear

 

Behavior

Learn how content tree behaves when the display changes or a user interacts with the component.

States

Content tree has the following states: default, hover, selected, and disabled.

State Example
Default now-content-tree
Hover now-content-tree
Selected now-content-tree
Disabled now-content-tree

Responsive behaviors

Learn how content tree responds to changes in a container or display.

Lazy loading

If you are using a large set of data in your content tree, you can use the lazy loading behavior to load data on demand. This functionality can be applied to any set of data at any level.
When using lazy loading, determine what data to load first by considering how a user will engage with the data set. For example, if you expect a user to identify the parent before drilling into a child node, you can load batches of parent nodes first. Then load batches of parent nodes until the list is complete.
A content tree can load child nodes on demand.

content tree with country names as parent nodes

When the user expands a node, this starts the lazy loading process. A loading state appears within the children node area. Collapsing the node will cancel the loading request.

user selects the United States node to open lazy loading of states

Once the process is done, the loading state disappears, and the child nodes appear in its place.

child nodes replace the loading icon and text under parent nodes

If it takes too long to return nodes during a lazy load request, the request stops and displays an error message. The user can try to load the nodes again with the "Retry" option.

content tree lazy loading error under California node

You can also use lazy loading within a branch to mitigate long load times, especially if a branch has a large set of data. You can set a predefined number of nodes to load before the "Show more" option appears.

a 'Show more' option to load more Los Angeles counties in the content tree

In this example, the branch loads only 5 items at a time. The user can select the 'Show more' option to load more nodes.

Interactions

Learn how content tree responds when a user interacts with it.

Action icon

If you include an icon to the right of the label, you can also add a click or hover action to it.

lock icon appearing to the right of the node label

In this example, the tooltip informs the user that they can't view the content.

Selection

The content tree allows a user to select either a single item or multiple items. This behavior is optional, and you can turn it off at any time.
When multi-selection is enabled, each selection highlights after the user selects it. The user doesn't need to hold the Shift key to select more than one item in the content tree. The user can select the item again to deselect it.

Single-select
only the Pasadena item is selected under the parent Los Angeles County
Multi-select
items Pasadena and Beverly Hills items are selected under the parent Los Angeles County

Highlight options

There are 2 different highlight options in a content tree: string highlight and node highlight.

String highlight

The content tree component supports string highlighting when the user enables a search or filter option.

'Ala' appears in the search and the matching string in both Alabama and Alaska is bolded

Items that match the search query will appear in bold. If the string is a text link, it will retain the underline and color styling.

Node highlight

You can configure whether to highlight only the selected node or the selected node and its immediate parent node. The default option is to highlight only the selected node.

Los Angeles is highlighted under the Los Angeles County parent node

In this example, only the selected node is highlighted.

If you choose to highlight the selected node and its immediate parent node, the selections highlight in different colors.

the parent node Los Angeles County and its child node Los Angeles are both highlighted

In this example, the selected node and its immediate parent node are highlighted.

Drag and drop

You can allow the user to drag and drop nodes within a content tree. When you enable drag for a node, by default a copy will be dragged to the drop location. You can change this effect to move the node.

When the user selects and begins to drag a node, a ghost image of that node appears. As the user drags it, an insertion point appears to show where the node moves to when dropped. The precise cursor position determines the drop location. When a node can accept a drop, a node can be dropped above, below, or on it to create a parent/chid relationship. The drop target is the parent and the dragged node is the child.

If the user tries to move a node that is not draggable, no action takes place. If they try to drop a node on a node that doesn’t allow drop, no action will take place and the cursor returns to its default state. If the user drags a child node, the immediate parent node receives a border. This allows users to know exactly where they are within the content tree.

insertion point appears above Sadou Makaté for the dragged node

In this example, the user is dragging Fakhri Shokoohi's record. The insertion point shows that its new location is above Sadou Makaté's record.

If the user wants to drop the child node at the bottom of the content tree, the location of the insertion point will determine the node's hierarchy. To place the node at the bottom of the current list of child nodes, the user must be within the correct parent node.

insertion point appears underneath the parent node

In this example, the user is dragging Fakhri Shokoohi's record. The insertion point shows that its new location is underneath Quinten Kortum's record.

If the user wants to convert the selected child node into a parent node, they can shift the insertion point to appear outside the current parent node.

insertion point appears under the root node

In this example, the user is dragging Fakhri Shokoohi's record. The insertion point shows that its new location is as a parent node on the same hierarchy level as Address Book, Deleted Items, and Messages.

If the user wants to place one or more nodes within a collapsed parent node, they must first expand the node by hovering the selected ghost nodes on top of the parent node. This action expands the collapsed node.

dragging ghost node to hover on top of collapsed parent node labeled Address Book
Address Book parent node opens when the user hovers the ghost node on it
drops node labeled John Williams under Address Book parent node

If the user is dragging and dropping an expanded parent node, the node collapses while it's being moved. Once it's dropped in its new location, it returns to its expanded state.

multi-select moving a parent node and its child nodes to the insertion point
new location for the parent node and its child nodes after drag and drop

If you enable multi-select, the user can drag more than one node at the same time. As the user drags the nodes, the total node count appears next to the first selected node, which turns into a ghost node.

dragging two nodes at once with the total number of nodes showing on the right

Truncation

The following options are available for handling long labels in a content tree: truncate with an ellipsis or wrap the label to the next line. Use only one of these options to keep your design consistent.

Ellipsis

You can truncate a label with an ellipsis, and the full label shows in a tooltip on hover. However, the elements on the right will always be present.

node label truncated with an ellipsis

Wrap

You can also choose to wrap the label instead of truncating it or adding a scrollbar. The label wraps to the second line, and any elements stay positioned to the upper right of the label.

node label wrapping to a second line

Usability

Content tree complies with all internationalization and accessibility requirements.

Internationalization

When the content translates to a right-to-left (RTL) language, the nodes flip and align on the right. Any icons in the content tree flip their orientation only if they are direction-based.

content tree reading right-to-left and aligned on the right side

Accessibility

Learn how to access the actionable elements of content tree through keyboard interactions and screen readers.

Keyboard interactions

When focus is outside of the content tree, you can access the actionable elements of content tree with these keyboard keys:

  • Home: Moves focus to first node in tree
  • End: Moves focus to last node in tree
  • Space or Enter:
    • If focus is on a node, it selects the node
    • If focus is on the expand or collapse control, it expands or collapses the node tree
    • If focus is on actionable text or an icon, it selects and initiates the action
  • Tab: Goes to next actionable item in a node; if there isn't one, it exits the tree
  • Arrow up: Moves focus to the previous visible node; if focus is on or within the first visible node, it does nothing
  • Arrow down: Moves focus to the next visible node; if focus is on or within the last visible node, it does nothing
  • Arrow right:
    • Expands a collapsed node that is in focus
    • If focus is on an expanded parent node, moves focus to the first actionable item within the parent node; does nothing if the parent node doesn’t have any actionable items
    • If focus is on a node that is not a parent, moves focus to the first actionalble iterm within the node; does nothing if the node has no actionable items
    • If focus is on an actionable item, moves focus to the next actionable item; does nothing if the actionable item is in the last position - furthest right
  • Arrow left:
    • If focus is on an expanded node, it collapses the node; does nothing if focus is on a collapsed parent node,
    • Does nothing if the node is not a parent node
    • If focus is on the first actionable item within a node, moves focus to the node
    • If focus is on the first node in the tree, it moves focus to the content tree
      To initiate drag and drop mode for content tree nodes:
  • Shift + Spacebar: Initiates drag and drop mode; no actions is taken if initiated on a non-draggable node
    When the user is using the drag and drop interaction:
  • Escape: Cancels drag mode
  • Enter: Drops the node(s) the user is dragging; if the user attempts to drop on a node that doesn’t allow dropping, the insertion point will not appear
  • Arrow up: Moves insertion point up
  • Arrow down: Moves insertion point down; if the insertion point is already at the bottom of a subtree, the insertion point goes to the parent node hierarchy level
  • Arrow right: Expands a collapsed node
  • Arrow left: Collapses an expanded node

Screen readers

Content tree has no specific screen reader considerations.