Tree

Tree components display hierarchical data in a collapsible structure, allowing users to explore nested relationships while keeping the interface organized and navigable.

import {TreeModule} from "@qualcomm-ui/angular/tree"

Overview

The tree relies on the TreeCollection class to manage its items. Refer to the API below for details.
Trees are composed of nodes, which are objects that describe the tree data. There are two types of nodes:
- A branch node is a node that has children.
- A leaf node is a node that does not have children.
Each node has a value (unique identifier used for selection/expansion) and a text (display text).

Default object shape:

value (required): unique identifier for expansion/selection
text (required): display text
nodes (optional): child nodes for branches
disabled (optional): prevents interaction when true

These defaults can be overridden in the TreeCollection constructor.

We expose the q-tree-nodes component for rendering Branch and Leaf nodes. Use the <ng-template q-tree-branch-template> and <ng-template q-tree-leaf-template> directives to customize the content of each tree item.

Note that q-tree-nodes automatically renders child nodes for branches, so you only have to customize the content of the node itself.

node_modules

src

prettier.config.js

package.json

tsconfig.json

<q-tree-nodes [indexPath]="[i]" [node]="node">
  <ng-template
    let-branch
    q-tree-branch-template
    [rootNode]="collection.rootNode"
  >
    <div q-tree-branch-node>
      <div q-tree-branch-trigger></div>
      <svg q-tree-node-icon qIcon="FolderIcon"></svg>
      <span q-tree-node-text>{{ branch.node.name }}</span>
    </div>
  </ng-template>

  <ng-template
    let-leaf
    q-tree-leaf-template
    [rootNode]="collection.rootNode"
  >
    <div q-tree-leaf-node>
      <div q-tree-node-indicator></div>
      <svg q-tree-node-icon qIcon="FileText"></svg>
      <span q-tree-node-text>{{ leaf.node.name }}</span>
    </div>
  </ng-template>
</q-tree-nodes>

Node Types

Pass the rootNode input to the template directives to enable TypeScript type inference. This allows branch.node and leaf.node to have your custom node type instead of the generic TreeNode type.

Nodes

You can bring your own recursive component to create your own abstraction for the tree.

NOTE

This approach is recommended only for advanced use cases. Most users should use the shorthand q-tree-nodes instead.

node_modules

src

prettier.config.js

package.json

tsconfig.json

import {Component, computed, inject, input, type OnInit} from "@angular/core"
import {FileText, FolderIcon} from "lucide-angular"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {
  provideTreeNodePropsContext,
  provideTreeNodeStateContext,
  TreeNodePropsContextService,
  TreeNodeStateContextService,
  useTreeContext,
} from "@qualcomm-ui/angular-core/tree"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {TreeModule} from "@qualcomm-ui/angular/tree"
import {createTreeCollection, type NodeProps} from "@qualcomm-ui/core/tree"

interface FileNode {
  id: string
  name: string
  nodes?: FileNode[]
}

const collection = createTreeCollection<FileNode>({
  nodeChildren: "nodes",
  nodeText: (node) => node.name,
  nodeValue: (node) => node.id,
  rootNode: {
    id: "ROOT",
    name: "",
    nodes: [
      {
        id: "node_modules",
        name: "node_modules",
        nodes: [
          {
            id: "@qui",
            name: "@qui",
            nodes: [
              {
                id: "node_modules/@qualcomm-ui/core",
                name: "@qualcomm-ui/core",
              },
              {
                id: "node_modules/@qualcomm-ui/react",
                name: "@qualcomm-ui/react",
              },
              {
                id: "node_modules/@qualcomm-ui/react-core",
                name: "@qualcomm-ui/react-core",
              },
            ],
          },
          {
            id: "node_modules/@types",
            name: "@types",
            nodes: [
              {id: "node_modules/@types/react", name: "react"},
              {id: "node_modules/@types/react-dom", name: "react-dom"},
            ],
          },
        ],
      },
      {
        id: "src",
        name: "src",
        nodes: [
          {id: "src/app.tsx", name: "app.tsx"},
          {id: "src/index.ts", name: "index.ts"},
        ],
      },
      {id: "prettier.config.js", name: "prettier.config.js"},
      {id: "package.json", name: "package.json"},
      {id: "tsconfig.json", name: "tsconfig.json"},
    ],
  },
})

@Component({
  imports: [TreeModule, IconDirective],
  providers: [
    provideIcons({FileText, FolderIcon}),
    provideTreeNodePropsContext(),
    provideTreeNodeStateContext(),
  ],
  selector: "tree-nodes-recursive",
  template: `
    @let childNodes = treeContext().collection.getNodeChildren(node());
    @if (childNodes.length) {
      <div q-tree-branch>
        <div q-tree-branch-node>
          <div q-tree-node-indicator></div>
          <div q-tree-branch-trigger></div>
          <svg q-tree-node-icon qIcon="FolderIcon"></svg>
          <span q-tree-node-text>
            {{ treeContext().collection.stringifyNode(node()) }}
          </span>
        </div>
        <div q-tree-branch-content>
          <div q-tree-branch-indent-guide></div>
          @for (
            childNode of childNodes;
            let j = $index;
            track treeContext().collection.getNodeValue(childNode)
          ) {
            <tree-nodes-recursive
              [indexPath]="indexPath().concat(j)"
              [node]="childNode"
            />
          }
        </div>
      </div>
    } @else {
      <div q-tree-leaf-node>
        <div q-tree-node-indicator></div>
        <svg q-tree-node-icon qIcon="FileText"></svg>
        <span q-tree-node-text>
          {{ treeContext().collection.stringifyNode(node()) }}
        </span>
      </div>
    }
  `,
})
export class TreeNodesRecursive implements OnInit {
  readonly indexPath = input.required<number[]>()
  readonly node = input.required<FileNode>()

  protected readonly treeContext = useTreeContext()

  private readonly nodePropsService = inject(TreeNodePropsContextService)
  private readonly nodeStateService = inject(TreeNodeStateContextService)

  ngOnInit() {
    const nodeProps = computed<NodeProps<FileNode>>(() => ({
      indexPath: this.indexPath(),
      node: this.node(),
    }))
    this.nodePropsService.init(nodeProps)
    this.nodeStateService.init(
      computed(() => this.treeContext().getNodeState(nodeProps())),
    )
  }
}

@Component({
  imports: [TreeModule, TreeNodesRecursive],
  providers: [provideIcons({FileText, FolderIcon})],
  selector: "tree-nodes-demo",
  template: `
    <div class="w-full max-w-sm" q-tree-root [collection]="collection">
      @for (
        node of collection.rootNode.nodes;
        let i = $index;
        track collection.getNodeValue(node)
      ) {
        <tree-nodes-recursive [indexPath]="[i]" [node]="node" />
      }
    </div>
  `,
})
export class TreeNodesDemo {
  collection = collection
}

Default Expanded

Expand nodes by default using the defaultExpandedValue input. Or use expandedValue and expandedValueChanged to control the expansion manually. These inputs follow our controlled state pattern.

node_modules

src

app.tsx

index.ts

prettier.config.js

package.json

tsconfig.json

<div
  class="w-full max-w-sm"
  q-tree-root
  [collection]="collection"
  [defaultExpandedValue]="['src']"
>

Checkbox Trees

Use the q-tree-node-checkbox directive within each node to create a checkbox tree. The checked state of the tree can be controlled using the checkedValue, checkedValueChanged, and defaultCheckedValue inputs, which follow our controlled state pattern.

Qualcomm

Snapdragon X Elite

Snapdragon X Plus

Intel

Intel Core Ultra

Intel Core i9

Intel Core i7

Intel Core i5

Intel Core i3

AMD

AMD Threadripper

AMD Ryzen 9

AMD Ryzen 7 / 5

import {Component} from "@angular/core"

import {TreeModule} from "@qualcomm-ui/angular/tree"
import {createTreeCollection} from "@qualcomm-ui/core/tree"

interface Node {
  id: string
  nodes?: Node[]
  text: string
}

