A tree is a hierarchical component that gives users access to a hierarchical set of objects displayed in a the parent-child relationship.

Usage

Use a tree view to visually display hierarchical information. The user can expand, collapse, and select a tree node within a tree view.

Types

Basic Tree

A basic tree provides a tree structure with named nodes and an arrow to expand and collapse child nodes.

Basic Tree With Icons

A tree can include icons to represent the type of nodes within that group. Icons appear between the collapse/expand arrow and the parent node title.

Checkbox Tree

A checkbox tree features checkboxes between the collapse/expand arrow and the name to indicate whether a node is selected. A parent node with children that are both selected and not selected is shown with an “indeterminate” state.

Checkbox trees should not be used together with icons for the nodes. As with icon trees, make sure to put checkboxes on all nodes of a checkbox tree. Do not alternate between types of trees in a checkbox tree.

Anatomy

The styling of each piece of a tree node is consistent across the different types of trees.

Touch Targets

The dimensions of the expand/collapse arrow and the node title allow for a comfortable touch target allowing use with a mouse or a touch screen.

Touch Targets are relevant even outside of a mobile form factor. Many new desktop environments, especially those running Windows, allow for the use of a touch screen and should be considered when designing your applications.

Behavior

Common terminology that explains tree behavior.

Highlight

Click on a node in the tree to either “highlight” it or navigate to its relative content.

Select

Choose items to apply an action. For example, selecting a checkbox in the tree.

Expand / Collapse

Use the arrow to the left of a node to expand or collapse a node in the tree.

Interacting With Nodes

Expanding / Collapsing Nodes

To expand or collapse a parent node, the user clicks on the expand/collapse arrow. Clicking on the node item itself does not expand or collapse a node. It serves as a highlighting mechanism.

In read-only trees where highlighting is not an option, this pattern remains true for consistency.

Highlighting Tree Nodes

To navigate to a content area based on a tree node or to highlight a tree node in order to take a subsequent action based on the selection, a user clicks on the node title itself.

Interacting With Checkbox Trees

With a checkbox tree, a user is able to perform one or a combination of three actions by clicking on one of three distinct targets:

1. Expanding and Collapsing: a user is able to perform this action by clicking on the expand / collapse arrow.
2. Checking a Checkbox: this would require clicking on the checkbox itself to check or uncheck a treenode. This will also affect the status of the parent node’s checkbox.
3. Highlighting Tree Node: a user can highlight a tree node by clicking on the name (label) of the tree node. This allows for the possibility of loading content based on selection to provide more information on a tree node.

Loading Data

The way to load data within the tree is based on the scenario in which the tree is being used.

Load Parent Nodes First

With a dynamic tree, make sure to load the parent nodes first and then lazy load child nodes when requested.

A general goal to keep in mind is that you want to minimize the time a user needs to spend before their first interaction with the tree as well as every subsequent interaction afterwards.

Code & Examples

Basic tree

A basic tree can be created by simply nesting clr-tree-node components at will. To pre-expand a node, you can use the [clrExpanded] input.

Please note that every tree requires to have root node to work properly, this is done by having clr-tree as root wrapper, please check the example below.

<clr-tree>
  <clr-tree-node [clrExpanded]="true">
    David Wallace (CFO)
    <clr-tree-node [clrExpanded]="true">
      Michael Scott (Regional Manager)

      <clr-tree-node>Dwight K. Schrute (Assistant to the Regional Manager)</clr-tree-node>

      <clr-tree-node>
        Jim Halpert (Head of Sales)
        <clr-tree-node>Andy Bernard</clr-tree-node>
        <clr-tree-node>Stanley Hudson</clr-tree-node>
        <clr-tree-node>Phyllis Vance</clr-tree-node>
        <clr-tree-node>Todd Packer</clr-tree-node>
      </clr-tree-node>

      <clr-tree-node>
        Angela Martin (Head of Accounting)
        <clr-tree-node>Kevin Malone</clr-tree-node>
        <clr-tree-node>Oscar Martinez</clr-tree-node>
      </clr-tree-node>

      <clr-tree-node>
        Kelly Kapoor (Head of Customer Service)
        <clr-tree-node>Ryan Howard (Temp)</clr-tree-node>
      </clr-tree-node>

      <clr-tree-node>
        Creed Bratton (Quality Assurance)
      </clr-tree-node>

      <clr-tree-node>
        Meredith Palmer (Supplier Relations)
      </clr-tree-node>

      <clr-tree-node>
        Toby Flenderson (Human Resources)
      </clr-tree-node>

      <clr-tree-node>
        Pam Beesly (Reception)
      </clr-tree-node>

      <clr-tree-node>
        Darryl Philbin (Warehouse)
      </clr-tree-node>
    </clr-tree-node>
  </clr-tree-node>
