Spectrum

Version 3.0.0

Tree view

A tree view provides users with a way to navigate nested hierarchical information.

Table of contents#

Anatomy
Options
Composition
Behaviors
Usage guidelines
Internationalization
Keyboard interactions
Changelog
Design checklist

Anatomy#

Options#

Text-only#

A tree view is text-only by default. This option is best used when a hierarchy consists of all of the same content type.

Icons#

Icons can be used to add clarification about tree view items. These help to signify content types, which creates easier reference and context within the hierarchy.

Thumbnails#

Use thumbnails for when a user needs to have a preview of the content contained in a tree view item. Thumbnails are primarily used in experiences such as layer panels.

Detached#

When a tree view is used outside of a panel (no borders on the left and right sides), the detached option will display the tree view items with rounded corners. A tree view is used inside of a panel by default, spanning from edge to edge.

Key example of an emphasized tree view with icons, with a parent tree view item, 2 child tree view items, and 2 more nested child tree view items under the expanded 2nd child tree view item. One of the child items is in a selected state, with a blue background and blue border.

Emphasis#

By default, a tree view is not emphasized. This is optimal for when it's used with a clear indication of selected items elsewhere in the interface (e.g., a main/detail split view in which the selected item’s label is repeated or clearly indicated in the detail view).

The emphasized tree view has a translucent blue background and blue border for its selected state, to provide visual prominence that meets accessible color contrast ratio. This is optimal for when the selection should call attention (e.g., selecting a file to upload from a tree view, or when the tree view is the sole UI element for the interaction with the hierarchical content).

Size#

A tree view comes in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.

Key example of a tree view with icons, with a parent tree view item, 2 child tree view items, and 2 more nested child tree view items under the expanded 2nd child tree view item. A drag icon appears when hovering on a tree view item.

Drag icon#

Tree view items can display a drag icon, if necessary. The drag icon provides a keyboard-navigable indicator when multiple actions can be taken on a single tree view item. It only appears on hover, down, and keyboard focus states.

Selection#

Tree views have the option of being either single-select or multi-select, for both checkbox and highlight selection styles. The default selection behavior for a multi-select tree view is to toggle selection on and off when selecting an item. The default selection behavior for a single-select tree view is to replace the current selection with the new selection.

Checkbox or highlight selection style#

Some tree views let a user select items, on which they can then take an action. Both single-select and multi-select tree views can display checkboxes to the far left side of each item, or display only a highlight state. With the checkbox selection style, clicking another tree view item will add that item to the selection. Clicking a selected tree view item will deselect it.

Sometimes it may not make sense to use checkboxes to indicate selection. In those cases, use the highlight selection style to display a highlighted state when a user is selecting one or more items. With this option, clicking another tree view item will select the new item and deselect any existing selection by default.

For the highlight selection style, use the emphasized option in order to meet contrast minimums. All tree views have a hover state, regardless if actions or selections can be made.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

Property	Values	Default value
size	small / medium / large / extra-large	medium
is detached	yes / no	no
emphasized	yes / no	no
show drag icon	yes / no Drag icon only appears on hover, down, and keyboard focus.	no
selection mode	single / multiple	multiple
selection style	checkbox / highlight	checkbox
selection behavior	toggle / replace	toggle

Composition#

Key example of a tree view with a parent tree view item and 2 child tree view items. The second child tree view item is expanded to show another child tree view item. The label area is the area for the text that shows the name of a tree view item.

Label area#

The label area is reserved for the text that acts as the label of the tree view item. In rare cases, additional components can be placed in this area (e.g., badges). This area is placed on the right side for RTL languages.

Context area#

The context area is reserved for icons or thumbnails that provide additional contextual information about the individual tree view item.

Actions area#

The actions area is reserved for an action button or action group. This area houses actions that can be taken on the tree view item.

Behaviors#

Collapse and expand#

Clicking the collapse and expand button will expand or collapse a tree view item that contains child tree view items.

Key example of a tree view with 2 parent tree view items. The second parent tree view item is expanded to show 2 child tree view items. This parent tree view item is being dragged to be reordered higher in the hierarchy.

Drag and drop#

Tree view items can be dragged and dropped as a way for reordering or restructuring the hierarchy. Multiple tree view items can be dragged and reordered simultaneously. When selecting tree view items in different hierarchies, dropping them in a new location will flatten their hierarchical relationship with one another as sibling children of the tree view item that they were dropped into.