@Component({
  imports: [TreeModule],
  selector: "tree-checkbox-demo",
  template: `
    <div
      class="w-full max-w-sm"
      q-tree-root
      [collection]="collection"
      [defaultExpandedValue]="['qualcomm', 'amd', 'intel']"
    >
      @for (
        node of collection.rootNode.nodes;
        let i = $index;
        track collection.getNodeValue(node)
      ) {
        <q-tree-nodes [indexPath]="[i]" [node]="node">
          <ng-template
            let-branch
            q-tree-branch-template
            [rootNode]="collection.rootNode"
          >
            <div q-tree-branch-node>
              <div q-tree-branch-trigger></div>
              <span q-tree-node-checkbox></span>
              <span q-tree-node-text>{{ branch.node.text }}</span>
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-tree-leaf-template
            [rootNode]="collection.rootNode"
          >
            <div q-tree-leaf-node>
              <div q-tree-node-indicator></div>
              <span q-tree-node-checkbox></span>
              <span q-tree-node-text>{{ leaf.node.text }}</span>
            </div>
          </ng-template>
        </q-tree-nodes>
      }
    </div>
  `,
})
export class TreeCheckboxDemo {
  collection = createTreeCollection<Node>({
    nodeText: "text",
    nodeValue: "id",
    rootNode: {
      id: "ROOT",
      nodes: [
        {
          id: "qualcomm",
          nodes: [
            {
              id: "snapdragon_x_elite",
              nodes: [
                {id: "X1E-00-1DE", text: "12-core X1E-00-1DE"},
                {id: "X1E-84-100", text: "12-core X1E-84-100"},
                {id: "X1E-80-100", text: "12-core X1E-80-100"},
                {id: "X1E-78-100", text: "12-core X1E-78-100"},
              ],
              text: "Snapdragon X Elite",
            },
            {
              id: "snapdragon_x_plus",
              nodes: [
                {id: "X1P-66-100", text: "10-core X1P-66-100"},
                {id: "X1P-64-100", text: "10-core X1P-64-100"},
                {id: "X1P-46-100", text: "8-core Plus X1P-46-100"},
                {id: "X1P-42-100", text: "8-core Plus X1P-42-100"},
              ],
              text: "Snapdragon X Plus",
            },
          ],
          text: "Qualcomm",
        },
        {
          id: "intel",
          nodes: [
            {
              id: "intel_core_ultra",
              nodes: [
                {id: "ultra9_s2", text: "Core Ultra 9 (Series 2)"},
                {id: "ultra7_s2", text: "Core Ultra 7 (Series 2)"},
                {id: "ultra5_s2", text: "Core Ultra 5 (Series 2)"},
              ],
              text: "Intel Core Ultra",
            },
            {
              id: "intel_core_i9",
              nodes: [
                {id: "i9_14th", text: "Core i9 14th Gen"},
                {id: "i9_13th", text: "Core i9 13th Gen"},
              ],
              text: "Intel Core i9",
            },
            {
              id: "intel_core_i7",
              nodes: [
                {id: "i7_14th", text: "Core i7 14th Gen"},
                {id: "i7_13th", text: "Core i7 13th Gen"},
              ],
              text: "Intel Core i7",
            },
            {
              id: "intel_core_i5",
              nodes: [
                {id: "i5_14th", text: "Core i5 14th Gen"},
                {id: "i5_13th", text: "Core i5 13th Gen"},
              ],
              text: "Intel Core i5",
            },
            {
              id: "intel_core_i3",
              nodes: [
                {id: "i3_14th", text: "Core i3 14th Gen"},
                {id: "i3_13th", text: "Core i3 13th Gen"},
              ],
              text: "Intel Core i3",
            },
          ],
          text: "Intel",
        },
        {
          id: "amd",
          nodes: [
            {
              id: "amd_threadripper",
              nodes: [
                {
                  id: "threadripper_9000",
                  text: "Ryzen Threadripper 9000 Series",
                },
                {
                  id: "threadripper_7000",
                  text: "Ryzen Threadripper 7000 Series",
                },
              ],
              text: "AMD Threadripper",
            },
            {
              id: "amd_ryzen_9",
              nodes: [
                {id: "ryzen9_9000", text: "Ryzen 9 9000 Series"},
                {id: "ryzen9_7000", text: "Ryzen 9 7000 Series"},
              ],
              text: "AMD Ryzen 9",
            },
            {
              id: "amd_ryzen_7_5",
              nodes: [
                {id: "ryzen7_9000", text: "Ryzen 7 9000 Series"},
                {id: "ryzen7_8000g", text: "Ryzen 7 8000-G Series"},
                {id: "ryzen7_8000", text: "Ryzen 7 8000 Series"},
                {id: "ryzen7_7000", text: "Ryzen 7 7000 Series"},
                {id: "ryzen5_9000", text: "Ryzen 5 9000 Series"},
                {id: "ryzen5_8000g", text: "Ryzen 5 8000-G Series"},
                {id: "ryzen5_8000", text: "Ryzen 5 8000 Series"},
                {id: "ryzen5_7000", text: "Ryzen 5 7000 Series"},
              ],
              text: "AMD Ryzen 7 / 5",
            },
          ],
          text: "AMD",
        },
      ],
      text: "",
    },
  })
}

Checkbox selection state

The Tree handles nested checkbox selection automatically:

If all of a node's children are checked, the node will also be checked.
If only some of a node's children are checked, the node will appear indeterminate to indicate partial selection.

When you supply the checkedValue or defaultCheckedValue inputs, you must account for the above logic.

Consider the following tree:

const collection = createTreeCollection<Node>({
  rootNode: {
    id: "ROOT",
    name: "",
    nodes: [
      {
        id: "qualcomm",
        name: "Qualcomm",
        nodes: [
          {
            id: "sdx",
            name: "Snapdragon X",
            nodes: [
              {id: "elite", name: "Snapdragon X Elite"},
              {id: "plus", name: "Snapdragon X Plus"},
            ],
          },
        ],
      },
    ],
  },
})

Let's say that we want to select the sdx node and its children by default.

@Component({
  template: `
    <!-- won't work, we need to supply the child nodes instead -->
    <div q-tree-root [defaultCheckedValue]="['sdx']" [collection]="collection">
      ...
    </div>
  `,
})
export class MyComponent {
  // ...
}

Instead, supply all the child nodes to indicate that the parent is selected:

Qualcomm

Snapdragon X

Snapdragon X Elite

Snapdragon X Plus

<div
  class="w-full max-w-sm"
  q-tree-root
  [collection]="collection"
  [defaultCheckedValue]="['elite', 'plus']"
  [defaultExpandedValue]="['qualcomm', 'sdx']"
>

The following demo shows checked state below the tree. Interact with it to see state updates:

qualcomm

snapdragon_x_elite

snapdragon_x_plus

intel

intel_core_ultra

intel_core_i9

amd

amd_threadripper

amd_ryzen_9

[
  "X1E-00-1DE",
  "X1E-84-100"
]

<q-tree-nodes [indexPath]="[i]" [node]="node">
  <ng-template
    let-branch
    q-tree-branch-template
    [rootNode]="collection.rootNode"
  >
    <div q-tree-branch-node>
      <div q-tree-branch-trigger></div>
      <span q-tree-node-checkbox></span>
      <span q-tree-node-text>{{ branch.node.id }}</span>
    </div>
  </ng-template>

  <ng-template
    let-leaf
    q-tree-leaf-template
    [rootNode]="collection.rootNode"
  >
    <div q-tree-leaf-node>
      <span q-tree-node-checkbox></span>
      <span q-tree-node-text>{{ leaf.node.id }}</span>
    </div>
  </ng-template>
</q-tree-nodes>

Disabled Nodes

You can disable nodes by setting the disabled property on the node object.

node_modules

src

prettier.config.js

package.json

renovate.json

tsconfig.json

import {Component} from "@angular/core"
import {FileText, FolderIcon} from "lucide-angular"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {TreeModule} from "@qualcomm-ui/angular/tree"
import {createTreeCollection} from "@qualcomm-ui/core/tree"

interface FileNode {
  disabled?: boolean
  id: string
  name: string
  nodes?: FileNode[]
}

