Side Nav

The side navigation provides a consistent, easy-to-scan way for users to move through major sections of an application. It stays visible as users browse, giving them a clear understanding of where they are and what options are available.

import {SideNavModule} from "@qualcomm-ui/angular/side-nav"

Overview

The side nav is an extension of our tree component.

The Side Navigation relies on the TreeCollection class to manage its items. Refer to the API below for details.
Like with the tree, Side Navigations are composed of nodes, which are objects that describe the navigation data. There are two types of nodes:
- A branch node has children.
- A leaf node does not have any children.
Each node has a value (unique identifier used for 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 keys can be customized via the TreeCollection constructor.

Examples

Node Shorthand

We expose the <q-side-nav-nodes> shorthand for rendering nested nodes. Use the following directives to customize the tree nodes:

<ng-template
  let-branch
  q-side-nav-branch-template
  [rootNode]="collection.rootNode"
>
  <div q-side-nav-branch-node>
    <!-- ... -->
  </div>
</ng-template>

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

Notifications

Dashboard

AI Studio

Account

<div q-side-nav-root [collection]="collection">
  <div q-side-nav-header>
    <div q-side-nav-header-logo>
      <q-logo />
    </div>
    <div q-side-nav-header-title>Qualcomm</div>
  </div>

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

      <ng-template
        let-leaf
        q-side-nav-leaf-template
        [rootNode]="collection.rootNode"
      >
        <div q-side-nav-leaf-node>
          <div q-side-nav-node-indicator></div>
          @if (leaf.node.icon) {
            <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
          }
          <span q-side-nav-node-text>{{ leaf.node.text }}</span>
        </div>
      </ng-template>
    </q-side-nav-nodes>
  }
</div>

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.

Grouping

Group nodes using the collection's groupChildren method. This should be called on the top-level node of your SideNav. Nested groups are not supported.

Notifications

Settings

Main menu

Dashboard

AI Studio

Data Analysis

Integrations

Administration

Profile

Security

Billing

<div q-side-nav-root [collection]="collection">
  <div q-side-nav-header>
    <div q-side-nav-header-logo>
      <q-logo />
    </div>
    <div q-side-nav-header-title>Qualcomm</div>
  </div>

  @for (group of groups; track group.key) {
    <div q-side-nav-group>
      <div q-side-nav-divider></div>

      @if (group.key !== "ungrouped") {
        <div q-side-nav-group-label>{{ group.key }}</div>
      }

      @for (
        item of group.items;
        track collection.getNodeValue(item.node)
      ) {
        <q-side-nav-nodes [indexPath]="item.indexPath" [node]="item.node">
          <ng-template
            let-branch
            q-side-nav-branch-template
            [rootNode]="collection.rootNode"
          >
            <div q-side-nav-branch-node>
              <div q-side-nav-node-indicator></div>
              @if (branch.node.icon) {
                <svg
                  q-side-nav-node-icon
                  [qIcon]="branch.node.icon"
                ></svg>
              }
              <span q-side-nav-node-text>{{ branch.node.text }}</span>
              <div q-side-nav-branch-trigger></div>
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-side-nav-leaf-template
            [rootNode]="collection.rootNode"
          >
            <div q-side-nav-leaf-node>
              <div q-side-nav-node-indicator></div>
              @if (leaf.node.icon) {
                <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
              }
              <span q-side-nav-node-text>{{ leaf.node.text }}</span>
            </div>
          </ng-template>
        </q-side-nav-nodes>
      }
    </div>
  }
</div>

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.

Notifications

Dashboard

AI Studio

Account

Profile

Security

Billing

<div
  q-side-nav-root
  [collection]="collection"
  [defaultExpandedValue]="['account']"
>

Disabled Nodes

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

Notifications

Dashboard

AI Studio

Account

Profile

Security

Billing

import {Component} from "@angular/core"
import {
  Bell,
  CircleUser,
  CreditCard,
  LayoutDashboard,
  Network,
  ShieldCheck,
  User,
} from "lucide-angular"

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

import {QLogoComponent} from "./q-logo.component"

interface SideNavItem {
  disabled?: boolean
  icon?: string
  id: string
  nodes?: SideNavItem[]
  text: string
}