</clr-tree>

Tracking expanded nodes

Use two-way binding [(clrExpanded)]="expanded" on the clrExpanded property to track when a node is expanded or collapsed.

<clr-tree>
  <clr-tree-node [(clrExpanded)]="expanded">
    {{expanded ? "I am expanded" : "I am collapsed"}}
    <clr-tree-node>
      Child Tree Node
    </clr-tree-node>
  </clr-tree-node>
</clr-tree>

Routing with a tree

Use the .clr-treenode-link class to style content inside of a Tree Node as clickable. Indicate an active Tree Node with the .active class combined with the .clr-treenode-link class.

<clr-tree>
  <clr-tree-node [clrExpanded]="true">
    The Beatles
    <clr-tree-node>
      <a [routerLink]="['./album1']" class="clr-treenode-link" routerLinkActive="active">Abbey Road</a>
    </clr-tree-node>
    <clr-tree-node>
      <a [routerLink]="['./album2']" class="clr-treenode-link" routerLinkActive="active">Revolver</a>
    </clr-tree-node>
    <clr-tree-node>
      <a [routerLink]="['./album3']" class="clr-treenode-link" routerLinkActive="active">Rubber Soul</a>
    </clr-tree-node>
  </clr-tree-node>
</clr-tree>
<router-outlet></router-outlet>

Generating a tree dynamically

When the tree structure is large and complex you can use iteration to generate nodes and child nodes based on the structure given to the ClrTree.

Tree element

<clr-tree>
  <clr-tree-node *ngFor="let directory of rootDirectory" [(clrExpanded)]="directory.expanded">
    <cds-icon [attr.shape]="directory.icon"></cds-icon>
    {{directory.name}}
    <clr-tree-node *ngFor="let file of directory.files">
      <button (click)="openFile(directory.name, file.name)" class="clr-treenode-link" [class.active]="file.active">
        <cds-icon [attr.shape]="file.icon"></cds-icon>
        {{file.name}}
      </button>
    </clr-tree-node>
  </clr-tree-node>
</clr-tree>

Tree typeScript

class DynamicDemo {
  rootDirectory: any[] = [
    {
      name: 'Applications',
      icon: 'folder',
      expanded: true,
      files: [
        {
          icon: 'calendar',
          name: 'Calendar',
          active: true,
        },
        {
          icon: 'line-chart',
          name: 'Charts',
          active: false,
        },
        {
          icon: 'dashboard',
          name: 'Dashboard',
          active: false,
        },
        {
          icon: 'map',
          name: 'Maps',
          active: false,
        },
      ],
    },
    {
      name: 'Files',
      icon: 'folder',
      expanded: false,
      files: [
        {
          icon: 'file',
          name: 'Cover Letter.doc',
          active: false,
        },
      ],
    },
    {
      name: 'Images',
      icon: 'folder',
      expanded: false,
      files: [
        {
          icon: 'image',
          name: 'Screenshot.png',
          active: false,
        },
      ],
    },
  ];

  openFile(directoryName: string, fileName: string) {
    /* ... */
  }
}

Checkbox tree

Use checkbox when nodes of the tree need to be selected or unselected by users. There are three parts that are needed to implement a ClrTree with checkbox controls.

1. Data structured in a tree hierarchy
2. The correct declaration on the ClrTreeNode's that need to be selectable
3. A ClrSelectedState for each node that is selectable

Checkbox JSON

[
  {
    "name": "Dairy",
    "selected": "INDETERMINATE",
    "items": [
      { "name": "Milk", "selected": "UNSELECTED" },
      { "name": "Cheese", "selected": "SELECTED" }
    ]
  },
  {
    "name": "Vegetables",
    "selected": "UNSELECTED",
    "items": [
      { "name": "Carrots", "selected": "UNSELECTED" },
      { "name": "Potatoes", "selected": "UNSELECTED" },
      { "name": "Beans", "selected": "UNSELECTED" }
    ]
  }
]

