Web Components Tree Overview

Ignite UI for Web Components Tree, also known as TreeView component, is a high-performance control that visualizes expandable data structures within a tree-like UI, enabling you to apply load on demand for child items. The Ignite UI for Web Components Tree also provides features like expanding and collapsing nodes, nested app navigation, Ignite UI for Web Components Tree nodes either can be generated manually or from a bound data source.

For end-users this means they can easily navigate across different app pages, use selection, checkboxes, add texts, icons, images and more.

The Ignite UI for Web Components Tree component allows users to represent hierarchical data in a tree-view structure, maintaining parent-child relationships, as well as to define static tree-view structure without a corresponding data model. Its primary purpose is to allow end-users to visualize and navigate within hierarchical data structures. The IgcTreeComponent component also provides load on demand capabilities, item activation, multiple and cascade selection of items through built-in checkboxes, built-in keyboard navigation and more.

Web Components Tree Example

In this basic Ignite UI for Web Components Tree example, you can see how to define a tree and its items by specifying the item hierarchy.

How to Use Ignite UI for Web Components Tree With Ignite UI

First, you need to install the Ignite UI for Web Components by running the following command:

npm install igniteui-webcomponents

Before using the IgcTreeComponent, you need to register it as follows:

import { defineComponents, IgcTreeComponent } from 'igniteui-webcomponents';
defineComponents(IgcTreeComponent);

For a complete introduction to the Ignite UI for Web Components, read the Getting Started topic.

The simplest way to start using the IgcTreeComponent is as follows:

Declaring a tree

IgcTreeItemComponent is the representation of every item that belongs to the IgcTreeComponent. Items provide disabled, active, selected and expanded properties, which give you opportunity to configure the states of the item as per your requirement. The value property can be used to add a reference to the data entry the item represents.

Items can be declared using one of the following approaches.

Declaring the tree and its items by specifying the item hierarchy and iterating through a data set

