Tree | Calcite Design System

Trees are nestable, expandable text groups that can contain multiple links for navigation or items for filtering.

Overview

Trees can be used for filtering, navigation, and form selection. They organize items into hierarchical parent-child relationships. Parents can expand or collapse to show or hide nested items.

Sample

Usage

Folder structures
Data navigation
Nested selection workflows

Component comparison

Tree and List both support structured selection, but serve different needs.

Tree

This component

Best for representing hierarchical, parent-child relationships with collapsible levels.

Offers additional selection modes such as "ancestors" and "multichildren".

Supports nesting and expandable content containers.

List

Alternative

Best for displaying actionable item sets, or sortable List Items.

Offers selection modes such as "single" and "multiple".

Supports nesting and expandable content containers. Provides advanced functionality such as draggable sorting and filtering.

Best practices

Recommendations

Open Tree showing parent, child, grandchild, and great-grandchild levels

Do use Tree for deep hierarchical data structures and multi-level selection workflows.

A transportation method Dropdown that contains a Tree with transportation types

Avoid placing Trees inside Dropdowns. Instead, use Combobox to represent hierarchical categories.

Accessibility

Key	Function
`Arrow left`	If the `calcite-tree-item` has children, all child elements will collapse.
`Arrow right`	If the `calcite-tree-item` has children, all child elements will expand.
`Arrow up`	Moves focus to the previous `calcite-tree-item`, including `expanded` child elements. If the current focus is the first `calcite-tree-item`, focus will not change.
`Arrow down`	Moves focus to the next `calcite-tree-item`, including `expanded` child elements. If the current focus is the last `calcite-tree-item`, focus will not change.
`Home`	Moves focus to the first `calcite-tree-item`. If the current focus is the first `calcite-tree-item`, focus will not change.
`End`	Moves focus to the last `calcite-tree-item`. If the current focus is the last `calcite-tree-item`, focus will not change.
`Tab`	Moves focus in and out of the component.
`Tab` and `Shift`	Moves focus in and out of the component.

Writing and copy

Do prefer brevity in Trees.

Avoid long phrases or sentences in Trees.

API reference

Properties

Property	Attribute	Description	Type	Default
lines	lines	When `true`, displays indentation guide lines.	`boolean`	`false`
scale	scale	Specifies the component's size.	`Scale`	`"m"`
selectedItemsread-only		Specifies the component's selected items.	`TreeItem[]`
selectionMode	selection-mode	Specifies the selection mode of the component, where: `"ancestors"` displays with a checkbox and allows any number of selections from corresponding parent and child selections, `"children"` allows any number of selections from one parent from corresponding parent and child selections, `"multichildren"` allows any number of selections from corresponding parent and child selections, `"multiple"` allows any number of selections, `"none"` allows no selections, `"single"` allows one selection, and `"single-persist"` allows and requires one selection.	`SelectionMode`	`"single"`

Slots

Name	Description
default (unnamed)	A slot for `calcite-tree-item` elements.

Events

Name	Description	Behavior
calciteTreeSelect	Fires when the user selects/deselects `calcite-tree-items`.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`