const collection = createTreeCollection<SideNavItem>({
  nodeChildren: "nodes",
  nodeText: (node) => node.text,
  nodeValue: (node) => node.id,
  rootNode: {
    id: "ROOT",
    nodes: [
      {
        icon: "Bell",
        id: "notifications",
        text: "Notifications",
      },
      {
        disabled: true,
        icon: "LayoutDashboard",
        id: "dashboard",
        text: "Dashboard",
      },
      {
        icon: "Network",
        id: "ai-studio",
        text: "AI Studio",
      },
      {
        icon: "CircleUser",
        id: "account",
        nodes: [
          {
            icon: "User",
            id: "profile",
            text: "Profile",
          },
          {
            icon: "ShieldCheck",
            id: "security",
            text: "Security",
          },
          {
            icon: "CreditCard",
            id: "billing",
            text: "Billing",
          },
        ],
        text: "Account",
      },
    ],
    text: "",
  },
})

@Component({
  imports: [SideNavModule, IconDirective, QLogoComponent],
  providers: [
    provideIcons({
      Bell,
      CircleUser,
      CreditCard,
      LayoutDashboard,
      Network,
      ShieldCheck,
      User,
    }),
  ],
  selector: "side-nav-disabled-node-demo",
  template: `
    <div class="flex justify-center">
      <div
        q-side-nav-root
        [collection]="collection"
        [defaultExpandedValue]="['account']"
      >
        <div q-side-nav-header>
          <div q-side-nav-header-logo>
            <q-logo />
          </div>
          <div q-side-nav-header-title>Qualcomm</div>
        </div>

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

            <ng-template
              let-leaf
              q-side-nav-leaf-template
              [rootNode]="collection.rootNode"
            >
              <div q-side-nav-leaf-node>
                <div q-side-nav-node-indicator></div>
                @if (leaf.node.icon) {
                  <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
                }
                <span q-side-nav-node-text>{{ leaf.node.text }}</span>
              </div>
            </ng-template>
          </q-side-nav-nodes>
        }
      </div>
    </div>
  `,
})
export class SideNavDisabledNodeDemo {
  collection = collection
}

Collapsed

Side Nav can be collapsed to render only the top-level icons.

The open state of the panel can be controlled using the open, openChanged and defaultOpen inputs. These inputs follow our controlled state pattern.

Notifications

Dashboard

AI Studio

Account

<div
  q-side-nav-root
  [collection]="collection"
  [open]="open()"
  (openChanged)="open.set($event)"
>
  <div q-side-nav-header>
    <div q-side-nav-header-logo>
      <q-logo />
    </div>
    <div q-side-nav-header-title>Qualcomm</div>
    <button q-side-nav-collapse-trigger></button>
  </div>

  @for (
    node of collection.rootNode.nodes;
    let i = $index;
    track collection.getNodeValue(node)
  ) {
    <q-side-nav-nodes [indexPath]="[i]" [node]="node">
      <ng-template
        let-branch
        q-side-nav-branch-template
        [rootNode]="collection.rootNode"
      >
        <div q-side-nav-branch-node [attr.aria-label]="branch.node.text">
          <div q-side-nav-node-indicator></div>
          @if (branch.node.icon) {
            <svg q-side-nav-node-icon [qIcon]="branch.node.icon"></svg>
          }
          <span q-side-nav-node-text>{{ branch.node.text }}</span>
          <div q-side-nav-branch-trigger></div>
        </div>
      </ng-template>

      <ng-template
        let-leaf
        q-side-nav-leaf-template
        [rootNode]="collection.rootNode"
      >
        <div q-side-nav-leaf-node [attr.aria-label]="leaf.node.text">
          <div q-side-nav-node-indicator></div>
          @if (leaf.node.icon) {
            <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
          }
          <span q-side-nav-node-text>{{ leaf.node.text }}</span>
        </div>
      </ng-template>
    </q-side-nav-nodes>
  }
</div>

Filtering

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

Notifications

Settings

Main menu

Dashboard

AI Studio

Data Analysis

Integrations

Administration

Profile

Security

Billing