Tree views should also accept dropped items from outside the component in order to create new tree view items (e.g., dropping a new file into a tree view in order to upload a file to a specific folder).

Key example of a tree view with a parent tree view item, containing 2 child tree view items. The 2nd child tree view item contains 2 more child tree view items. The first of these is in the selected state, with a drag icon appearing to allow for a keyboard-based drag-and-drop interaction.

Drag icon focus#

When using this option for a tree view, the drag icon receives keyboard focus in order to allow for a keyboard-based drag-and-drop interaction.

Key example of several nested parent and child tree view items, with the items deepest in the hierarchy having their labels truncated because of limited horizontal space.

Text overflow#

When a tree view item label is too long for the available horizontal space, the label truncates. The full label is displayed on hover and focus within a tooltip.

Usage guidelines#

Always display the collapse and expand button#

For proper functionality, a tree view needs to display the collapse and expand button, which uses a chevron icon. This makes it clear to a user as to what kind of behavior to expect when they click on the icon of a tree view item.

Key example of the correct way to use the collapse and expand button in a tree view. A parent tree view item, label My files, with the collapse and expand button next to the label, is in the collapsed state. When toggling the button, the parent tree view item expands to show 4 child tree view items, labels File 01.pdf, File 02.pdf, File 03.pdf, File 04.pdf.

Use the chevron icon to show how to toggle the collapse/expand behavior.

Key example of the incorrect way to use the collapse and expand button in a tree view, by removing the chevron icon. A parent tree view item, label My files, with no collapse and expand button next to the label, is in the collapsed state. When toggling the tree view item label, the parent tree view item expands to show 4 child tree view items, labels File 01.pdf, File 02.pdf, File 03.pdf, File 04.pdf.

Don't remove or replace the chevron icon with unique iconography.

Using multiple sources in one tree view#

If you need to display hierarchical information from different sources, display them in a single tree view as separate sections with section headings. These sources should not cross-reference each other so that you don’t confuse users. Single selection and multi-selection should work as expected for a single tree view component.

Key example of the correct way to show a tree view using multiple sources, by using section headings. First section, heading Local Files. Parent tree view item, label Design files. 2 child tree view items, labels Production ready, Work in progress. Work in progress contains 1 more item, label Branding. Branding contains 1 more item, label Assets. Second section, heading On the Cloud. Parent tree view item, label Design files, child tree view item, Shared with team.

Separate tree views into sections with headings.

Customize the root item display#

The root (topmost) level of the hierarchy doesn't always need to be displayed, nor be displayed as a tree view item. In some cases, the root does not provide a user with any context and it can be hidden or replaced with a section header. In other cases, such as with mixing tree views, the root can be displayed as a “back” button.

Key example of the correct way to customize the root item display. Root item, label All Library Folders, with a unique icon. 2 parent folders and 2 child folders, each with a file folder icon.

Use a heading and unique icon for showing a root item.

Drill-in tree views#

Sometimes it's necessary to show different hierarchical displays based on the context of what a user is navigating. In those cases, allow for a user to replace a tree view item by “driling" into it, displaying a different variation of the tree view within the same panel. Place the tree view within a navigation controller (which should provide a “back" button) to enable this type of drill-in navigation.

Key example of correct way to display a tree view with a navigation controller for a drill-in view. Root item with a back button, label Artboards. 2 child tree view items, labels Group 1 and Group 2. Group 2 is expanded to show 2 child tree view items, labels Group 3 and Group 4.

Display a tree view within a navigation controller for drill-in views.

Iconography#

Choose icons that relate to the object type being represented in the tree view. These icons can be unique to specific data types, to add better clarification for users.

Key example of how to correctly use iconography to communicate the type of object a tree view item represents. First example, label My files, with a file folder icon to show that the item is a folder. Second example, label ReviewDocument.pdf, with a document icon to show that the item is a file type. Third example, label Brushed titanium, with a preset texture icon, to show that the item is an object type.

Use an icon that correlates to the type of object being shown.

Using thumbnails#

Tree view items can show thumbnails as an alternative to icons. Thumbnails are best used when a user needs to have a preview of the content represented by the tree view item. Icons can be used as a fallback for when an image is unavailable, but should be appropriately sized to match the thumbnail.

Key example of the correct way to use thumbnails to show a preview of a tree item’s content. Parent tree view item, label Group, in an expanded state to show 2 child tree view items, labels Layer 1, Layer 2. All tree view items have thumbnails next to the labels.

Use thumbnails to preview content.

Be mindful of thumbnail size and proportions#