@Component({
  imports: [TreeModule, IconDirective],
  providers: [provideIcons({FileText, FolderIcon})],
  selector: "tree-disabled-node-demo",
  template: `
    <div class="w-full max-w-sm" q-tree-root [collection]="collection">
      @for (
        node of collection.rootNode.nodes;
        let i = $index;
        track collection.getNodeValue(node)
      ) {
        <q-tree-nodes [indexPath]="[i]" [node]="node">
          <ng-template
            let-branch
            q-tree-branch-template
            [rootNode]="collection.rootNode"
          >
            <div q-tree-branch-node>
              <div q-tree-node-indicator></div>
              <div q-tree-branch-trigger></div>
              <svg q-tree-node-icon qIcon="FolderIcon"></svg>
              <span q-tree-node-text>{{ branch.node.name }}</span>
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-tree-leaf-template
            [rootNode]="collection.rootNode"
          >
            <div q-tree-leaf-node>
              <div q-tree-node-indicator></div>
              <svg q-tree-node-icon qIcon="FileText"></svg>
              <span q-tree-node-text>{{ leaf.node.name }}</span>
            </div>
          </ng-template>
        </q-tree-nodes>
      }
    </div>
  `,
})
export class TreeDisabledNodeDemo {
  collection = createTreeCollection<FileNode>({
    nodeChildren: "nodes",
    nodeText: (node) => node.name,
    nodeValue: (node) => node.id,
    rootNode: {
      id: "ROOT",
      name: "",
      nodes: [
        {
          id: "node_modules",
          name: "node_modules",
          nodes: [
            {
              id: "@qui",
              name: "@qui",
              nodes: [
                {
                  id: "node_modules/@qualcomm-ui/core",
                  name: "@qualcomm-ui/core",
                },
                {
                  id: "node_modules/@qualcomm-ui/react",
                  name: "@qualcomm-ui/react",
                },
                {
                  id: "node_modules/@qualcomm-ui/react-core",
                  name: "@qualcomm-ui/react-core",
                },
              ],
            },
            {
              id: "node_modules/@types",
              name: "@types",
              nodes: [
                {id: "node_modules/@types/react", name: "react"},
                {id: "node_modules/@types/react-dom", name: "react-dom"},
              ],
            },
          ],
        },
        {
          id: "src",
          name: "src",
          nodes: [
            {id: "src/app.tsx", name: "app.tsx"},
            {id: "src/index.ts", name: "index.ts"},
          ],
        },
        {id: "prettier.config.js", name: "prettier.config.js"},
        {id: "package.json", name: "package.json"},
        {disabled: true, id: "renovate.json", name: "renovate.json"},
        {id: "tsconfig.json", name: "tsconfig.json"},
      ],
    },
  })
}

Filtering

Here's an example that filters the nodes using matchSorter.

node_modules

src

prettier.config.js

package.json

tsconfig.json

import {Component, signal} from "@angular/core"
import {FormsModule} from "@angular/forms"
import {FileText, FolderIcon, Search} from "lucide-angular"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {TextInputModule} from "@qualcomm-ui/angular/text-input"
import {TreeModule} from "@qualcomm-ui/angular/tree"
import {createTreeCollection} from "@qualcomm-ui/core/tree"
import type {TreeCollection} from "@qualcomm-ui/utils/collection"
import {matchSorter} from "@qualcomm-ui/utils/match-sorter"

interface FileNode {
  id: string
  name: string
  nodes?: FileNode[]
}

const initialCollection = createTreeCollection<FileNode>({
  nodeChildren: "nodes",
  nodeText: (node) => node.name,
  nodeValue: (node) => node.id,
  rootNode: {
    id: "ROOT",
    name: "",
    nodes: [
      {
        id: "node_modules",
        name: "node_modules",
        nodes: [
          {
            id: "@qui",
            name: "@qui",
            nodes: [
              {
                id: "node_modules/@qualcomm-ui/core",
                name: "@qualcomm-ui/core",
              },
              {
                id: "node_modules/@qualcomm-ui/react",
                name: "@qualcomm-ui/react",
              },
              {
                id: "node_modules/@qualcomm-ui/react-core",
                name: "@qualcomm-ui/react-core",
              },
            ],
          },
          {
            id: "node_modules/@types",
            name: "@types",
            nodes: [
              {id: "node_modules/@types/react", name: "react"},
              {id: "node_modules/@types/react-dom", name: "react-dom"},
            ],
          },
        ],
      },
      {
        id: "src",
        name: "src",
        nodes: [
          {id: "src/app.tsx", name: "app.tsx"},
          {id: "src/index.ts", name: "index.ts"},
        ],
      },
      {id: "prettier.config.js", name: "prettier.config.js"},
      {id: "package.json", name: "package.json"},
      {id: "tsconfig.json", name: "tsconfig.json"},
    ],
  },
})

@Component({
  imports: [TreeModule, IconDirective, TextInputModule, FormsModule],
  providers: [provideIcons({FileText, FolderIcon, Search})],
  selector: "tree-filtering-demo",
  template: `
    <div
      class="w-full max-w-sm"
      q-tree-root
      [collection]="initialCollection"
      [expandedValue]="expanded()"
      (expandedValueChanged)="expanded.set($event.expandedValue)"
    >
      <q-text-input
        aria-label="Search for files"
        class="mb-1"
        placeholder="Search for files: 'react'"
        size="sm"
        startIcon="Search"
        [ngModel]="query()"
        (ngModelChange)="search($event)"
      />
      @for (
        node of collection().rootNode.nodes;
        let i = $index;
        track collection().getNodeValue(node)
      ) {
        <q-tree-nodes [indexPath]="[i]" [node]="node">
          <ng-template
            let-branch
            q-tree-branch-template
            [rootNode]="collection().rootNode"
          >
            <div q-tree-branch-node>
              <div q-tree-node-indicator></div>
              <div q-tree-branch-trigger></div>
              <svg q-tree-node-icon qIcon="FolderIcon"></svg>
              <span q-tree-node-text>{{ branch.node.name }}</span>
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-tree-leaf-template
            [rootNode]="collection().rootNode"
          >
            <div q-tree-leaf-node>
              <div q-tree-node-indicator></div>
              <svg q-tree-node-icon qIcon="FileText"></svg>
              <span q-tree-node-text>{{ leaf.node.name }}</span>
            </div>
          </ng-template>
        </q-tree-nodes>
      }
    </div>
  `,
})
export class TreeFilteringDemo {
  readonly initialCollection = initialCollection
  readonly collection = signal<TreeCollection<FileNode>>(initialCollection)
  readonly expanded = signal<string[]>([])
  readonly query = signal("")

  search(value: string) {
    this.query.set(value)

    if (!value) {
      this.collection.set(initialCollection)
      return
    }

    const nodes = matchSorter(initialCollection.getDescendantNodes(), value, {
      keys: ["name"],
    })
    const nextCollection = initialCollection.filter((node) =>
      nodes.some((n) => n.id === node.id),
    )
    this.collection.set(nextCollection)
    this.expanded.set(nextCollection.getBranchValues())
  }
}

Links

Tree nodes can be links using Angular's RouterLink directive. Apply the q-tree-branch-node or q-tree-leaf-node directive to an anchor element with [routerLink].

Components

Switch

Tooltip

Tree

@if (leaf.node.pathname) {
  <a q-tree-leaf-node [routerLink]="leaf.node.pathname">
    <div q-tree-node-indicator></div>
    <span q-tree-node-text>{{ leaf.node.name }}</span>
  </a>
} @else {
  <div q-tree-leaf-node>
    <div q-tree-node-indicator></div>
    <span q-tree-node-text>{{ leaf.node.name }}</span>
  </div>
}

Sizes

Tree item sizes are controlled using the size input on the root of the tree.

Small (sm)

node_modules

src

prettier.config.js

package.json

tsconfig.json

Medium (md)

node_modules

src

prettier.config.js

package.json

tsconfig.json

import {NgTemplateOutlet} from "@angular/common"
import {Component} from "@angular/core"
import {FileText, FolderIcon} from "lucide-angular"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {TreeModule} from "@qualcomm-ui/angular/tree"
import {createTreeCollection} from "@qualcomm-ui/core/tree"

interface FileNode {
  id: string
  name: string
  nodes?: FileNode[]
}