<div
  q-side-nav-root
  [collection]="collection()"
  [expandedValue]="expanded()"
  (expandedValueChanged)="expanded.set($event.expandedValue)"
>
  <div q-side-nav-header>
    <div q-side-nav-header-logo>
      <q-logo />
    </div>
    <div q-side-nav-header-title>Qualcomm</div>
  </div>

  <hr q-side-nav-divider />

  <q-text-input
    aria-label="Search filter"
    placeholder="Search"
    q-side-nav-filter-input
    size="sm"
    startIcon="Search"
    style="margin-bottom: 16px"
    [ngModel]="query()"
    (ngModelChange)="search($event)"
  />

  @for (group of groups(); track group.key) {
    <div q-side-nav-group>
      <hr q-side-nav-divider />

      @if (group.key !== "ungrouped") {
        <div q-side-nav-group-label>{{ group.key }}</div>
      }

      @for (
        item of group.items;
        track collection().getNodeValue(item.node)
      ) {
        <q-side-nav-nodes [indexPath]="item.indexPath" [node]="item.node">
          <ng-template
            let-branch
            q-side-nav-branch-template
            [rootNode]="collection().rootNode"
          >
            <div q-side-nav-branch-node>
              @if (branch.node.icon) {
                <svg
                  q-side-nav-node-icon
                  [qIcon]="branch.node.icon"
                ></svg>
              }
              <span q-side-nav-node-text>{{ branch.node.text }}</span>
              <div q-side-nav-branch-trigger></div>
            </div>
          </ng-template>

          <ng-template
            let-leaf
            q-side-nav-leaf-template
            [rootNode]="collection().rootNode"
          >
            <div q-side-nav-leaf-node>
              <div q-side-nav-node-indicator></div>
              @if (leaf.node.icon) {
                <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
              }
              <span q-side-nav-node-text>{{ leaf.node.text }}</span>
            </div>
          </ng-template>
        </q-side-nav-nodes>
      }
    </div>
  }
</div>

Links

Side Nav nodes can be links. Apply the q-side-nav-leaf-node directive to an anchor element with routerLink to create navigable links.

Components

Pagination

Side Nav

Switch

<a q-side-nav-leaf-node [routerLink]="leaf.node.pathname">
  <div q-side-nav-node-indicator></div>
  <span q-side-nav-node-text>{{ leaf.node.text }}</span>
</a>

Surface

Use the surface input to change the background color of the Side Nav.

Notifications

Settings

Main menu

Dashboard

AI Studio

Data Analysis

Integrations

Administration

Profile

Security

Billing

import {Component} from "@angular/core"

import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {SideNavModule} from "@qualcomm-ui/angular/side-nav"

import {groupedCollection, groupedIcons} from "./grouped-items"
import {QLogoComponent} from "./q-logo.component"

@Component({
  imports: [SideNavModule, IconDirective, QLogoComponent],
  providers: [provideIcons(groupedIcons)],
  selector: "side-nav-surface-demo",
  template: `
    <div class="flex justify-center">
      <div q-side-nav-root surface="secondary" [collection]="collection">
        <div q-side-nav-header>
          <div q-side-nav-header-logo>
            <q-logo />
          </div>
          <div q-side-nav-header-title>Qualcomm</div>
        </div>

        @for (group of groups; track group.key) {
          <div q-side-nav-group>
            <div q-side-nav-divider></div>

            @if (group.key !== "ungrouped") {
              <div q-side-nav-group-label>{{ group.key }}</div>
            }

            @for (
              item of group.items;
              track collection.getNodeValue(item.node)
            ) {
              <q-side-nav-nodes [indexPath]="item.indexPath" [node]="item.node">
                <ng-template
                  let-branch
                  q-side-nav-branch-template
                  [rootNode]="collection.rootNode"
                >
                  <div q-side-nav-branch-node>
                    <div q-side-nav-node-indicator></div>
                    @if (branch.node.icon) {
                      <svg
                        q-side-nav-node-icon
                        [qIcon]="branch.node.icon"
                      ></svg>
                    }
                    <span q-side-nav-node-text>{{ branch.node.text }}</span>
                    <div q-side-nav-branch-trigger></div>
                  </div>
                </ng-template>

                <ng-template
                  let-leaf
                  q-side-nav-leaf-template
                  [rootNode]="collection.rootNode"
                >
                  <div q-side-nav-leaf-node>
                    <div q-side-nav-node-indicator></div>
                    @if (leaf.node.icon) {
                      <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
                    }
                    <span q-side-nav-node-text>{{ leaf.node.text }}</span>
                  </div>
                </ng-template>
              </q-side-nav-nodes>
            }
          </div>
        }
      </div>
    </div>
  `,
})
export class SideNavSurfaceDemo {
  collection = groupedCollection

