Side Nav

import {SideNav} from "@qualcomm-ui/react/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 SideNav. 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 <SideNav.Nodes> shorthand for rendering nodes. Use its renderBranch and renderLeaf render props to customize the content of each tree node.

Note that <SideNav.Nodes> automatically renders child nodes for branches, so you only have to customize the content of the node itself.

Brand

Notifications

Dashboard

AI Studio

Account

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.

Brand

Notifications

Settings

Main menu

Dashboard

AI Studio

Data Analysis

Integrations

Administration

Profile

Security

Billing

Default Expanded

Expand nodes by default using the defaultExpandedValue prop. Or use expandedValue and onExpandedChange to control the expansion manually. These props follow our controlled state pattern.

Brand

Notifications

Dashboard

AI Studio

Account

Profile

Security

Billing

<SideNav.Root collection={collection} defaultExpandedValue={["account"]}>

Disabled Nodes

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

Brand

Notifications

Dashboard

AI Studio

Account

Profile

Security

Billing

Filtering

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

Brand

Notifications

Settings

Main menu

Dashboard

AI Studio

Data Analysis

Integrations

Administration

Profile

Security

Billing

Links

Side Nav nodes can be links using polymorphic composition. Use the render prop on the <SideNav.LeafNode> to specify the element type.

Brand

Components

Pagination Side Nav Switch

<SideNav.LeafNode
  render={node.pathname ? <Link to={node.pathname} /> : <div />}
>
  <SideNav.NodeIndicator />
  {node.icon ? <SideNav.NodeIcon icon={node.icon} /> : null}
  <SideNav.NodeText>{node.text}</SideNav.NodeText>
</SideNav.LeafNode>

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, onOpenChange and defaultOpen props. These props follow our controlled state pattern.

Brand

Notifications

Settings

Main menu

Dashboard

AI Studio

Data Analysis

Integrations

Administration

Profile

Security

Billing

API

<SideNav.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'	'ltr'
disabled Whether the collapsible 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 document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
id id attribute. If omitted, a unique identifier will be automatically 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<Array<T>>
onExpandedValueChange Called when the tree is opened or closed	(details: { expandedNodes: Array<T> expandedValue: string[] focusedValue: string }) => void
onFocusChange Called when the focused node changes	(details: { focusedNode: T focusedValue: string }) => void
onLoadChildrenComplete Called when a node finishes loading children	(details: { collection: TreeCollection<T> }) => void
onLoadChildrenError Called when loading children fails for one or more nodes	(details: { nodes: NodeWithError[] }) => void
onOpenChange Function invoked when the collapsible opens or closes openThe next value.	( open: boolean, ) => void
onSelectedValueChange Called when the selection changes	(details: { focusedValue: string selectedNodes: Array<T> selectedValue: string[] }) => void
open The controlled open state of the collapsible	boolean
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
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: NodeState<T>, ) => 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

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 collapsible 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 document in custom environments. i.e., Iframes, Electron.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically 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<Array<T>>

Description

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

onExpandedValueChange

Type

(details: {
  expandedNodes: Array<T>
  expandedValue: string[]
  focusedValue: string
}) => void

Description

Called when the tree is opened or closed

onFocusChange

Type

(details: {
  focusedNode: T
  focusedValue: string
}) => void

Description

Called when the focused node changes

onLoadChildrenComplete

Type

(details: {
  collection: TreeCollection<T>
}) => void

Description

Called when a node finishes loading children

onLoadChildrenError

Type

(details: {
  nodes: NodeWithError[]
}) => void

Description

Called when loading children fails for one or more nodes

onOpenChange

Type

(
  open: boolean,
) => void

Description

Function invoked when the collapsible opens or closes

openThe next value.

onSelectedValueChange

Type

(details: {
  focusedValue: string
  selectedNodes: Array<T>
  selectedValue: string[]
}) => void

Description

Called when the selection changes

open

Type

boolean

Description

The controlled open state of the collapsible

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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: NodeState<T>,
) => 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.

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

className

Value

'qui-side-nav__root'

data-part

Value

'root'

data-scope

Value

'tree'

data-surface

Value

| 'primary'
| 'secondary'

tabIndex

Value

-1

<SideNav.Nodes>

A helper component that renders recursive tree nodes. Doesn't render its own HTML element.

Prop	Type	Default
indexPath ^* The index path of the tree node	number[]
node ^* The tree node to apply context from.	T
renderBranch ^* Render Prop for the tree's branch items. Use this prop to supply the content of the branch item like the text, indicator, or icon.	RenderProp<TreeNodesProps>
renderLeaf ^* Render Prop for the tree's leaf items. Use this prop to supply the content of the leaf item like the text, indicator, or icon.	RenderProp<TreeNodesProps>
indentGuideProps Props passed to the branch indent guide component. Only applicable when showIndentGuide is true.	TreeBranchIndentGuideProps
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 to apply context from.