Checkbox element

<clr-tree>
  <clr-tree-node *ngFor="let group of groceries" [(clrSelected)]="group.selected" [clrExpanded]="true">
    {{group.name}}
    <clr-tree-node *ngFor="let item of group.items" [(clrSelected)]="item.selected">
      {{item.name}}
    </clr-tree-node>
  </clr-tree-node>
</clr-tree>

<button class="btn btn-sm" type="button" (click)="selectVegetables()">Select all vegetables</button>

Checkbox typeScript

import { ClrSelectedState } from '@clr/angular';
export class GroceryList {
  groceries = [
    {
      name: 'Dairy',
      selected: ClrSelectedState.INDETERMINATE,
      items: [
        { name: 'Milk', selected: ClrSelectedState.UNSELECTED },
        { name: 'Cheese', selected: ClrSelectedState.SELECTED },
      ],
    },
    {
      name: 'Vegetables',
      selected: ClrSelectedState.UNSELECTED,
      items: [
        { name: 'Carrots', selected: ClrSelectedState.UNSELECTED },
        { name: 'Potatoes', selected: ClrSelectedState.UNSELECTED },
        { name: 'Beans', selected: ClrSelectedState.UNSELECTED },
      ],
    },
  ];
  selectVegetables() {
    this.groceries[1].selected = ClrSelectedState.SELECTED;
  }
}

Binding selection to a boolean

If you know a specific node can never become indeterminate, you probably want to use a boolean property on your node. As mentioned previously, [(clrSelected)] always outputs ClrSelectedState enum values, making two-way binding with a boolean problematic. The most straightforward solution is to use the de-sugarized syntax of the two-way binding , transforming the output to a boolean directly.

Checkbox JSON

[
  {
    "type": "Authenticated Users",
    "rights": [
      {
        "name": "Read",
        "enable": true
      },
      {
        "name": "Modify",
        "enable": true
      },
      {
        "name": "Create",
        "enable": false
      },
      {
        "name": "Delete",
        "enable": false
      }
    ]
  },
  {
    "type": "Owners",
    "rights": [
      {
        "name": "Read",
        "enable": true
      },
      {
        "name": "Modify",
        "enable": true
      },
      {
        "name": "Create",
        "enable": true
      },
      {
        "name": "Delete",
        "enable": true
      }
    ]
  },
  {
    "type": "Public",
    "rights": [
      {
        "name": "Read",
        "enable": true
      },
      {
        "name": "Modify",
        "enable": false
      },
      {
        "name": "Create",
        "enable": false
      },
      {
        "name": "Delete",
        "enable": false
      }
    ]
  }
]

Binding element

<clr-tree>
  <clr-tree-node [clrExpanded]="true">
    Permissions
    <clr-tree-node *ngFor="let permission of permissions" [clrExpanded]="true">
      {{permission.type}}
      <clr-tree-node
        *ngFor="let right of permission.rights"
        [clrSelected]="right.enable"
        (clrSelectedChange)="right.enable = !!$event"
      >
        {{right.name}}
      </clr-tree-node>
    </clr-tree-node>
  </clr-tree-node>
</clr-tree>

Binding TypeScript

@Component({
  selector: '...',
  templateUrl: '...',
})
export class Permissions {
  permissions: any = [
    {
      type: 'Authenticated Users',
      rights: [
        {
          name: 'Read',
          enable: true,
        },
        {
          name: 'Modify',
          enable: true,
        },
        {
          name: 'Create',
          enable: false,
        },
        {
          name: 'Delete',
          enable: false,
        },
      ],
    },
    {
      type: 'Owners',
      rights: [
        {
          name: 'Read',
          enable: true,
        },
        {
          name: 'Modify',
          enable: true,
        },
        {
          name: 'Create',
          enable: true,
        },
        {
          name: 'Delete',
          enable: true,
        },
      ],
    },
  ];
}

Recursive tree

If the data you are displaying is recursive or has an unknown depth, you can use our *clrRecursiveFor structural directive to recursively iterate over your data. It has the same syntax as *ngFor, and accepts an additional getChildren parameter that receives a node and should return its children. Please note that it needs to be used inside of a <clr-tree> to function properly.

Recursive element

<clr-tree>
  <clr-tree-node *clrRecursiveFor="let file of root; getChildren: getChildren" [(clrSelected)]="file.selected">
    {{file.name}}
  </clr-tree-node>