  groups = this.collection.groupChildren(
    [],
    (node) => node.group ?? "ungrouped",
    ["ungrouped", "Main menu"],
  )
}

Tooltips

Consider wrapping collapsed nodes with the Tooltip component to provide context about each item. This is also useful for describing disabled nodes.

<div q-tooltip>
  <span q-tooltip-trigger>
    <div q-side-nav-leaf-node>
      <div q-side-nav-node-indicator></div>
      @if (leaf.node.icon) {
        <svg q-side-nav-node-icon [qIcon]="leaf.node.icon"></svg>
      }
      <span q-side-nav-node-text>{{ leaf.node.text }}</span>
    </div>
  </span>
  {{ leaf.node.tooltip || leaf.node.text }}
</div>

API

q-side-nav-root

Prop	Type	Default
collection The tree collection data	TreeCollection
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
defaultOpen The initial open state of the side navigation when rendered. Use when you don't need to control the open state of the collapsible.	boolean	true
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'
disabled Whether the side navigation collapse behavior is disabled.	boolean
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[]>
open The controlled open state of the side navigation	boolean
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.	(state: { checked: \| boolean \| 'indeterminate' depth: number disabled: boolean expanded: boolean focused: boolean id: string indexPath: number[] isBranch: boolean loading: boolean node: T selected: boolean textId: string value: string valuePath: string[] }) => boolean
surface The background color of the side navigation.	\| 'primary' \| 'secondary'	'primary'
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
(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[] }
(openChanged) Called when the side navigation opens or closes	boolean
(selectedValueChanged) Called when the selection changes	{ focusedValue: string selectedNodes: Array<T> selectedValue: string[] }

collection

Type

TreeCollection

Description

The tree collection data

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.

defaultOpen

Type

boolean

Description

The initial open state of the side navigation when rendered. Use when you don't need to control the open state of the collapsible.

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.

disabled

Type

boolean

Description

Whether the side navigation collapse behavior is disabled.

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.

open

Type

boolean

Description

The controlled open state of the side navigation

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

(state: {
  checked:
    | boolean
    | 'indeterminate'
  depth: number
  disabled: boolean
  expanded: boolean
  focused: boolean
  id: string
  indexPath: number[]
  isBranch: boolean
  loading: boolean
  node: T
  selected: boolean
  textId: string
  value: string
  valuePath: string[]
}) => boolean

Description

Callback function that determines whether a node should be hidden.

surface

Type

| 'primary'
| 'secondary'

Description

The background color of the side navigation.

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.