renderBranch

Type

RenderProp<TreeNodesProps>

Description

Render Prop for the tree's branch items. Use this prop to supply the content of the branch item like the text, indicator, or icon.

renderLeaf

Type

RenderProp<TreeNodesProps>

Description

Render Prop for the tree's leaf items. Use this prop to supply the content of the leaf item like the text, indicator, or icon.

indentGuideProps

Type

TreeBranchIndentGuideProps

Description

Props passed to the branch indent guide component. Only applicable when showIndentGuide is true.

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. indexPathArray of indices representing the path to the node	( indexPath: number[], ) => T
contains Checks if a parent index path contains a child index path. parentIndexPathThe parent path valueIndexPathThe child path to check	( parentIndexPath: number[], valueIndexPath: number[], ) => boolean
copy Creates a new tree collection with the same options but different root node. rootNodeThe new root node for the copied collection	( rootNode: T, ) => any
filter Filters the tree keeping only nodes that match the predicate. predicateFunction to test each node	( predicate: ( node: T, indexPath: number[], ) => boolean, ) => any
findNode Finds the first node with the specified value. valueThe value to search for rootNodeThe 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. valuesArray of values to search for rootNodeThe root node to start searching from	( values: string[], rootNode?: T, ) => Array<T>
flatten Flattens the tree into an array with parent/child relationships. rootNodeThe 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. rootNodeThe root node to start from optsOptions 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. valueThe value to find the depth for	( value: string, ) => number
getDescendantNodes Gets all descendant nodes of the specified node. valueOrIndexPathEither a node value or index path optionsOptions 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. valueOrIndexPathEither a node value or index path optionsOptions 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. rootNodeThe root node to start searching from	( rootNode?: T, ) => T
getIndexPath Gets the index path for a node with the specified value. valueThe value to find the index path for	( value: string, ) => number[]
getLastNode Gets the last non-disabled node in the tree. rootNodeThe root node to start searching from optsOptions 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. valueThe value to find the next node from optsOptions 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. indexPathArray 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. nodeThe 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. nodeThe 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. nodeThe node to get the value from	( node: T, ) => string
getParentNode Gets the parent node of the specified node. valueOrIndexPathEither a node value or index path	( valueOrIndexPath: \| string \| number[], ) => T
getParentNodes Gets all parent nodes from root to the specified node. valueOrIndexPathEither a node value or index path	( valueOrIndexPath: \| string \| number[], ) => Array<T>
getPreviousNode Gets the previous node before the one with the specified value. valueThe value to find the previous node from optsOptions 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. indexPathArray of indices representing the path to the node	( indexPath: number[], ) => T
getSiblingNodes Gets all sibling nodes of the node at the index path. indexPathArray of indices representing the path to the node	( indexPath: number[], ) => Array<T>
getValue Gets the value of the node at the specified index path. indexPathArray of indices representing the path to the node	( indexPath: number[], ) => string
getValuePath Gets the path of values from root to the specified index path. indexPathArray of indices representing the path to the node	( indexPath: number[], ) => string[]
getValues Gets all values in the tree, excluding the root node. rootNodeThe root node to start from	( rootNode?: T, ) => string[]
groupChildren Groups children of a parent node by a specified key. parentIndexPathIndex path of the parent node whose children to group. Pass `[]` for root-level children. groupByFunction that determines the group key for each child node sortGroupsOptional 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>[]
// 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)) )
insertAfter Inserts nodes after the node at the specified index path. indexPathArray of indices representing the insertion point nodesArray of nodes to insert	( indexPath: number[], nodes: Array<T>, ) => any
insertBefore Inserts nodes before the node at the specified index path. indexPathArray of indices representing the insertion point nodesArray 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). nodeThe node to check	( node: T, ) => boolean
isEqual Compares this tree collection with another for deep equality. otherThe other tree collection to compare with	( other: TreeCollection<T>, ) => boolean
isRootNode Checks if a node is the root node. nodeThe node to check	( node: T, ) => boolean
isSameNode Checks if two nodes are the same by comparing their values. nodeFirst node to compare otherSecond node to compare	( node: T, other: T, ) => boolean
move Moves nodes from one location to another in the tree. fromIndexPathsArray of index paths to move from toIndexPathIndex path to move to	( fromIndexPaths: Array< number[] >, toIndexPath: number[], ) => any
remove Removes nodes at the specified index paths. indexPathsArray of index paths to remove	( indexPaths: Array<number[]>, ) => any
replace Replaces the node at the specified index path. indexPathArray of indices representing the path to the node nodeThe new node to replace with	( indexPath: number[], node: T, ) => any
rootNode The root tree node.	T
sort Sorts values according to their tree order. valuesArray of values to sort	( values: string[], ) => string[]
stringify Converts a node value to its string representation. valueThe value to stringify	( 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. nodeThe node to stringify	( 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. optsOptions 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.

indexPathArray 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.

parentIndexPathThe parent path
valueIndexPathThe child path to check

copy

Type

(
  rootNode: T,
) => any

Description

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

rootNodeThe 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.

predicateFunction to test each node

findNode

Type

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

Description

Finds the first node with the specified value.

valueThe value to search for
rootNodeThe 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.

valuesArray of values to search for
rootNodeThe 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.

rootNodeThe 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.

rootNodeThe root node to start from
optsOptions for skipping nodes and filtering by depth

getDepth

Type

(
  value: string,
) => number

Description

Gets the depth of a node with the specified value.

valueThe 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.

valueOrIndexPathEither a node value or index path
optionsOptions 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.

valueOrIndexPathEither a node value or index path
optionsOptions for controlling which descendants to include

getFirstNode

Type

(
  rootNode?: T,
) => T

Description

Gets the first non-disabled node in the tree.

rootNodeThe root node to start searching from

getIndexPath

Type

(
  value: string,
) => number[]

Description

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

valueThe 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.

rootNodeThe root node to start searching from
optsOptions 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.

valueThe value to find the next node from
optsOptions for skipping nodes during traversal

getNextSibling

Type

(
  indexPath: number[],
) => T

Description

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

indexPathArray 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.

nodeThe 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.

nodeThe 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.

nodeThe node to get the value from

getParentNode

Type

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

Description

Gets the parent node of the specified node.

valueOrIndexPathEither a node value or index path

getParentNodes

Type

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

Description

Gets all parent nodes from root to the specified node.

valueOrIndexPathEither 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.

valueThe value to find the previous node from
optsOptions for skipping nodes during traversal

getPreviousSibling

Type

(
  indexPath: number[],
) => T

Description

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

indexPathArray 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.

indexPathArray 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.

indexPathArray 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.

indexPathArray of indices representing the path to the node

getValues

Type

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

Description

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

rootNodeThe 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.

parentIndexPathIndex path of the parent node whose children to group. Pass [] for root-level children.
groupByFunction that determines the group key for each child node
sortGroupsOptional 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))
)