</clr-tree>

Recursive TypeScript

export class RecursiveSelection {
  root = [
    {
      name: 'src',
      selected: ClrSelectedState.INDETERMINATE,
      files: [
        {
          name: 'app',
          selected: ClrSelectedState.INDETERMINATE,
          files: [
            {
              name: 'app.component.html',
              selected: ClrSelectedState.UNSELECTED,
            },
            {
              name: 'app.component.ts',
              selected: ClrSelectedState.UNSELECTED,
            },
            {
              name: 'app.module.ts',
              selected: ClrSelectedState.SELECTED,
            },
            {
              name: 'app.routing.ts',
              selected: ClrSelectedState.UNSELECTED,
            },
          ],
        },
        {
          name: 'environments',
          selected: ClrSelectedState.SELECTED,
          files: [
            {
              name: 'environments.prod.ts',
              selected: ClrSelectedState.SELECTED,
            },
            {
              name: 'environment.ts',
              selected: ClrSelectedState.SELECTED,
            },
          ],
        },
        {
          name: 'index.html',
          selected: ClrSelectedState.UNSELECTED,
        },
        {
          name: 'main.ts',
          selected: ClrSelectedState.UNSELECTED,
        },
      ],
    },
    {
      name: 'package.json',
      selected: ClrSelectedState.UNSELECTED,
    },
    {
      name: 'tsconfig.json',
      selected: ClrSelectedState.UNSELECTED,
    },
  ];

  getChildren = folder => folder.files;
}

Lazy loading child nodes

If your tree is too large to be fully build on initialization or getting the children of a node is an expensive operation like an HTTP request, you might want to lazy-load tree nodes, only loading the ones that are currently displayed. To lazy-load children for a simple tree component, you need to combine several features as follows:

• Use our <clr-tree> root component, giving it a [clrLazy]="true" input
• leverage our *clrIfExpanded structural directive, it only instantiates children when they are displayed
• listen to the (clrIfExpandedChange) output to fetch the children's data
• add a [clrLoading] boolean input to the node if fetching children is asynchronous, to display a spinner while waiting for the data to be loaded

Lazy tree element

<clr-tree [clrLazy]="true">
  <clr-tree-node [clrLoading]="loading">
    <cds-icon shape="building"></cds-icon>
    Office Locations
    <ng-template clrIfExpanded (clrIfExpandedChange)="$event ? fetchLocations() : null">
      <clr-tree-node *ngFor="let location of locations$ | async">
        {{location}}
      </clr-tree-node>
    </ng-template>
  </clr-tree-node>
</clr-tree>

Lazy tree TypeScript

@Component({})
export class OfficeLocations {
  constructor(private locationService: LocationService) {}

  locations$: Observable<string[]>;
  loading = false;

  fetchLocations() {
    this.loading = true;
    this.locations$ = this.locationService.getLocations().pipe(tap(() => (this.loading = false)));
  }
}

Lazy-loading recursive trees

Lazy-loading data for recursive trees is actually the simplest case: as soon as you set [clrLazy]="true" on the parent <clr-tree>, the getChildren function will only be lazily called when a node becomes expanded, and supports both Promise and Observable return types if you need to fetch children asynchronously.

By default, recursive trees will pre-load on level ahead to know if the currently displayed nodes are expandable of not. If you do not want this behavior and have a way of knowing if a node is expandable without fetching its children, you can prevent the extra loading by using the [clrExpandable] boolean input on nodes based on your own condition.

Lazy-loading recursive tree element

<clr-tree [clrLazy]="true">
    <clr-tree-node *clrRecursiveFor="let file of root$ | async; getChildren: getChildren"
                   [clrExpandable]="file.isFolder">
        <clr-icon [attr.shape]="file.isFolder ? 'folder' : 'file'"></clr-icon>
        {{file.name}}
    </clr-tree-node>
</clr-tree>

Lazy-loading recursive tree TypeScript

@Component({})
export class FileBrowser implements OnInit {
  constructor(private folderService: FolderService) {}

  root$: Observable<File[]>;

  getChildren = (folder: File) => {
    if (folder.isFolder) {
      return this.folderService.getFiles(folder);
    } else {
      return null;
    }
  };

  ngOnInit(): void {
    this.root$ = this.folderService.getFiles('/');
  }
}