(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

(openChanged)

Type

boolean

Description

Called when the side navigation opens or closes

(selectedValueChanged)

Type

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

Description

Called when the selection changes

Attribute / Property	Value
`class`	'qui-side-nav__root'
`data-surface`	\| 'primary' \| 'secondary'
`data-tree-part`	'root'
`tabIndex`	-1

class

Value

'qui-side-nav__root'

data-surface

Value

| 'primary'
| 'secondary'

data-tree-part

Value

'root'

tabIndex

Value

-1

q-side-nav-nodes

Prop	Type
indexPath ^* The index path of the tree node	number[]
node ^* The tree node	T
renderBranch	TemplateRef<any>
renderLeaf	TemplateRef<any>
showIndentGuide	boolean

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

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

Attribute / Property	Value
`class`	'qui-side-nav__header'
`data-side-nav-part`	'header'
`data-state`	\| 'open' \| 'closed' \| 'closing'

class

Value

'qui-side-nav__header'

data-side-nav-part

Value

'header'

data-state

Value

| 'open'
| 'closed'
| 'closing'

Attribute / Property	Value
`class`	'qui-side-nav__header-logo'
`data-side-nav-part`	'header-logo'
`hidden`	boolean

Attribute / Property	Value
`class`	'qui-side-nav__header-title'
`data-side-nav-part`	'header-title'
`hidden`	boolean

Attribute / Property	Value
`class`	'qui-side-nav__header-action'
`data-side-nav-part`	'header-action'
`data-state`	\| 'open' \| 'closed' \| 'closing'

class

Value

'qui-side-nav__header-action'

data-side-nav-part

Value

'header-action'

data-state

Value

| 'open'
| 'closed'
| 'closing'

q-side-nav-collapse-trigger

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-side-nav__collapse-trigger'
`data-disabled`
`data-side-nav-part`	'trigger'
`data-state`	\| 'open' \| 'closed' \| 'closing'

class

Value

'qui-side-nav__collapse-trigger'

data-disabled

Value

data-side-nav-part

Value

'trigger'

data-state

Value

| 'open'
| 'closed'
| 'closing'

q-side-nav-group

Attribute / Property	Value
`class`	'qui-side-nav__group'

q-side-nav-group-label

Attribute / Property	Value
`class`	'qui-side-nav__group-label'

q-side-nav-divider

Attribute / Property	Value
`class`	'qui-side-nav__divider'

q-side-nav-branch

Attribute / Property	Value
`class`	'qui-side-nav__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-side-nav__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-side-nav-branch-node

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

class

Value

'qui-side-nav__node-root'

data-depth

Value

number

data-disabled

Value

data-focus

Value

data-loading

Value

data-path

Value

string

data-selected

Value

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch-node'

data-value

Value

string

tabIndex

Value

-1 | 0

q-side-nav-branch-trigger

Prop	Type	Default
icon The icon to display. This rotates by 180deg when the branch is expanded.	\| LucideIconData \| string	ChevronDown

icon

Type

| LucideIconData
| string

Description

The icon to display. This rotates by 180deg when the branch is expanded.

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

class

Value

'qui-side-nav__branch-trigger'

data-disabled

Value

data-loading

Value

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch-trigger'

data-value

Value

string

q-side-nav-branch-content

Prop	Type
id	string

Type

string

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

class

Value

'qui-side-nav__branch-content'

data-depth

Value

number

data-path

Value

string

data-tree-part

Value

'branch-content'

data-value

Value

string

q-side-nav-branch-indent-guide

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

q-side-nav-leaf-node

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

class

Value

'qui-side-nav__node-root'

data-depth

Value

number

data-disabled

Value

data-focus

Value

data-ownedby

Value

string

data-path

Value

string

data-selected

Value

data-tree-part

Value

'leaf-node'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

tabIndex

Value

-1 | 0

q-side-nav-node-icon

Attribute / Property	Value
`class`	'qui-side-nav__node-icon'
`data-disabled`
`data-focus`
`data-selected`
`data-tree-part`	'node-icon'

class

Value

'qui-side-nav__node-icon'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-icon'

q-side-nav-node-text

Attribute / Property	Value
`data-disabled`
`data-focus`
`data-selected`
`data-tree-part`	'node-text'

q-side-nav-node-indicator

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

class

Value

'qui-side-nav__node-indicator'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-indicator'

hidden

Value

boolean

q-side-nav-node-action

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

class

Value

'qui-side-nav__node-action'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-action'

q-side-nav-node-accessory

Attribute / Property	Value
`class`	'qui-side-nav__node-accessory'

q-side-nav-filter-input

Attribute / Property	Value
`class`	'qui-side-nav__filter-input'

Template Directives

q-side-nav-branch-template

Structural directive that defines the template used to render branch nodes in a side nav. 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-side-nav-nodes> component renders the branch children internally.

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

rootNode

Type

Description

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

q-side-nav-leaf-template

Structural directive that defines the template used to render leaf nodes in a side nav. 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.	T

rootNode

Type

Description

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

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

Last updated on Apr 24, 2026 by Ryan Bower

Select

Slider