insertAfter

Type

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

Description

Inserts nodes after the node at the specified index path.

indexPathArray of indices representing the insertion point
nodesArray of nodes to insert

insertBefore

Type

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

Description

Inserts nodes before the node at the specified index path.

indexPathArray of indices representing the insertion point
nodesArray of nodes to insert

isBranchNode

Type

(
  node: T,
) => boolean

Description

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

nodeThe node to check

isEqual

Type

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

Description

Compares this tree collection with another for deep equality.

otherThe other tree collection to compare with

isRootNode

Type

(
  node: T,
) => boolean

Description

Checks if a node is the root node.

nodeThe node to check

isSameNode

Type

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

Description

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

nodeFirst node to compare
otherSecond node to compare

move

Type

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

Description

Moves nodes from one location to another in the tree.

fromIndexPathsArray of index paths to move from
toIndexPathIndex path to move to

remove

Type

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

Description

Removes nodes at the specified index paths.

indexPathsArray of index paths to remove

replace

Type

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

Description

Replaces the node at the specified index path.

indexPathArray of indices representing the path to the node
nodeThe new node to replace with

rootNode

Type

Description

The root tree node.

sort

Type

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

Description

Sorts values according to their tree order.

valuesArray of values to sort

stringify

Type

(
  value: string,
) => string

Description

Converts a node value to its string representation.

valueThe value to stringify

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.

nodeThe node to stringify

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.

optsOptions for visiting nodes, including skip predicate

Element API

<SideNav.Group>

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

<SideNav.GroupLabel>

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

<SideNav.Divider>

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-side-nav__header'

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-side-nav__header-logo'

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-side-nav__header-title'

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'qui-side-nav__header-action'

<SideNav.Branch>

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'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' \| 'closed'
`data-value`	string
`hidden`	boolean
`style`	CSSProperties

className

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-part

Value

'branch'

data-path

Value

string

data-scope

Value

'tree'

data-selected

Value

data-state

Value

| 'open'
| 'closed'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

<SideNav.BranchNode>

An interactive tree node with children. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'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' \| 'closed'
`data-value`	string
`tabIndex`	-1 \| 0

className

Value

'qui-side-nav__node-root'

data-depth

Value

number

data-disabled

Value

data-focus

Value

data-loading

Value

data-part

Value

'branch-node'

data-path

