Blazor Tree Overview

    The Ignite UI for Blazor Tree element 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 IgbTree 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.

    Blazor Tree Example

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

    Usage

    You will also need to link an additional CSS file to apply the styling to the IgbTree component. The following needs to be placed in the wwwroot/index.html file in a Blazor Web Assembly project or the Pages/_Host.cshtml file in a Blazor Server project:

    <link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
    
    // in Program.cs file
    
    builder.Services.AddIgniteUIBlazor(
        typeof(IgbTreeModule),
        typeof(IgbTreeItemModule)
    );
    

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

    Declaring a tree

    IgbTreeItem is the representation of every item that belongs to the IgbTree. 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
    <IgbTree>
        @foreach (var student in this.Students)
        {
            <IgbTreeItem Value="@item.Id" Label="@item.Name">
            </IgbTreeItem>
        }
    </IgbTree>
    

    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 IgbTreeItem label.

    <IgbTree>
        <IgbTreeItem Label="North America">
            <IgbTreeItem Label="United States"></IgbTreeItem>
            <IgbTreeItem Label="Canada"></IgbTreeItem>
            <IgbTreeItem Label="Mexico"></IgbTreeItem>
        </IgbTreeItem>
        <IgbTreeItem Label="South America">
            <IgbTreeItem Label="Brazil"></IgbTreeItem>
            <IgbTreeItem Label="Uruguay"></IgbTreeItem>
        </IgbTreeItem>
        <IgbTreeItem Label="Europe">
            <IgbTreeItem Label="United Kingdom"></IgbTreeItem>
            <IgbTreeItem Label="Germany"></IgbTreeItem>
            <IgbTreeItem Label="Bulgaria"></IgbTreeItem>
        </IgbTreeItem>
    </IgbTree>
    
    Note

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

    Item Interactions

    The IgbTree 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.
    • select - selects all items. If an items array is passed, selects only the specified items. Does not emit Selection event.
    • deselect - deselects all items. If an items array is passed, deselects only the specified items. Does not emit Selection event.

    Blazor Tree Selection

    In order to setup item selection in the Ignite UI for Blazor Tree, 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 IgbTree 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 IgbTree 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.

    <IgbTree Selection=TreeSelection.Multiple>
    </IgbTree>
    

    Cascade

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

    <IgbTree Selection=TreeSelection.Cascade>
    </IgbTree>
    

    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

    Keyboard navigation in IgbTree 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 IgbTree navigation is compliant with W3C accesibility standards and convenient to use.

    Key Combinations

    • Arrow Down - navigates to the next visible item. Marks the item as active. Does nothing if on the LAST item.
    • Ctrl + Arrow Down - navigates to the next visible item. Does nothing if on the LAST item.
    • Arrow Up - navigates to the previous visible item. Marks the item as active. Does nothing if on the FIRST item.
    • Ctrl + Arrow Up - navigates to the previous visible item. Does nothing if on the FIRST item.
    • Arrow Left - 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.
    • Arrow Right - 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 + 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

    Styling

    You can change the appearance of the IgbTreeItems, 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 IgbTree 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;
    }
    

    API References

    Additional Resources