const collection = createTreeCollection<FileNode>({
  nodeChildren: "nodes",
  nodeText: (node) => node.name,
  nodeValue: (node) => node.id,
  rootNode: {
    id: "ROOT",
    name: "",
    nodes: [
      {
        id: "node_modules",
        name: "node_modules",
        nodes: [
          {
            id: "@qui",
            name: "@qui",
            nodes: [
              {
                id: "node_modules/@qualcomm-ui/core",
                name: "@qualcomm-ui/core",
              },
              {
                id: "node_modules/@qualcomm-ui/react",
                name: "@qualcomm-ui/react",
              },
              {
                id: "node_modules/@qualcomm-ui/react-core",
                name: "@qualcomm-ui/react-core",
              },
            ],
          },
          {
            id: "node_modules/@types",
            name: "@types",
            nodes: [
              {id: "node_modules/@types/react", name: "react"},
              {id: "node_modules/@types/react-dom", name: "react-dom"},
            ],
          },
        ],
      },
      {
        id: "src",
        name: "src",
        nodes: [
          {id: "src/app.tsx", name: "app.tsx"},
          {id: "src/index.ts", name: "index.ts"},
        ],
      },
      {id: "prettier.config.js", name: "prettier.config.js"},
      {id: "package.json", name: "package.json"},
      {id: "tsconfig.json", name: "tsconfig.json"},
    ],
  },
})

@Component({
  imports: [TreeModule, IconDirective, NgTemplateOutlet],
  providers: [provideIcons({FileText, FolderIcon})],
  selector: "tree-size-demo",
  template: `
    <div class="flex w-full flex-col gap-4">
      <div
        #root1="treeRoot"
        class="w-full max-w-sm"
        q-tree-root
        size="sm"
        [collection]="collection"
      >
        <span q-tree-label>Small (sm)</span>
        <ng-container
          [ngTemplateOutlet]="treeContent"
          [ngTemplateOutletInjector]="root1.injector"
        />
      </div>

      <div
        #root2="treeRoot"
        class="w-full max-w-sm"
        q-tree-root
        size="md"
        [collection]="collection"
      >
        <span q-tree-label>Medium (md)</span>
        <ng-container
          [ngTemplateOutlet]="treeContent"
          [ngTemplateOutletInjector]="root2.injector"
        />
      </div>
    </div>

    <ng-template #treeContent>
      @for (
        node of collection.rootNode.nodes;
        let i = $index;
        track collection.getNodeValue(node)
      ) {
        <q-tree-nodes [indexPath]="[i]" [node]="node">
          <ng-template
            let-branch
            q-tree-branch-template
            [rootNode]="collection.rootNode"
          >
            <div q-tree-branch-node>
              <div q-tree-node-indicator></div>
              <div q-tree-branch-trigger></div>
              <svg q-tree-node-icon qIcon="FolderIcon"></svg>
              <span q-tree-node-text>{{ branch.node.name }}</span>
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-tree-leaf-template
            [rootNode]="collection.rootNode"
          >
            <div q-tree-leaf-node>
              <div q-tree-node-indicator></div>
              <svg q-tree-node-icon qIcon="FileText"></svg>
              <span q-tree-node-text>{{ leaf.node.name }}</span>
            </div>
          </ng-template>
        </q-tree-nodes>
      }
    </ng-template>
  `,
})
export class TreeSizeDemo {
  collection = collection
}

Add / Remove nodes

The TreeCollection class exposes methods to handle the addition and removal of nodes. Here's an example of how to use them.

node_modules

src

prettier.config.js

package.json

tsconfig.json

import {Component, input, output, signal} from "@angular/core"
import {FileText, FolderIcon, Plus, Trash} from "lucide-angular"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {useTreeContext} from "@qualcomm-ui/angular-core/tree"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {TreeModule} from "@qualcomm-ui/angular/tree"
import {createTreeCollection} from "@qualcomm-ui/core/tree"
import type {TreeCollection} from "@qualcomm-ui/utils/collection"

interface FileNode {
  id: string
  name: string
  nodes?: FileNode[]
}

@Component({
  imports: [TreeModule],
  providers: [provideIcons({Plus, Trash})],
  selector: "tree-node-actions",
  template: `
    <button
      aria-label="Remove node"
      icon="Trash"
      q-tree-node-action
      size="sm"
      (click)="onRemove()"
    ></button>
    @if (isBranch()) {
      <button
        aria-label="Add node"
        icon="Plus"
        q-tree-node-action
        size="sm"
        (click)="onAdd()"
      ></button>
    }
  `,
})
export class TreeNodeActions {
  readonly node = input.required<FileNode>()
  readonly indexPath = input.required<number[]>()
  readonly isBranch = input(false)

  readonly add = output<{indexPath: number[]; node: FileNode}>()
  readonly remove = output<{indexPath: number[]; node: FileNode}>()

  protected readonly treeContext = useTreeContext()

  onRemove() {
    this.remove.emit({indexPath: this.indexPath(), node: this.node()})
  }

  onAdd() {
    this.treeContext().expand([this.node().id])
    this.add.emit({indexPath: this.indexPath(), node: this.node()})
  }
}

const initialCollection = createTreeCollection<FileNode>({
  nodeChildren: "nodes",
  nodeText: "name",
  nodeValue: "id",
  rootNode: {
    id: "ROOT",
    name: "",
    nodes: [
      {
        id: "node_modules",
        name: "node_modules",
        nodes: [
          {
            id: "@qui",
            name: "@qui",
            nodes: [
              {
                id: "node_modules/@qualcomm-ui/core",
                name: "@qualcomm-ui/core",
              },
              {
                id: "node_modules/@qualcomm-ui/react",
                name: "@qualcomm-ui/react",
              },
              {
                id: "node_modules/@qualcomm-ui/react-core",
                name: "@qualcomm-ui/react-core",
              },
            ],
          },
          {
            id: "node_modules/@types",
            name: "@types",
            nodes: [
              {id: "node_modules/@types/react", name: "react"},
              {id: "node_modules/@types/react-dom", name: "react-dom"},
            ],
          },
        ],
      },
      {
        id: "src",
        name: "src",
        nodes: [
          {id: "src/app.tsx", name: "app.tsx"},
          {id: "src/index.ts", name: "index.ts"},
        ],
      },
      {id: "prettier.config.js", name: "prettier.config.js"},
      {id: "package.json", name: "package.json"},
      {id: "tsconfig.json", name: "tsconfig.json"},
    ],
  },
})

@Component({
  imports: [TreeModule, IconDirective, TreeNodeActions],
  providers: [provideIcons({FileText, FolderIcon, Plus, Trash})],
  selector: "tree-add-remove-demo",
  template: `
    <div class="w-full max-w-sm" q-tree-root [collection]="collection()">
      @for (
        node of collection().rootNode.nodes;
        let i = $index;
        track collection().getNodeValue(node)
      ) {
        <q-tree-nodes [indexPath]="[i]" [node]="node">
          <ng-template
            let-branch
            q-tree-branch-template
            [rootNode]="collection().rootNode"
          >
            <div q-tree-branch-node role="treeitem">
              <div q-tree-node-indicator></div>
              <div q-tree-branch-trigger></div>
              <svg q-tree-node-icon qIcon="FolderIcon"></svg>
              <span q-tree-node-text>
                {{ collection().stringifyNode(branch.node) }}
              </span>
              <tree-node-actions
                [indexPath]="branch.indexPath"
                [isBranch]="true"
                [node]="branch.node"
                (add)="addNode($event)"
                (remove)="removeNode($event)"
              />
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-tree-leaf-template
            [rootNode]="collection().rootNode"
          >
            <div q-tree-leaf-node>
              <div q-tree-node-indicator></div>
              <svg q-tree-node-icon qIcon="FileText"></svg>
              <span q-tree-node-text>
                {{ collection().stringifyNode(leaf.node) }}
              </span>
              <tree-node-actions
                [indexPath]="leaf.indexPath"
                [isBranch]="false"
                [node]="leaf.node"
                (remove)="removeNode($event)"
              />
            </div>
          </ng-template>
        </q-tree-nodes>
      }
    </div>
  `,
})
export class TreeAddRemoveDemo {
  readonly collection = signal<TreeCollection<FileNode>>(initialCollection)