Value

string

data-scope

Value

'tree'

data-selected

Value

data-state

Value

| 'open'
| 'closed'

data-value

Value

string

tabIndex

Value

-1 | 0

<SideNav.BranchTrigger>

Icon that indicates whether a branch is expanded or collapsed. Renders a <div> element by default.

Prop	Type	Default
icon The icon to display. This rotates by 180deg when the branch is expanded.	\| LucideIcon \| ReactNode	ChevronDown
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

icon

Type

| LucideIcon
| ReactNode

Description

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

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

className

Value

'qui-side-nav__branch-trigger'

data-disabled

Value

data-loading

Value

data-part

Value

'branch-trigger'

data-scope

Value

'tree'

data-state

Value

| 'open'
| 'closed'

data-value

Value

string

<SideNav.BranchContent>

Container element for the branch node's children. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

className

Value

'qui-side-nav__branch-content'

data-depth

Value

number

data-part

Value

'branch-content'

data-path

Value

string

data-scope

Value

'tree'

data-value

Value

string

<SideNav.BranchIndentGuide>

Provides a visual guide to the indentation level of the branch's children. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

className

Value

'qui-tree__branch-indent-guide'

data-depth

Value

number

data-part

Value

'branch-indent-guide'

data-scope

Value

'tree'

style

Value

CSSProperties

<SideNav.LeafNode>

A childless tree node. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'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`	CSSProperties
`tabIndex`	-1 \| 0

className

Value

'qui-side-nav__node-root'

data-depth

Value

number

data-disabled

Value

data-focus

Value

data-ownedby

Value

string

data-part

Value

'leaf-node'

data-path

Value

string

data-scope

Value

'tree'

data-selected

Value

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

tabIndex

Value

-1 | 0

<SideNav.NodeAction>

An action button within a tree node's interactive area. Renders a <button> element by default.

Prop	Type	Default
icon ^* Lucide icon to display inside the button.	\| LucideIcon \| ReactNode
emphasis The style variant of the button. Governs color. TODO: link to design system docs.	\| 'neutral' \| 'persistent-white' \| 'persistent-black'	'neutral'
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
size The size of the button and its icon.	\| 'sm' \| 'md' \| 'lg'	'md'

icon

Type

| LucideIcon
| ReactNode

Description

Lucide icon to display inside the button.

emphasis

Type

| 'neutral'
| 'persistent-white'
| 'persistent-black'

Description

The style variant of the button. Governs color. TODO: link to design system docs.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

size

Type

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

Description

The size of the button and its icon.

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

className

Value

'qui-side-nav__node-action'

data-disabled

Value

data-focus

Value

data-part

Value

'node-action'

data-scope

Value

'tree'

data-selected

Value

<SideNav.NodeIndicator>

Indicates whether the tree node is selected. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

className

Value

'qui-side-nav__node-indicator'

data-disabled

Value

data-focus

Value

data-part

Value

'node-indicator'

data-scope

Value

'tree'

data-selected

Value

hidden

Value

boolean

<SideNav.NodeIcon>

The icon for the tree node. Renders a <span> element by default.

Prop	Type
icon ^* lucide-react icon or JSX Element.	\| LucideIcon \| ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

icon

Type

| LucideIcon
| ReactNode

Description

lucide-react icon or JSX Element.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

className

Value

'qui-side-nav__node-icon'

data-disabled

Value

data-focus

Value

data-part

Value

'node-icon'

data-scope

Value

'tree'

data-selected

Value

<SideNav.NodeProvider>

Prop	Type
indexPath ^* The index path of the tree node	number[]
node ^* The tree node	T
children React children prop.	ReactNode

indexPath

Type

number[]

Description

The index path of the tree node

node

Type

Description

The tree node

children

Type

ReactNode

Description

React children prop.

<SideNav.NodeText>

The primary title of the tree node. Renders a <span> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Pagination

Tabs

Side Nav

Overview

Examples

Node Shorthand

Grouping

Default Expanded

Disabled Nodes

Filtering

Links

Collapsed

API

<SideNav.Root>

<SideNav.Nodes>

TreeCollection

Constructor

Element API

<SideNav.Group>

<SideNav.GroupLabel>

<SideNav.Divider>

<SideNav.Header>

<SideNav.HeaderLogo>

<SideNav.HeaderTitle>

<SideNav.HeaderAction>

<SideNav.Branch>

<SideNav.BranchNode>

<SideNav.BranchTrigger>

<SideNav.BranchContent>

<SideNav.BranchIndentGuide>

<SideNav.LeafNode>

<SideNav.NodeAction>

<SideNav.NodeIndicator>

<SideNav.NodeIcon>

<SideNav.NodeProvider>

<SideNav.NodeText>