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
TreeCollectionclass 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
branchnode has children. - A
leafnode does not have any children.
- A
- Each node has a
value(unique identifier used for expansion) and atext(display text).
Default object shape:
value(required): unique identifier for expansion/selectiontext(required): display textnodes(optional): child nodes for branchesdisabled(optional): prevents interaction whentrue
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><ng-template
let-leaf
q-side-nav-leaf-template
[rootNode]="collection.rootNode"
>
<div q-side-nav-leaf-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.
<nav q-side-nav-root [collection]="collection">
<header q-side-nav-header>
<div q-side-nav-header-logo>
<q-logo />
</div>
<div q-side-nav-header-title>Qualcomm</div>
</header>
@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>
}
</nav>
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.
<nav q-side-nav-root [collection]="collection">
<header q-side-nav-header>
<div q-side-nav-header-logo>
<q-logo />
</div>
<div q-side-nav-header-title>Qualcomm</div>
</header>
@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>
}
</nav>
Default Expanded
Expand nodes by default using the defaultExpandedValue input. Or use expandedValue and expandedValueChange to control the expansion manually. These inputs follow our controlled state pattern.
<nav
q-side-nav-root
[collection]="collection"
[defaultExpandedValue]="['account']"
>
Disabled Nodes
You can disable nodes by setting the disabled property on the node object.
import {Component} from "@angular/core"
import {
Bell,
CircleUser,
CreditCard,
LayoutDashboard,
Network,
ShieldCheck,
User,
} from "lucide-angular"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {SideNavModule} from "@qualcomm-ui/angular/side-nav"
import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
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">
<nav
q-side-nav-root
[collection]="collection"
[defaultExpandedValue]="['account']"
>
<header q-side-nav-header>
<div q-side-nav-header-logo>
<q-logo />
</div>
<div q-side-nav-header-title>Qualcomm</div>
</header>
@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>
}
</nav>
</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.
<nav
q-side-nav-root
[collection]="collection"
[open]="open()"
(openChanged)="open.set($event)"
>
<header 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>
</header>
@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>
<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>
}
</nav>
Filtering
Here's an example that filters the items using matchSorter.
<nav
q-side-nav-root
[collection]="collection()"
[expandedValue]="expanded()"
(expandedValueChanged)="expanded.set($event.expandedValue)"
>
<header q-side-nav-header>
<div q-side-nav-header-logo>
<q-logo />
</div>
<div q-side-nav-header-title>Qualcomm</div>
</header>
<hr q-side-nav-divider />
<q-text-input
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>
}
</nav>
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.
<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.
import {Component} from "@angular/core"
import {IconDirective} from "@qualcomm-ui/angular/icon"
import {SideNavModule} from "@qualcomm-ui/angular/side-nav"
import {provideIcons} from "@qualcomm-ui/angular-core/lucide"
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">
<nav q-side-nav-root surface="secondary" [collection]="collection">
<header q-side-nav-header>
<div q-side-nav-header-logo>
<q-logo />
</div>
<div q-side-nav-header-title>Qualcomm</div>
</header>
@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>
}
</nav>
</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 |
|---|---|---|
The tree collection data | ||
The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value. | string[] | |
The initial focused node value when rendered.
Use when you don't need to control the focused node value. | string | |
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 |
The initial selected node value when rendered.
Use when you don't need to control the selected node value. | string[] | |
The document's text/writing direction. | 'ltr' | 'rtl' | |
Whether the side navigation collapse behavior is disabled. | boolean | |
The controlled expanded node ids | string[] | |
Whether clicking on a branch should open it or not | boolean | true |
The value of the focused node | string | |
A root node to correctly resolve the Document in custom environments. i.e.,
Iframes, Electron. | () => | |
HTML id attribute. If omitted, a unique identifier will be generated for
accessibility. | string | |
When true, the component will not be rendered in the DOM until it becomes
visible or active. | boolean | false |
Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding. | (details: { | |
The controlled open state of the side navigation | boolean | |
The controlled selected node value | string[] | |
Whether the tree supports multiple selection | | 'multiple' | 'single' |
Callback function that determines whether a node should be hidden. | (state: { | |
The background color of the side navigation. | | 'primary' | 'primary' |
Whether the tree supports typeahead search | boolean | true |
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 |
Called when the tree is opened or closed | { | |
Called when the focused node changes | { | |
Called when a node finishes loading children | { | |
Called when loading children fails for one or more nodes | { | |
Called when the side navigation opens or closes | boolean | |
Called when the selection changes | { |
string[]
stringbooleanstring[]
'ltr' | 'rtl'
booleanstring[]
booleanstring() =>
| Node
| ShadowRoot
| Document
stringboolean(details: {
indexPath: number[]
node: T
signal: AbortSignal
valuePath: string[]
}) => Promise<any[]>
booleanstring[]
| 'multiple'
| 'single'
(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
| 'primary'
| 'secondary'
booleanboolean{
expandedNodes: Array<T>
expandedValue: string[]
focusedValue: string
}
{
focusedNode: T
focusedValue: string
}
{
collection: TreeCollection<T>
}
{
nodes: NodeWithError[]
}
boolean{
focusedValue: string
selectedNodes: Array<T>
selectedValue: string[]
}
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__root' |
data-part | 'root' |
data-scope | 'tree' |
data-surface | | 'primary' |
tabIndex | -1 |
class'qui-side-nav__root'data-part'root'data-scope'tree'data-surface| 'primary'
| 'secondary'
tabIndex-1
q-side-nav-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 |
|---|---|---|
Property key for accessing a node's children. | keyof T | "nodes" |
Function to determine the count of a node's children. | ( | |
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 | "disabled" |
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 | "text" |
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 | "value" |
The root node of the tree | T |
keyof T
(
node: T,
) => number
| keyof T
| ((node: T) => boolean)
| keyof T
| ((node: T) => string)
| keyof T
| ((node: T) => string)
T| Prop | Type |
|---|---|
Gets the node at the specified index path.
| ( |
Checks if a parent index path contains a child index path.
| ( |
Creates a new tree collection with the same options but different root node.
| ( |
Filters the tree keeping only nodes that match the predicate.
| ( |
Finds the first node with the specified value.
| ( |
( | |
Finds all nodes with values matching the provided array.
| ( |
Flattens the tree into an array with parent/child relationships.
| ( |
Gets all branch node values with optional depth filtering.
| ( |
Gets the depth of a node with the specified value.
| ( |
Gets all descendant nodes of the specified node.
| ( |
Gets all descendant values of the specified node.
| ( |
Gets the first non-disabled node in the tree.
| ( |
Gets the index path for a node with the specified value.
| ( |
Gets the last non-disabled node in the tree.
| ( |
Gets the next node after the one with the specified value.
| ( |
Gets the next non-disabled sibling of the node at the index path.
| ( |
Returns all child nodes for this node.
Uses options.nodeToChildren if provided, otherwise falls back to default behavior. | ( |
Gets the number of children for a node, supporting lazy loading scenarios.
Uses options.nodeToChildrenCount if provided, otherwise falls back to default behavior.
| ( |
Checks if a node is disabled.
Uses options.isNodeDisabled if provided, otherwise falls back to default behavior.
| ( |
Gets the string value for a node.
Uses options.nodeValue if provided, otherwise falls back to default behavior.
| ( |
Gets the parent node of the specified node.
| ( |
Gets all parent nodes from root to the specified node.
| ( |
Gets the previous node before the one with the specified value.
| ( |
Gets the previous non-disabled sibling of the node at the index path.
| ( |
Gets all sibling nodes of the node at the index path.
| ( |
Gets the value of the node at the specified index path.
| ( |
Gets the path of values from root to the specified index path.
| ( |
Gets all values in the tree, excluding the root node.
| ( |
Groups children of a parent node by a specified key.
| ( |
// Group root-level children | |
Inserts nodes after the node at the specified index path.
| ( |
Inserts nodes before the node at the specified index path.
| ( |
Checks if a node is a branch node (has children or can have children).
| ( |
Compares this tree collection with another for deep equality.
| ( |
Checks if a node is the root node.
| ( |
Checks if two nodes are the same by comparing their values.
| ( |
Moves nodes from one location to another in the tree.
| ( |
Removes nodes at the specified index paths.
| ( |
Replaces the node at the specified index path.
| ( |
The root tree node. | T |
Sorts values according to their tree order.
| ( |
Converts a node value to its string representation.
| ( |
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.
| ( |
Serializes the tree to a JSON-compatible array of values. | () => string[] |
Visits all nodes in the tree with optional skip functionality.
| (opts: { |
(
indexPath: number[],
) => T
- indexPath:Array of indices representing the path to the node
(
parentIndexPath: number[],
valueIndexPath: number[],
) => boolean
- parentIndexPath:The parent path
- valueIndexPath:The child path to check
(
rootNode: T,
) => any
- rootNode:The new root node for the copied collection
(
predicate: (
node: T,
indexPath: number[],
) => boolean,
) => any
- predicate:Function to test each node
(
value: string,
rootNode?: T,
) => T
- value:The value to search for
- rootNode:The root node to start searching from
(
predicate: (
node: T,
indexPath: number[],
) => boolean,
rootNode?: T,
) => T
(
values: string[],
rootNode?: T,
) => Array<T>
- values:Array of values to search for
- rootNode:The root node to start searching from
(
rootNode?: T,
) => Array<
T & {
_children: number[]
_index: number
_parent: number
}
>
- rootNode:The root node to start flattening from
(
rootNode?: T,
opts?: {
skip?: (args: {
indexPath: number[]
node: T
value: string
}) => boolean | void
} & {
depth?:
| number
| ((
nodeDepth: number,
) => boolean)
},
) => string[]
- rootNode:The root node to start from
- opts:Options for skipping nodes and filtering by depth
(
value: string,
) => number
- value:The value to find the depth for
(
valueOrIndexPath?:
| string
| number[],
options?: T & {
disabled?: boolean
id?: string
onUnregister?: (
index: number,
) => void
requireContext?: boolean
},
) => Array<T>
- 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[]
- valueOrIndexPath:Either a node value or index path
- options:Options for controlling which descendants to include
(
rootNode?: T,
) => T
- rootNode:The root node to start searching from
(
value: string,
) => number[]
- value:The value to find the index path for
(
rootNode?: T,
opts?: {
skip?: (args: {
indexPath: number[]
node: T
value: string
}) => boolean | void
},
) => T
- rootNode:The root node to start searching from
- opts:Options for skipping nodes during traversal
(
value: string,
opts?: {
skip?: (args: {
indexPath: number[]
node: T
value: string
}) => boolean | void
},
) => T
- value:The value to find the next node from
- opts:Options for skipping nodes during traversal
(
indexPath: number[],
) => T
- indexPath:Array of indices representing the path to the node
(
node: T,
) => Array<T>
(
node: T,
) => number
- node:The node to get children count for
(
node: T,
) => boolean
- node:The node to check
(
node: T,
) => string
- node:The node to get the value from
(
valueOrIndexPath:
| string
| number[],
) => T
- valueOrIndexPath:Either a node value or index path
(
valueOrIndexPath:
| string
| number[],
) => Array<T>
- valueOrIndexPath:Either a node value or index path
(
value: string,
opts?: {
skip?: (args: {
indexPath: number[]
node: T
value: string
}) => boolean | void
},
) => T
- value:The value to find the previous node from
- opts:Options for skipping nodes during traversal
(
indexPath: number[],
) => T
- indexPath:Array of indices representing the path to the node
(
indexPath: number[],
) => Array<T>
- indexPath:Array of indices representing the path to the node
(
indexPath: number[],
) => string
- indexPath:Array of indices representing the path to the node
(
indexPath: number[],
) => string[]
- indexPath:Array of indices representing the path to the node
(
rootNode?: T,
) => string[]
- rootNode:The root node to start from
(
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>[]
- 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)
// Group root-level children
const groups = collection.groupChildren([], (node) => node.group ?? 'default')
// Group with explicit order
const groups = collection.groupChildren(
[],
(node) => node.group,
['primary', 'secondary', 'tertiary']
)
// Group with custom sorter
const groups = collection.groupChildren(
[],
(node) => node.group,
(a, b) => String(a.key).localeCompare(String(b.key))
)
(
indexPath: number[],
nodes: Array<T>,
) => any
- indexPath:Array of indices representing the insertion point
- nodes:Array of nodes to insert
(
indexPath: number[],
nodes: Array<T>,
) => any
- indexPath:Array of indices representing the insertion point
- nodes:Array of nodes to insert
(
node: T,
) => boolean
- node:The node to check
(
other: TreeCollection<T>,
) => boolean
- other:The other tree collection to compare with
(
node: T,
) => boolean
- node:The node to check
(
node: T,
other: T,
) => boolean
- node:First node to compare
- other:Second node to compare
(
fromIndexPaths: Array<
number[]
>,
toIndexPath: number[],
) => any
- fromIndexPaths:Array of index paths to move from
- toIndexPath:Index path to move to
(
indexPaths: Array<number[]>,
) => any
- indexPaths:Array of index paths to remove
(
indexPath: number[],
node: T,
) => any
- indexPath:Array of indices representing the path to the node
- node:The new node to replace with
T(
values: string[],
) => string[]
- values:Array of values to sort
(
value: string,
) => string
- value:The value to stringify
(
T,
) => string
node.text, or node.value if node.text is not available.- node:The node to stringify
() => string[]
(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
- opts:Options for visiting nodes, including skip predicate
Element API
q-side-nav-header
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__header' |
data-part | 'header' |
data-scope | 'side-nav' |
data-state | | 'open' |
class'qui-side-nav__header'data-part'header'data-scope'side-nav'data-state| 'open'
| 'closed'
| 'closing'
q-side-nav-header-logo
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__header-logo' |
data-part | 'header-logo' |
data-scope | 'side-nav' |
hidden | boolean |
class'qui-side-nav__header-logo'data-part'header-logo'data-scope'side-nav'hiddenbooleanq-side-nav-header-title
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__header-title' |
data-part | 'header-title' |
data-scope | 'side-nav' |
hidden | boolean |
class'qui-side-nav__header-title'data-part'header-title'data-scope'side-nav'hiddenbooleanq-side-nav-header-action
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__header-action' |
data-part | 'header-action' |
data-scope | 'side-nav' |
data-state | | 'open' |
class'qui-side-nav__header-action'data-part'header-action'data-scope'side-nav'data-state| 'open'
| 'closed'
| 'closing'
q-side-nav-collapse-trigger
| Prop | Type |
|---|---|
HTML id attribute. If omitted, a unique identifier will be generated for
accessibility. | string |
string| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__collapse-trigger' |
data-disabled | |
data-part | 'trigger' |
data-scope | 'side-nav' |
data-state | | 'open' |
class'qui-side-nav__collapse-trigger'data-disableddata-part'trigger'data-scope'side-nav'data-state| 'open'
| 'closed'
| 'closing'
q-side-nav-group
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__group' |
class'qui-side-nav__group'q-side-nav-group-label
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__group-label' |
class'qui-side-nav__group-label'q-side-nav-divider
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__divider' |
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-part | 'branch' |
data-path | string |
data-scope | 'tree' |
data-selected | |
data-state | | 'open' |
data-value | string |
hidden | boolean |
style |
class'qui-side-nav__branch-root'data-branchstringdata-depthnumberdata-disableddata-loadingdata-ownedbystringdata-part'branch'data-pathstringdata-scope'tree'data-selecteddata-state| 'open'
| 'closed'
data-valuestringhiddenbooleanstyleq-side-nav-branch-node
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__node-root' |
data-depth | number |
data-disabled | |
data-focus | |
data-loading | |
data-part | 'branch-node' |
data-path | string |
data-scope | 'tree' |
data-selected | |
data-state | | 'open' |
data-value | string |
tabIndex | -1 | 0 |
class'qui-side-nav__node-root'data-depthnumberdata-disableddata-focusdata-loadingdata-part'branch-node'data-pathstringdata-scope'tree'data-selecteddata-state| 'open'
| 'closed'
data-valuestringtabIndex-1 | 0
q-side-nav-branch-trigger
| Prop | Type | Default |
|---|---|---|
The icon to display. This rotates by 180deg when the branch is expanded. | | LucideIconData | ChevronDown |
| LucideIconData
| string
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__branch-trigger' |
data-disabled | |
data-loading | |
data-part | 'branch-trigger' |
data-scope | 'tree' |
data-state | | 'open' |
data-value | string |
class'qui-side-nav__branch-trigger'data-disableddata-loadingdata-part'branch-trigger'data-scope'tree'data-state| 'open'
| 'closed'
data-valuestringq-side-nav-branch-content
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__branch-content' |
data-depth | number |
data-part | 'branch-content' |
data-path | string |
data-scope | 'tree' |
data-value | string |
class'qui-side-nav__branch-content'data-depthnumberdata-part'branch-content'data-pathstringdata-scope'tree'data-valuestringq-side-nav-branch-indent-guide
| Attribute / Property | Value |
|---|---|
data-depth | number |
data-part | 'branch-indent-guide' |
data-scope | 'tree' |
style |
data-depthnumberdata-part'branch-indent-guide'data-scope'tree'styleq-side-nav-leaf-node
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__node-root' |
data-depth | number |
data-disabled | |
data-focus | |
data-ownedby | string |
data-part | 'leaf-node' |
data-path | string |
data-scope | 'tree' |
data-selected | |
data-value | string |
hidden | boolean |
style | |
tabIndex | -1 | 0 |
class'qui-side-nav__node-root'data-depthnumberdata-disableddata-focusdata-ownedbystringdata-part'leaf-node'data-pathstringdata-scope'tree'data-selecteddata-valuestringhiddenbooleanstyletabIndex-1 | 0
q-side-nav-node-icon
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__node-icon' |
data-disabled | |
data-focus | |
data-part | 'node-icon' |
data-scope | 'tree' |
data-selected |
class'qui-side-nav__node-icon'data-disableddata-focusdata-part'node-icon'data-scope'tree'data-selectedq-side-nav-node-text
| Attribute / Property | Value |
|---|---|
data-disabled | |
data-focus | |
data-part | 'node-text' |
data-scope | 'tree' |
data-selected |
data-disableddata-focusdata-part'node-text'data-scope'tree'data-selectedq-side-nav-node-indicator
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__node-indicator' |
data-disabled | |
data-focus | |
data-part | 'node-indicator' |
data-scope | 'tree' |
data-selected | |
hidden | boolean |
class'qui-side-nav__node-indicator'data-disableddata-focusdata-part'node-indicator'data-scope'tree'data-selectedhiddenbooleanq-side-nav-node-action
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__node-action' |
data-disabled | |
data-focus | |
data-part | 'node-action' |
data-scope | 'tree' |
data-selected |
class'qui-side-nav__node-action'data-disableddata-focusdata-part'node-action'data-scope'tree'data-selectedq-side-nav-node-accessory
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__node-accessory' |
class'qui-side-nav__node-accessory'q-side-nav-filter-input
| Attribute / Property | Value |
|---|---|
class | 'qui-side-nav__filter-input' |
class'qui-side-nav__filter-input'Template Directives
q-side-nav-branch-template
q-side-nav-leaf-template
ng-template to customize how leaf nodes (nodes
without children) are displayed.<ng-template q-side-nav-leaf-template let-node>
<div q-side-nav-leaf-node>
<span q-side-nav-node-text>{{ node.item.label }}</span>
</div>
</ng-template>
| Prop | Type |
|---|---|
The root node of the tree. Used for type narrowing of the template guard. | T |
TUse this directive on an ng-template to customize the rendering of leaf nodes within q-side-nav-nodes.
ng-templateto 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.