  removeNode(event: {indexPath: number[]; node: FileNode}) {
    this.collection.update((c) => c.remove([event.indexPath]))
  }

  addNode(event: {indexPath: number[]; node: FileNode}) {
    const {indexPath, node} = event
    if (!this.collection().isBranchNode(node)) {
      return
    }

    const nodes = [
      {
        id: `untitled-${Date.now()}`,
        name: `untitled-${node.nodes?.length || 0}.tsx`,
      },
      ...(node.nodes || []),
    ]
    this.collection.update((c) => c.replace(indexPath, {...node, nodes}))
  }
}

Explorer

Component Anatomy

Hover to highlight, click to view API

root branch branch-node branch-trigger branch-content branch-indent-guide leaf-node node-checkbox node-icon node-indicator node-text

API

q-tree-root

Prop	Type	Default
checkedValue The controlled checked node value	string[]
collection The tree collection data	TreeCollection
defaultCheckedValue The initial checked node value when rendered. Use when you don't need to control the checked node value.	string[]
defaultExpandedValue The initial expanded node ids when rendered. Use when you don't need to control the expanded node value.	string[]
defaultFocusedValue The initial focused node value when rendered. Use when you don't need to control the focused node value.	string
defaultSelectedValue The initial selected node value when rendered. Use when you don't need to control the selected node value.	string[]
dir The document's text/writing direction.	'ltr' \| 'rtl'
expandedValue The controlled expanded node ids	string[]
expandOnClick Whether clicking on a branch should open it or not	boolean	true
focusedValue The value of the focused node	string
getRootNode A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
id HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
lazyMount When true, the component will not be rendered in the DOM until it becomes visible or active.	boolean	false
loadChildren Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding.	(details: { indexPath: number[] node: T signal: AbortSignal valuePath: string[] }) => Promise<any[]>
selectedValue The controlled selected node value	string[]
selectionMode Whether the tree supports multiple selection `'single'`: only one node can be selected `'multiple'`: multiple nodes can be selected	\| 'multiple' \| 'single'	'single'
shouldHideNode Callback function that determines whether a node should be hidden.	InputSigna
size The size of the tree and its elements. Governs properties like font size, item padding, and icon sizes.	'sm' \| 'md'	'md'
typeahead Whether the tree supports typeahead search	boolean	true
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false
(checkedValueChanged) Called when the checked value changes	{ checkedNodes: Array<T> checkedValue: string[] }
(expandedValueChanged) Called when the tree is opened or closed	{ expandedNodes: Array<T> expandedValue: string[] focusedValue: string }
(focusChanged) Called when the focused node changes	{ focusedNode: T focusedValue: string }
(loadChildrenComplete) Called when a node finishes loading children	{ collection: TreeCollection<T> }
(loadChildrenError) Called when loading children fails for one or more nodes	{ nodes: NodeWithError[] }
(selectedValueChanged) Called when the selection changes	{ focusedValue: string selectedNodes: Array<T> selectedValue: string[] }

checkedValue

Type

string[]

Description

The controlled checked node value

collection

Type

TreeCollection

Description

The tree collection data

defaultCheckedValue

Type

string[]

Description

The initial checked node value when rendered. Use when you don't need to control the checked node value.

defaultExpandedValue

Type

string[]

Description

The initial expanded node ids when rendered. Use when you don't need to control the expanded node value.

defaultFocusedValue

Type

string

Description

The initial focused node value when rendered. Use when you don't need to control the focused node value.

defaultSelectedValue

Type

string[]

Description

The initial selected node value when rendered. Use when you don't need to control the selected node value.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

expandedValue

Type

string[]

Description

The controlled expanded node ids

expandOnClick

Type

boolean

Description

Whether clicking on a branch should open it or not

focusedValue

Type

string

Description

The value of the focused node

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.

Type

string

Description

HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)

lazyMount

Type

boolean

Description

When true, the component will not be rendered in the DOM until it becomes visible or active.

loadChildren

Type

(details: {
  indexPath: number[]
  node: T
  signal: AbortSignal
  valuePath: string[]
}) => Promise<any[]>

Description

Function to load children for a node asynchronously. When provided, branches will wait for this promise to resolve before expanding.

selectedValue

Type

string[]

Description

The controlled selected node value

selectionMode

Type

| 'multiple'
| 'single'

Description

Whether the tree supports multiple selection

'single': only one node can be selected
'multiple': multiple nodes can be selected

shouldHideNode

Type

InputSigna

Description

Callback function that determines whether a node should be hidden.

size

Type

'sm' | 'md'

Description

The size of the tree and its elements. Governs properties like font size, item padding, and icon sizes.

typeahead

Type

boolean

Description

Whether the tree supports typeahead search

unmountOnExit

Type

boolean

Description

When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.

(checkedValueChanged)

Type

{
  checkedNodes: Array<T>
  checkedValue: string[]
}

Description

Called when the checked value changes

(expandedValueChanged)

Type

{
  expandedNodes: Array<T>
  expandedValue: string[]
  focusedValue: string
}

Description

Called when the tree is opened or closed

(focusChanged)

Type

{
  focusedNode: T
  focusedValue: string
}

Description

Called when the focused node changes

(loadChildrenComplete)

Type

{
  collection: TreeCollection<T>
}

Description

Called when a node finishes loading children

(loadChildrenError)

Type

{
  nodes: NodeWithError[]
}

Description

Called when loading children fails for one or more nodes

(selectedValueChanged)

Type

{
  focusedValue: string
  selectedNodes: Array<T>
  selectedValue: string[]
}

Description

Called when the selection changes

Attribute / Property	Value
`class`	'qui-tree__root'
`data-size`	'sm' \| 'md'
`data-tree-part`	'root'
`tabIndex`	-1

q-tree-nodes

Prop	Type	Default
indexPath ^* The index path of the tree node	number[]
node ^* The tree node	T
renderBranch	TemplateRef<any>
renderLeaf	TemplateRef<any>
showIndentGuide Whether to render the indent guide for branch child nodes.	boolean	false

indexPath

Type

number[]

Description

The index path of the tree node

node

Type

Description

The tree node

renderBranch

Type

TemplateRef<any>

renderLeaf

Type

TemplateRef<any>

showIndentGuide

Type

boolean

Description

Whether to render the indent guide for branch child nodes.

TreeCollection

Note that the TreeCollection accepts a single generic type parameter, T, which is the object type of the node used in the collection.

Constructor

The constructor of the TreeCollection class accepts the following options:

Prop	Type	Default
nodeChildren Property key for accessing a node's children.	keyof T	"nodes"
nodeChildrenCount Function to determine the count of a node's children.	( node: T, ) => number
nodeDisabled Property key or function to determine if a node is disabled. When a string key is provided, the value of node[key] determines the disabled state.	\| keyof T \| ((node: T) => boolean)	"disabled"
nodeText Property key or function for getting a node's text. When a string key is provided, the value of node[key] is used.	\| keyof T \| ((node: T) => string)	"text"
nodeValue Property key or function for getting a node's value. When a string key is provided, the value of node[key] is used.	\| keyof T \| ((node: T) => string)	"value"
rootNode The root node of the tree	T

nodeChildren

Type

keyof T

Description

Property key for accessing a node's children.

nodeChildrenCount

Type

(
  node: T,
) => number

Description

Function to determine the count of a node's children.

nodeDisabled

Type

| keyof T
| ((node: T) => boolean)

Description

Property key or function to determine if a node is disabled. When a string key is provided, the value of node[key] determines the disabled state.

nodeText

Type

| keyof T
| ((node: T) => string)

Description

Property key or function for getting a node's text. When a string key is provided, the value of node[key] is used.

nodeValue

Type

| keyof T
| ((node: T) => string)

Description

Property key or function for getting a node's value. When a string key is provided, the value of node[key] is used.

rootNode

Type

Description

The root node of the tree