<igc-tree>
    ${data.map((x) => html`
        <igc-tree-item .value=${x} .expanded=${x.expanded} .label=${x.label}>
              ${x.children.map((y) => html`
                  <igc-tree-item .value=${y} .expanded=${y.expanded}>
                      <span slot="label">${y.label}</slot>
                  </igc-tree-item>
              `
        </igc-tree-item>
    `
</igc-tree>

Items can be bound to a data model so that their expanded and selected states are reflected in the underlying data as well.

Declaring a tree by creating static unbound items

In order to render a tree you do not necessarily need a data set - individual items can be created without an underlying data model using the exposed label property or provide a custom slot content for the IgcTreeItemComponent label.

<igc-tree>
    <igc-tree-item>
        <div slot="label">
            I am a parent item 1
	        <img src="hard_coded_src.webb" alt="Alt Text">
        </div>
	    <igc-tree-item label="I am a child item 1">
	    </igc-tree-item>
    </igc-tree-item>

    <igc-tree-item>
        <div slot="label">
            I am a parent item 2
	        <img src="hard_coded_src.webb" alt="Alt Text">
        </div>
	    <igc-tree-item label="I am a child item 1">
	    </igc-tree-item>
    </igc-tree-item>
</igc-tree>

[!Note] You can provide a custom slot content for each IgcTreeItemComponent's indentation, expansion and label area respectively using the provided indentation, indicator and label slots.

Item Interactions

IgcTreeItemComponent could be expanded or collapsed:

by clicking on the item expand indicator (default behavior).
by clicking on the item if the IgcTreeComponent toggleNodeOnClick property is set to true.

<igc-tree toggle-node-on-click="true">
    <igc-tree-item label="North America">
        <igc-tree-item label="United States"></igc-tree-item>
        <igc-tree-item label="Canada"></igc-tree-item>
        <igc-tree-item label="Mexico"></igc-tree-item>
    </igc-tree-item>
    <igc-tree-item label="South America">
        <igc-tree-item label="Brazil"></igc-tree-item>
    </igc-tree-item>
</igc-tree>

By default, multiple items could be expanded at the same time. In order to change this behavior and allow expanding only single branch at a time, the singleBranchExpand property could be enabled. This way when an item is expanded, all of the others already expanded branches in the same level will be collapsed.

<igc-tree single-branch-expand="true">
    <igc-tree-item label="North America">
        <igc-tree-item label="United States"></igc-tree-item>
        <igc-tree-item label="Canada"></igc-tree-item>
        <igc-tree-item label="Mexico"></igc-tree-item>
    </igc-tree-item>
    <igc-tree-item label="South America">
        <igc-tree-item label="Brazil"></igc-tree-item>
    </igc-tree-item>
</igc-tree>

In addition, the IgcTreeComponent provides the following API methods for item interactions:

expand - expands all items. If an items array is passed, expands only the specified items.
collapse - collapses all items. If an items array is passed, collapses only the specified items.
IgcSelectComponent - selects all items. If an items array is passed, selects only the specified items. Does not emit selection event.
Tree.Deselect - deselects all items. If an items array is passed, deselects only the specified items. Does not emit selection event.

Web Components Tree Selection

In order to setup item selection in the Ignite UI for Web Components Tree component, you just need to set its selection property. This property accepts the following three modes: None, Multiple and Cascade. Below we will take a look at each of them in more detail.

None

In the IgcTreeComponent by default item selection is disabled. Users cannot select or deselect an item through UI interaction, but these actions can still be completed through the provided API method.

Multiple

To enable multiple item selection in the IgcTreeComponent just set the selection property to multiple. This will render a checkbox for every item. Each item has two states - selected or not. This mode supports multiple selection.

<igc-tree selection="multiple">
</igc-tree>

Cascade

To enable cascade item selection in the IgcTreeComponent, just set the selection property to cascade. This will render a checkbox for every item.

<igc-tree selection="Cascade">
</igc-tree>

In this mode a parent's selection state entirely depends on the selection state of its children. When a parent has some selected and some deselected children, its checkbox is in an indeterminate state.

Keyboard navigation in IgcTreeComponent provides a rich variety of keyboard interactions for the user. This functionality is enabled by default and allows users to navigate through the items.

The IgcTreeComponent navigation is compliant with W3C accessibility standards and convenient to use.

Key Combinations

↓ - navigates to the next visible item. Marks the item as active. Does nothing if on the LAST item.
Ctrl + ↓ - navigates to the next visible item. Does nothing if on the LAST item.
↑ - navigates to the previous visible item. Marks the item as active. Does nothing if on the FIRST item.
Ctrl + ↑ - navigates to the previous visible item. Does nothing if on the FIRST item.
← - on an expanded parent item, collapses it. If the item is collapsed or does not have children, moves to its parent item. Does nothing if there is no parent item.
→ - on an expanded parent item, navigates to the first child of the item. If on a collapsed parent item, expands it. Does nothing if the item does not have children.
Home - navigates to the FIRST item.
End - navigates to the LAST visible item.
Tab - navigates to the next focusable element on the page, outside of the tree.
Shift + Tab - navigates to the previous focusable element on the page, outside of the tree.
Space - toggles selection of the current item. Marks the node as active.
Shift + Space - toggles selection of all items between the active one and the one pressed Space while holding Shift if selection is enabled.
Enter - activates the focused item. If the item has link in it, opens the link.
* - expands the item and all sibling items on the same level.

When selection is enabled, end-user selection of items is only allowed through the rendered checkbox. Since both selection types allow multiple selection, the following mouse and keyboard interactions are available:

Click - when performed on the item checkbox, toggles selection of the item if selection is enabled. Otherwise, focuses the item
Shift + Click - when performed on the item checkbox, toggles selection of all items between the active one and the one clicked while holding Shift if selection is enabled

Web Components Tree Load On Demand

The Ignite UI for Web Components Tree can be rendered in such way that it requires the minimal amount of data to be retrieved from the server so the user could see it as quickly as possible. With this dynamic data loading approach, only after the user expands an item, the children for that particular parent item will be retrieved. This mechanism, also known as Load on Demand, can be easily configured to work with any remote data.

After the user clicks the expand icon, it is replaced by a loading indicator. When the loading property resolves to false, the loading indicator disappears and the children are loaded.

You can provide a custom slot content for the loading area using the loadingIndicator slot. If such slot is not defined, the IgcCircularProgressComponent is used.

Load On Demand With Virtualization

Loading a greater number of children on demand in the Ignite UI for Web Components Tree might negatively impact performance since the tree items are declaratively defined by design. The following demo showcases how the @lit-labs/virtualizer library can be used to render the child tree items in a virtualized container. The result is improved performance as only the visible chunk of children is rendered in the DOM.

Styling

You can change the appearance of the IgcTreeItemComponents, by using some of the exposed CSS parts listed below:

Part name	Description
`wrapper`	The wrapper for the tree item.
`selected`	Indicates selected state. Applies to `wrapper`.
`focused`	Indicates focused state. Applies to `wrapper`.
`active`	Indicates an active state. Applies to `wrapper`.
`indicator`	The expand indicator of the tree item.
`label`	The tree item content.
`text`	The tree item displayed text.
`select`	The checkbox of the tree item when selection is enabled.

Using these CSS parts we can customize thе appearance of the IgcTreeComponent component like this:

igc-tree-item::part(active) {
    background: #ecaa53;
}

igc-tree-item::part(selected) {
    background: #ffe6cc;
}

igc-tree-item::part(active selected) {
    background: #ff8c1a;
    color: white;
}