Tree views with thumbnails should use a thumbnail size that is appropriate to the size of the tree view itself. For example, an extra-large tree view would not work well with small thumbnails; those proportions may be better suited for using icons instead.

Key example of the incorrect way to use thumbnails to show a preview of a tree item’s content. Parent tree view item, in an expanded state to show 2 child tree view items. All tree view items have thumbnails next to the label that are too large compared to the smaller size of the tree view items.

Don’t use large thumbnails in a small tree view.

Multiple thumbnails#

In some cases, multiple thumbnails need to be displayed in-line with the tree view item (e.g., layer masks). These thumbnails should be individually selectable and inherit all other behaviors of a standard tree view item, such as drag-and-drop behavior. Don't use more than 3 thumbnails per tree view item.

Key examples of the correct way to use multiple thumbnails. First example, a parent tree view item in the expanded state, labeled Flowers, with 3 thumbnails next to the label. 2 child tree view items, labels Left flower and Right flower, with 2 thumbnails each.

Separate multiple thumbnails with an indicator.

Restrict hierarchy depth#

One way to address overflow is to set a limit on how many levels of hierarchy deep that a user can create in a tree view. Some products use this method to mitigate the complexity that comes with deeply-nested hierarchies. Limits can help for when having a complex hierarchy isn’t necessary to an experience.

Key example of the correct way to restrict hierarchy depth. A tree view with 5 levels of hierarchy, from root to most nested, labels Composition, Foreground, Framing, Flowers, Right flower.

Restrict hierarchy depth when appropriate.

When a label's length is too long to display within the tree view, the text will truncate at the end using an ellipsis. Hovering over or focusing on the truncated tree view item should reveal a tooltip that shows the full text of the label.

Key example of the correct way to use a tooltip to show a label that has been truncated in a tree view. A cursor hovers over a tree view item in German that has a label that has been truncated, to reveal the entire label text in a tooltip.

Show truncated labels using a tooltip.

Use an adjustable layout#

When a user’s tree view hierarchy could be deeper than the available space in the layout, use an adjustable layout mechanism like panels or rails. This will allow users to modify the layout and still preserve visibility on their tree view.

Key example of the correct way to use an adjustable layout. A drag bar appears to allow a user to customize a hierarchy that is 4 levels deep, with the lowest level in the hierarchy having truncated tree view item labels.

Use an adjustable layout for deeply-nested hierarchies.

Horizontal scrolling#

If you have a layout that doesn't allow for users to adjust the width of the container for a tree view, allow them to horizontally scroll in order to see the full depth of the hierarchy.

Key example of the correct way to use horizontal scrolling in a fixed layout. A horizontal scroll bar appears to allow a user to view a hierarchy that is 4 levels deep, with the lowest levels in the hierarchy having truncated tree view item labels.

Allow horizontal scrolling in a fixed layout.

Large tree views#

When tree views are very large, use a progress circle or a "show more" affordance to show additional parts when it’s contextually relevant. These loading patterns can apply to the entire tree view, or to nested tree view items.

Key example of the correct way to show a loading affordance when loading a larger tree view. A tree view with 8 tree view items has a progress circle and label reading loading… at the bottom of the tree view to indicate that there are more tree view items to view.

Display a progress circle when loading large tree views.

Loading tree view items#

If system processes are delaying the display of child tree view items when a parent tree view item is expanded, show a clear indication that the items are in the process of loading.

Show a progress circle when waiting for tree view data to load.

Sorting#

Users should be able to sort a tree view. Sorting should not affect the hierarchical structure since each layer of the hierarchy is sorted individually.

Key example showing how tree view items can be sorted. Tree view item label A parent in expanded state to show it contains 3 child tree view items, labels A child, B child, C child. 2 more tree view items, labels B parent and C parent, in the collapsed state.

Sort at the individual layers of the hierarchy.

Filtering#

Users should be able to filter a tree view’s content in order to quickly find the items they're looking for. When filtering hides sections of the hierarchical structure, the remaining tree view items are displayed as a root item. If filtering doesn't remove structures, the hierarchical relationships are still retained.

Key example of filtering functionality in a tree view. A text field, label filter, input text Home. Search filter results show 3 levels of a tree view hierarchy, with tree view items all containing the word Home.

Flatten or retain hierarchy in filter results.

Modifying the tree view#

Users may need to be able to directly modify a tree view. They should be able to create new parent or child tree view items, such as a grouping or a folder. They should also be able to flatten the hierarchy at an individual tree view item level (e.g., ungrouping a group of layers). In some cases, the tree view item labels should be editable by the user.