Prop	Type
at Gets the node at the specified index path. indexPath:Array of indices representing the path to the node	( indexPath: number[], ) => T
contains Checks if a parent index path contains a child index path. parentIndexPath:The parent path valueIndexPath:The child path to check	( parentIndexPath: number[], valueIndexPath: number[], ) => boolean
copy Creates a new tree collection with the same options but different root node. rootNode:The new root node for the copied collection	( rootNode: T, ) => any
filter Filters the tree keeping only nodes that match the predicate. predicate:Function to test each node	( predicate: ( node: T, indexPath: number[], ) => boolean, ) => any
findNode Finds the first node with the specified value. value:The value to search for rootNode:The root node to start searching from	( value: string, rootNode?: T, ) => T
findNodeBy	( predicate: ( node: T, indexPath: number[], ) => boolean, rootNode?: T, ) => T
findNodes Finds all nodes with values matching the provided array. values:Array of values to search for rootNode:The root node to start searching from	( values: string[], rootNode?: T, ) => Array<T>
flatten Flattens the tree into an array with parent/child relationships. rootNode:The root node to start flattening from	( rootNode?: T, ) => Array< T & { _children: number[] _index: number _parent: number } >
getBranchValues Gets all branch node values with optional depth filtering. rootNode:The root node to start from opts:Options for skipping nodes and filtering by depth	( rootNode?: T, opts?: { skip?: (args: { indexPath: number[] node: T value: string }) => boolean \| void } & { depth?: \| number \| (( nodeDepth: number, ) => boolean) }, ) => string[]
getDepth Gets the depth of a node with the specified value. value:The value to find the depth for	( value: string, ) => number
getDescendantNodes Gets all descendant nodes of the specified node. valueOrIndexPath:Either a node value or index path options:Options for controlling which descendants to include	( valueOrIndexPath?: \| string \| number[], options?: T & { disabled?: boolean id?: string onUnregister?: ( index: number, ) => void requireContext?: boolean }, ) => Array<T>
getDescendantValues Gets all descendant values of the specified node. valueOrIndexPath:Either a node value or index path options:Options for controlling which descendants to include	( valueOrIndexPath: \| string \| number[], options?: T & { disabled?: boolean id?: string onUnregister?: ( index: number, ) => void requireContext?: boolean }, ) => string[]
getFirstNode Gets the first non-disabled node in the tree. rootNode:The root node to start searching from	( rootNode?: T, ) => T
getIndexPath Gets the index path for a node with the specified value. value:The value to find the index path for	( value: string, ) => number[]
getLastNode Gets the last non-disabled node in the tree. rootNode:The root node to start searching from opts:Options for skipping nodes during traversal	( rootNode?: T, opts?: { skip?: (args: { indexPath: number[] node: T value: string }) => boolean \| void }, ) => T
getNextNode Gets the next node after the one with the specified value. value:The value to find the next node from opts:Options for skipping nodes during traversal	( value: string, opts?: { skip?: (args: { indexPath: number[] node: T value: string }) => boolean \| void }, ) => T
getNextSibling Gets the next non-disabled sibling of the node at the index path. indexPath:Array of indices representing the path to the node	( indexPath: number[], ) => T
getNodeChildren Returns all child nodes for this node. Uses options.nodeToChildren if provided, otherwise falls back to default behavior.	( node: T, ) => Array<T>
getNodeChildrenCount Gets the number of children for a node, supporting lazy loading scenarios. Uses options.nodeToChildrenCount if provided, otherwise falls back to default behavior. node:The node to get children count for	( node: T, ) => number
getNodeDisabled Checks if a node is disabled. Uses options.isNodeDisabled if provided, otherwise falls back to default behavior. node:The node to check	( node: T, ) => boolean
getNodeValue Gets the string value for a node. Uses options.nodeValue if provided, otherwise falls back to default behavior. node:The node to get the value from	( node: T, ) => string
getParentNode Gets the parent node of the specified node. valueOrIndexPath:Either a node value or index path	( valueOrIndexPath: \| string \| number[], ) => T
getParentNodes Gets all parent nodes from root to the specified node. valueOrIndexPath:Either a node value or index path	( valueOrIndexPath: \| string \| number[], ) => Array<T>
getPreviousNode Gets the previous node before the one with the specified value. value:The value to find the previous node from opts:Options for skipping nodes during traversal	( value: string, opts?: { skip?: (args: { indexPath: number[] node: T value: string }) => boolean \| void }, ) => T
getPreviousSibling Gets the previous non-disabled sibling of the node at the index path. indexPath:Array of indices representing the path to the node	( indexPath: number[], ) => T
getSiblingNodes Gets all sibling nodes of the node at the index path. indexPath:Array of indices representing the path to the node	( indexPath: number[], ) => Array<T>
getValue Gets the value of the node at the specified index path. indexPath:Array of indices representing the path to the node	( indexPath: number[], ) => string
getValuePath Gets the path of values from root to the specified index path. indexPath:Array of indices representing the path to the node	( indexPath: number[], ) => string[]
getValues Gets all values in the tree, excluding the root node. rootNode:The root node to start from	( rootNode?: T, ) => string[]
groupChildren Groups children of a parent node by a specified key. parentIndexPath:Index path of the parent node whose children to group. Pass `[]` for root-level children. groupBy:Function that determines the group key for each child node sortGroups:Optional array of group keys defining order, or comparator function to sort the groups. By default, groups are sorted by first occurrence in the tree (insertion order)	( parentIndexPath: IndexPath, groupBy: ( node: T, index: number, ) => string, sortGroups?: \| string[] \| (( a: { items: Array<{ indexPath: IndexPath node: T }> key: string }, b: { items: Array<{ indexPath: IndexPath node: T }> key: string }, ) => number), ) => GroupedTreeNode<T>[]

insertAfter Inserts nodes after the node at the specified index path. indexPath:Array of indices representing the insertion point nodes:Array of nodes to insert	( indexPath: number[], nodes: Array<T>, ) => any
insertBefore Inserts nodes before the node at the specified index path. indexPath:Array of indices representing the insertion point nodes:Array of nodes to insert	( indexPath: number[], nodes: Array<T>, ) => any
isBranchNode Checks if a node is a branch node (has children or can have children). node:The node to check	( node: T, ) => boolean
isEqual Compares this tree collection with another for deep equality. other:The other tree collection to compare with	( other: TreeCollection<T>, ) => boolean
isRootNode Checks if a node is the root node. node:The node to check	( node: T, ) => boolean
isSameNode Checks if two nodes are the same by comparing their values. node:First node to compare other:Second node to compare	( node: T, other: T, ) => boolean
move Moves nodes from one location to another in the tree. fromIndexPaths:Array of index paths to move from toIndexPath:Index path to move to	( fromIndexPaths: Array< number[] >, toIndexPath: number[], ) => any
remove Removes nodes at the specified index paths. indexPaths:Array of index paths to remove	( indexPaths: Array<number[]>, ) => any
replace Replaces the node at the specified index path. indexPath:Array of indices representing the path to the node node:The new node to replace with	( indexPath: number[], node: T, ) => any
replaceChildren Replaces the children for the node at the specified index path. indexPath:Array of indices representing the path to the node children:Array of child nodes to set on the target node	( indexPath: number[], children: Array<T>, ) => any
rootNode The root tree node.	T
sort Sorts values according to their tree order. values:Array of values to sort	( values: string[], ) => string[]
stringify Converts a node value to its string representation.	( value: string, ) => string
stringifyNode Converts a node to its string representation. Uses options.nodeLabel if provided, otherwise falls back to default behavior: uses `node.text`, or `node.value` if `node.text` is not available.	( T, ) => string
toJSON Serializes the tree to a JSON-compatible array of values.	() => string[]
visit Visits all nodes in the tree with optional skip functionality. opts:Options for visiting nodes, including skip predicate	(opts: { onEnter?: ( node: T, indexPath: number[], ) => void \| 'skip' \| 'stop' onLeave?: ( node: T, indexPath: number[], ) => void \| 'stop' reuseIndexPath?: boolean skip?: (args: { indexPath: number[] node: T value: string }) => boolean \| void }) => void

Type

(
  indexPath: number[],
) => T

Description

Gets the node at the specified index path.

indexPath:Array of indices representing the path to the node

contains

Type

(
  parentIndexPath: number[],
  valueIndexPath: number[],
) => boolean

Description

Checks if a parent index path contains a child index path.

parentIndexPath:The parent path
valueIndexPath:The child path to check

copy

Type

(
  rootNode: T,
) => any

Description

Creates a new tree collection with the same options but different root node.

rootNode:The new root node for the copied collection

filter

Type

(
  predicate: (
    node: T,
    indexPath: number[],
  ) => boolean,
) => any

Description

Filters the tree keeping only nodes that match the predicate.

predicate:Function to test each node

findNode

Type

(
  value: string,
  rootNode?: T,
) => T

Description

Finds the first node with the specified value.

value:The value to search for
rootNode:The root node to start searching from

findNodeBy

Type

(
  predicate: (
    node: T,
    indexPath: number[],
  ) => boolean,
  rootNode?: T,
) => T

findNodes

Type

(
  values: string[],
  rootNode?: T,
) => Array<T>

Description

Finds all nodes with values matching the provided array.

values:Array of values to search for
rootNode:The root node to start searching from

flatten

Type

(
  rootNode?: T,
) => Array<
  T & {
    _children: number[]
    _index: number
    _parent: number
  }
>

Description

Flattens the tree into an array with parent/child relationships.

rootNode:The root node to start flattening from

getBranchValues

Type

(
  rootNode?: T,
  opts?: {
    skip?: (args: {
      indexPath: number[]
      node: T
      value: string
    }) => boolean | void
  } & {
    depth?:
      | number
      | ((
          nodeDepth: number,
        ) => boolean)
  },
) => string[]

Description

Gets all branch node values with optional depth filtering.

rootNode:The root node to start from
opts:Options for skipping nodes and filtering by depth

getDepth

Type

(
  value: string,
) => number

Description

Gets the depth of a node with the specified value.

value:The value to find the depth for

getDescendantNodes

Type

(
  valueOrIndexPath?:
    | string
    | number[],
  options?: T & {
    disabled?: boolean
    id?: string
    onUnregister?: (
      index: number,
    ) => void
    requireContext?: boolean
  },
) => Array<T>

Description

Gets all descendant nodes of the specified node.

valueOrIndexPath:Either a node value or index path
options:Options for controlling which descendants to include

getDescendantValues

Type

(
  valueOrIndexPath:
    | string
    | number[],
  options?: T & {
    disabled?: boolean
    id?: string
    onUnregister?: (
      index: number,
    ) => void
    requireContext?: boolean
  },
) => string[]

Description

Gets all descendant values of the specified node.

valueOrIndexPath:Either a node value or index path
options:Options for controlling which descendants to include

getFirstNode

Type

(
  rootNode?: T,
) => T

Description

Gets the first non-disabled node in the tree.

rootNode:The root node to start searching from

getIndexPath

Type

(
  value: string,
) => number[]

Description

Gets the index path for a node with the specified value.

value:The value to find the index path for

getLastNode

Type

(
  rootNode?: T,
  opts?: {
    skip?: (args: {
      indexPath: number[]
      node: T
      value: string
    }) => boolean | void
  },
) => T

Description

Gets the last non-disabled node in the tree.

rootNode:The root node to start searching from
opts:Options for skipping nodes during traversal

getNextNode

Type

(
  value: string,
  opts?: {
    skip?: (args: {
      indexPath: number[]
      node: T
      value: string
    }) => boolean | void
  },
) => T

Description

Gets the next node after the one with the specified value.

value:The value to find the next node from
opts:Options for skipping nodes during traversal

getNextSibling

Type

(
  indexPath: number[],
) => T

Description

Gets the next non-disabled sibling of the node at the index path.

indexPath:Array of indices representing the path to the node

getNodeChildren

Type

(
  node: T,
) => Array<T>

Description

Returns all child nodes for this node. Uses options.nodeToChildren if provided, otherwise falls back to default behavior.

getNodeChildrenCount

Type

(
  node: T,
) => number

Description

Gets the number of children for a node, supporting lazy loading scenarios. Uses options.nodeToChildrenCount if provided, otherwise falls back to default behavior.

node:The node to get children count for

getNodeDisabled

Type

(
  node: T,
) => boolean

Description

Checks if a node is disabled. Uses options.isNodeDisabled if provided, otherwise falls back to default behavior.

node:The node to check

getNodeValue

Type

(
  node: T,
) => string

Description

Gets the string value for a node. Uses options.nodeValue if provided, otherwise falls back to default behavior.

node:The node to get the value from

getParentNode

Type

(
  valueOrIndexPath:
    | string
    | number[],
) => T

Description

Gets the parent node of the specified node.

valueOrIndexPath:Either a node value or index path

getParentNodes

Type

(
  valueOrIndexPath:
    | string
    | number[],
) => Array<T>

Description

Gets all parent nodes from root to the specified node.

valueOrIndexPath:Either a node value or index path

getPreviousNode

Type

(
  value: string,
  opts?: {
    skip?: (args: {
      indexPath: number[]
      node: T
      value: string
    }) => boolean | void
  },
) => T

Description

Gets the previous node before the one with the specified value.

value:The value to find the previous node from
opts:Options for skipping nodes during traversal

getPreviousSibling

Type

(
  indexPath: number[],
) => T

Description

Gets the previous non-disabled sibling of the node at the index path.

indexPath:Array of indices representing the path to the node

getSiblingNodes

Type

(
  indexPath: number[],
) => Array<T>

Description

Gets all sibling nodes of the node at the index path.

indexPath:Array of indices representing the path to the node

getValue

Type

(
  indexPath: number[],
) => string

Description

Gets the value of the node at the specified index path.

indexPath:Array of indices representing the path to the node

getValuePath

Type

(
  indexPath: number[],
) => string[]

Description

Gets the path of values from root to the specified index path.

indexPath:Array of indices representing the path to the node

getValues

Type

(
  rootNode?: T,
) => string[]

Description

Gets all values in the tree, excluding the root node.

rootNode:The root node to start from

groupChildren

Type

(
  parentIndexPath: IndexPath,
  groupBy: (
    node: T,
    index: number,
  ) => string,
  sortGroups?:
    | string[]
    | ((
        a: {
          items: Array<{
            indexPath: IndexPath
            node: T
          }>
          key: string
        },
        b: {
          items: Array<{
            indexPath: IndexPath
            node: T
          }>
          key: string
        },
      ) => number),
) => GroupedTreeNode<T>[]

Description

Groups children of a parent node by a specified key.

parentIndexPath:Index path of the parent node whose children to group. Pass [] for root-level children.
groupBy:Function that determines the group key for each child node
sortGroups:Optional array of group keys defining order, or comparator function to sort the groups. By default, groups are sorted by first occurrence in the tree (insertion order)

insertAfter

Type

(
  indexPath: number[],
  nodes: Array<T>,
) => any

Description

Inserts nodes after the node at the specified index path.

indexPath:Array of indices representing the insertion point
nodes:Array of nodes to insert

insertBefore

Type

(
  indexPath: number[],
  nodes: Array<T>,
) => any

Description

Inserts nodes before the node at the specified index path.

indexPath:Array of indices representing the insertion point
nodes:Array of nodes to insert

isBranchNode

Type

(
  node: T,
) => boolean

Description

Checks if a node is a branch node (has children or can have children).

node:The node to check

isEqual

Type

(
  other: TreeCollection<T>,
) => boolean

Description

Compares this tree collection with another for deep equality.

other:The other tree collection to compare with

isRootNode

Type

(
  node: T,
) => boolean

Description

Checks if a node is the root node.

node:The node to check

isSameNode

Type

(
  node: T,
  other: T,
) => boolean

Description

Checks if two nodes are the same by comparing their values.

node:First node to compare
other:Second node to compare

move

Type

(
  fromIndexPaths: Array<
    number[]
  >,
  toIndexPath: number[],
) => any

Description

Moves nodes from one location to another in the tree.

fromIndexPaths:Array of index paths to move from
toIndexPath:Index path to move to

remove

Type

(
  indexPaths: Array<number[]>,
) => any

Description

Removes nodes at the specified index paths.

indexPaths:Array of index paths to remove

replace

Type

(
  indexPath: number[],
  node: T,
) => any

Description

Replaces the node at the specified index path.

indexPath:Array of indices representing the path to the node
node:The new node to replace with

replaceChildren

Type