Any action for modifying the hierarchy should be presented as both an explicit action as well as keyboard shortcuts (if needed), but never as keyboard shortcuts alone.

Key example of actions that allow modification of a tree view. A three-level tree view has available options to add, view, create new folder, delete, and do more options on all of the tree view items.

Use persistent actions to allow for modification to the hierarchy.

Entering into multiple selection mode#

Allow users to explicitly enter a multiple selection mode when keyboard shortcuts (Shift + click) are unavailable, or when you want to display a unique kind of selection. Do this by toggling between the selection style, from highlight to checkbox.

Key example of a multiple selection mode in a tree view. More than one tree view item in a layers panel is selected, with a small toast appearing with text reading 2 layers selected.

Allow users to enter multiple selection mode.

Use checkbox selection for modifying a tree view#

The checkbox selection style is intended for performing bulk actions on tree view items. Use this option when selection corresponds to bulk actions.

Key example of the correct way to use checkbox selection to have users modify a tree view. A 2-level hierarchy tree view with 6 tree view items, with a checkbox next to each item. 2 of the items are selected with a checkmark.

Use checkbox selection for modifying items in a tree view.

Use a checkbox component when selection doesn't affect tree view items#

When you need to provide selection controls within a hierarchy, use a checkbox component in place of the tree view item’s label. This shouldn't correspond to the selection of specific content, and is optimal for use cases like categorized filtering.

Key example of how to use a checkbox in place of a tree view item label. A 2-level tree view hierarchy with 5 tree view items, 2 of which are selected with a checkbox.

Use a checkbox component for selecting hierarchical options.

Internationalization#

Key example of a 2-level hierarchy tree view with 4 tree view items, with labels in Arabic. The tree view is mirrored so that the icons are on the right.

RTL#

For RTL (right-to-left) languages, the entire tree view is mirrored horizontally, including the direction of the collapse and expand button. Workflow icons follow iconography internationalization guidelines.

Keyboard interactions#

Key	Interaction
Tab	Moves focus to the tree view, placing the first tree view item in focus.
Down Arrow	Moves focus to the tree view item below or to the next thumbnail of a tree view item.
Up Arrow	Moves focus to the tree view item above or to the previous thumbnail of a tree view item.
Enter or Space	Selects the currently focused tree view item. If focus is on a child of the tree view item, subsequent action is based on the child component’s keyboard interactions. For the drag icon, this places the user in drag-and-drop mode.
Right Arrow (Left Arrow in RTL)	Expands the currently focused tree view item. If the tree view item is already expanded, or if the tree view item is not expandable, focus is moved in a left-to-right direction along child components. If focus is on the rightmost child of the tree view item, focus does not move.
Left Arrow (Right Arrow in RTL)	Collapses the currently focused tree view item. If focus is on a child of the tree view item, focus is moved in a right-to-left direction along child components. If focus is on the leftmost child of the tree view item, focus is placed back on the parent tree view item.
Home	Moves focus to the first item in the tree view without opening or closing a level.
End	Moves focus to the last item in the tree view that is focusable without opening a level.
Cmd + [ (optional)	Moves the currently selected item up in the view order.
Cmd + ] (optional)	Moves the currently selected item down in the view order.
Cmd + Z (optional)	Undoes the action most recently taken, such as after the user drags and drops, reorders, or performs an action on a tree view item.
Cmd + G (optional)	Groups the selected tree view item(s) into a new parent tree view item.
Shift + Cmd + G (optional)	Ungroups or removes the selected parent tree view item, placing its children at the same level of hierarchy as the removed items.

Changelog#

Date	Number	Notes
Apr 06, 2022	3.0.0	Updated all colors to 6.0.0
Mar 23, 2021	2.0.0	Added size, drag icon, selection mode, selection style, and selection behavior options Replaced quiet option with emphasis (changes default) Renamed standalone option as detached
Feb 14, 2020	1.0.0	This component has been added to the website

Design checklist#

All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Accessible use of color

Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).

Accessible contrast for text

Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).

Accessible contrast for UI components

Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).

Content design

UI language and information design considerations have been incorporated into component design.

Defined options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

Defined behaviors

Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don'ts that highlight best practices and common mistakes.

Writing guidelines

Includes content standards or usage guidelines for how to write or format in-product content for the component.

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are available as design tokens.

UI kit

Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.

Generated UI kit

Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.

Tab bar (iOS)

Badge