(
  indexPath: number[],
  children: Array<T>,
) => any

Description

Replaces the children for the node at the specified index path.

indexPath:Array of indices representing the path to the node
children:Array of child nodes to set on the target node

rootNode

Type

Description

The root tree node.

sort

Type

(
  values: string[],
) => string[]

Description

Sorts values according to their tree order.

values:Array of values to sort

stringify

Type

(
  value: string,
) => string

Description

Converts a node value to its string representation.

stringifyNode

Type

(
  T,
) => string

Description

Converts a node to its string representation. Uses options.nodeLabel if provided, otherwise falls back to default behavior: uses node.text, or node.value if node.text is not available.

toJSON

Type

() => string[]

Description

Serializes the tree to a JSON-compatible array of values.

visit

Type

(opts: {
  onEnter?: (
    node: T,
    indexPath: number[],
  ) => void | 'skip' | 'stop'
  onLeave?: (
    node: T,
    indexPath: number[],
  ) => void | 'stop'
  reuseIndexPath?: boolean
  skip?: (args: {
    indexPath: number[]
    node: T
    value: string
  }) => boolean | void
}) => void

Description

Visits all nodes in the tree with optional skip functionality.

opts:Options for visiting nodes, including skip predicate

Element API

q-tree-label

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.

Attribute / Property	Value
`class`	'qui-tree__label'
`data-size`	'sm' \| 'md'
`data-tree-part`	'label'

q-tree-branch

Attribute / Property	Value
`class`	'qui-tree__branch-root'
`data-branch`	string
`data-depth`	number
`data-disabled`
`data-loading`
`data-ownedby`	string
`data-path`	string
`data-selected`
`data-state`	\| 'open' \| 'closed'
`data-tree-part`	'branch'
`data-value`	string
`hidden`	boolean
`style`	CSSProperties

class

Value

'qui-tree__branch-root'

data-branch

Value

string

data-depth

Value

number

data-disabled

Value

data-loading

Value

data-ownedby

Value

string

data-path

Value

string

data-selected

Value

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

q-tree-branch-node

Attribute / Property	Value
`class`	'qui-tree__node-root'
`data-depth`	number
`data-disabled`
`data-focus`
`data-loading`
`data-path`	string
`data-selected`
`data-size`	'sm' \| 'md'
`data-state`	\| 'open' \| 'closed'
`data-tree-part`	'branch-node'
`data-value`	string
`tabIndex`	-1 \| 0

class

Value

'qui-tree__node-root'

data-depth

Value

number

data-disabled

Value

data-focus

Value

data-loading

Value

data-path

Value

string

data-selected

Value

data-size

Value

'sm' | 'md'

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch-node'

data-value

Value

string

tabIndex

Value

-1 | 0

q-tree-branch-trigger

Prop	Type	Default
icon	\| LucideIconData \| string	ChevronRight

icon

Type

| LucideIconData
| string

Description

Attribute / Property	Value
`class`	'qui-tree__branch-trigger'
`data-disabled`
`data-loading`
`data-state`	\| 'open' \| 'closed'
`data-tree-part`	'branch-trigger'
`data-value`	string

class

Value

'qui-tree__branch-trigger'

data-disabled

Value

data-loading

Value

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch-trigger'

data-value

Value

string

q-tree-branch-content

Prop	Type
id HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-tree__branch-content'
`data-depth`	number
`data-path`	string
`data-tree-part`	'branch-content'
`data-value`	string

class

Value

'qui-tree__branch-content'

data-depth

Value

number

data-path

Value

string

data-tree-part

Value

'branch-content'

data-value

Value

string

q-tree-branch-indent-guide

Attribute / Property	Value
`data-depth`	number
`data-tree-part`	'branch-indent-guide'
`style`	CSSProperties

q-tree-leaf-node

Attribute / Property	Value
`class`	'qui-tree__node-root'
`data-depth`	number
`data-disabled`
`data-focus`
`data-ownedby`	string
`data-path`	string
`data-selected`
`data-size`	'sm' \| 'md'
`data-tree-part`	'leaf-node'
`data-value`	string
`hidden`	boolean
`style`	CSSProperties
`tabIndex`	-1 \| 0

class

Value

'qui-tree__node-root'

data-depth

Value

number

data-disabled

Value

data-focus

Value

data-ownedby

Value

string

data-path

Value

string

data-selected

Value

data-size

Value

'sm' | 'md'

data-tree-part

Value

'leaf-node'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

tabIndex

Value

-1 | 0

q-tree-node-checkbox

Attribute / Property	Value
`class`	'qui-checkbox__control qui-checkmark__root'
`data-checkmark-part`	'root'
`data-disabled`
`data-state`	\| 'checked' \| 'indeterminate' \| 'unchecked'
`data-tree-part`	'node-checkbox'
`tabIndex`	-1

class

Value

'qui-checkbox__control qui-checkmark__root'

data-checkmark-part

Value

'root'

data-disabled

Value

data-state

Value

| 'checked'
| 'indeterminate'
| 'unchecked'

data-tree-part

Value

'node-checkbox'

tabIndex

Value

-1

q-tree-node-action

Prop	Type	Default
icon Lucide icon to display inside the button.	\| LucideIconData \| string
size The size of the button and its icon.	\| 'sm' \| 'md' \| 'lg'	'md'

icon

Type

| LucideIconData
| string

Description

Lucide icon to display inside the button.

size

Type

| 'sm'
| 'md'
| 'lg'

Description

The size of the button and its icon.

Attribute / Property	Value
`class`	'qui-tree__node-action'
`data-disabled`
`data-focus`
`data-selected`
`data-tree-part`	'node-action'

class

Value

'qui-tree__node-action'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-action'

q-tree-node-indicator

Attribute / Property	Value
`class`	'qui-tree__node-indicator'
`data-disabled`
`data-focus`
`data-selected`
`data-tree-part`	'node-indicator'
`hidden`	boolean

class

Value

'qui-tree__node-indicator'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-indicator'

hidden

Value

boolean

q-tree-node-icon

Prop	Type
icon	\| LucideIconData \| string

icon

Type

| LucideIconData
| string

Attribute / Property	Value
`class`	'qui-tree__node-icon'
`data-disabled`
`data-focus`
`data-selected`
`data-size`	'sm' \| 'md'
`data-tree-part`	'node-icon'

class

Value

'qui-tree__node-icon'

data-disabled

Value

data-focus

Value

data-selected

Value

data-size

Value

'sm' | 'md'

data-tree-part

Value

'node-icon'

q-tree-node-text

Template Directives

q-tree-branch-template

Structural directive that defines the template used to render leaf nodes in a tree. Apply this to an ng-template to customize how branch nodes (nodes with children) are displayed. Note that this template will only customize the content of the node. The parent <q-tree-nodes> component renders the branch children internally.

Prop	Type
rootNode The root node of the tree. Used for type narrowing of the template guard. Learn more	T

rootNode

Type

Description

The root node of the tree. Used for type narrowing of the template guard. Learn more

q-tree-leaf-template

Structural directive that defines the template used to render leaf nodes in a tree. Apply this to an ng-template to customize how leaf nodes (nodes without children) are displayed.

Prop	Type
rootNode The root node of the tree. Used for type narrowing of the template guard. Learn more	T

rootNode

Type

Description

The root node of the tree. Used for type narrowing of the template guard. Learn more

Use this directive on an ng-template to customize the rendering of leaf nodes within q-tree-nodes.

Last updated on May 23, 2026 by Ryan Bower

Tooltip

Tree

Overview

Examples

Node Shorthand

Nodes

Default Expanded

Checkbox Trees

Checkbox selection state

Disabled Nodes

Filtering

Links

Sizes

Add / Remove nodes

Explorer

Component Anatomy

API

q-tree-root

q-tree-nodes

TreeCollection

Constructor

Element API

q-tree-label

q-tree-branch

q-tree-branch-node

q-tree-branch-trigger

q-tree-branch-content

q-tree-branch-indent-guide

q-tree-leaf-node

q-tree-node-checkbox

q-tree-node-action

q-tree-node-indicator

q-tree-node-icon

q-tree-node-text

Template Directives

q-tree-branch-template

q-tree-leaf-template