Tree

import {Tree} from "@qualcomm-ui/react/tree"

Overview

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

Default object shape:

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

These defaults can be overridden in the TreeCollection constructor.

Examples

Node Shorthand

We expose the <Tree.Nodes> shorthand for rendering Branch and Leaf nodes. Use its renderBranch and renderLeaf render props to customize the content of each tree item.

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

Brand

node_modules

src

prettier.config.js

package.json

tsconfig.json

Nodes

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

NOTE

This approach is recommended only for advanced use cases. Most users should use the shorthand <Tree.Nodes> instead.

Brand

node_modules

src

prettier.config.js

package.json

tsconfig.json

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

node_modules

src

app.tsx

index.ts

prettier.config.js

package.json

tsconfig.json

<Tree.Root
  className="w-full max-w-sm"
  collection={collection}
  defaultExpandedValue={["src"]}
>

Use the Tree.CheckboxNode to create a checkbox tree. The checked state of the tree can be controlled using the checkedValue, onCheckedChange, and defaultCheckedValue props, which follow our controlled state pattern.

Brand

Qualcomm

Snapdragon X Elite

Snapdragon X Plus

Intel

Intel Core Ultra

Intel Core i9

Intel Core i7

Intel Core i5

Intel Core i3

AMD

AMD Threadripper

AMD Ryzen 9

AMD Ryzen 7 / 5

<Tree.Nodes
  key={node.id}
  indexPath={[index]}
  node={node}
  renderBranch={({node}) => (
    <Tree.BranchNode>
      <Tree.BranchTrigger />
      <Tree.NodeCheckbox />
      <Tree.NodeText>{node.text}</Tree.NodeText>
    </Tree.BranchNode>
  )}
  renderLeaf={({node}) => (
    <Tree.LeafNode>
      <Tree.NodeCheckbox />
      <Tree.NodeText>{node.text}</Tree.NodeText>
    </Tree.LeafNode>
  )}
/>

Checkbox selection state

The Tree handles nested checkbox selection automatically:

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

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

Consider the following tree:

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

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

function Component() {
  return (
    // won't work, we need to supply the child nodes instead
    <Tree.Root defaultCheckedValue={["sdx"]} collection={collection}>
      ...
    </Tree.Root>
  )
}

function Component() {
  return (
    // works as expected
    <Tree.Root defaultCheckedValue={["elite", "plus"]} collection={collection}>
      ...
    </Tree.Root>
  )
}

Disabled Nodes

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

Brand

node_modules

src

prettier.config.js

package.json

renovate.json

tsconfig.json

Filtering

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

Brand

node_modules

src

prettier.config.js

package.json

tsconfig.json

Links

Tree nodes can be links using polymorphic composition. Use the render prop on the <Tree.BranchNode> or <Tree.LeafNode> to specify the element type.

Brand

Components

Switch Tooltip Tree

<Tree.LeafNode
  render={node.pathname ? <Link to={node.pathname} /> : <div />}
>
  <Tree.NodeIndicator />
  <Tree.NodeText>{node.name}</Tree.NodeText>
</Tree.LeafNode>

Sizes

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

Brand

Small (sm)

node_modules

src

prettier.config.js

package.json

tsconfig.json

Medium (md)

node_modules

src

prettier.config.js

package.json

tsconfig.json

Add / Remove nodes

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

Brand

node_modules

src

prettier.config.js

package.json

tsconfig.json

API

<Tree.Root>

Groups all parts of the tree. Renders a <div> element by default.

Prop	Type	Default
checkedValue The controlled checked node value	string[]
collection The tree collection data	TreeCollection
defaultCheckedValue The initial checked node value when rendered. Use when you don't need to control the checked node value.	string[]
defaultExpandedValue The initial expanded node ids when rendered. Use when you don't need to control the expanded node value.	string[]
defaultFocusedValue The initial focused node value when rendered. Use when you don't need to control the focused node value.	string
defaultSelectedValue The initial selected node value when rendered. Use when you don't need to control the selected node value.	string[]
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
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>>
onCheckedValueChange Called when the checked value changes	(details: { checkedNodes: Array<T> checkedValue: string[] }) => void
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
onSelectedValueChange Called when the selection changes	(details: { focusedValue: string selectedNodes: Array<T> selectedValue: string[] }) => void
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
size The size of the tree and its elements. Governs properties like font size, item padding, and icon sizes.	'sm' \| 'md'	'md'
typeahead Whether the tree supports typeahead search	boolean	true
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false

checkedValue

Type

string[]

Description

The controlled checked node value

collection

Type

TreeCollection

Description

The tree collection data

defaultCheckedValue

Type

string[]

Description

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

defaultExpandedValue

Type

string[]

Description

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

defaultFocusedValue

Type

string

Description

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

defaultSelectedValue

Type

string[]

Description

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

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

expandedValue

Type

string[]

Description

The controlled expanded node ids

expandOnClick

Type

boolean

Description

Whether clicking on a branch should open it or not

focusedValue

Type

string

Description

The value of the focused node

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve 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.

onCheckedValueChange

Type

(details: {
  checkedNodes: Array<T>
  checkedValue: string[]
}) => void

Description

Called when the checked value changes

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

onSelectedValueChange

Type

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

Description

Called when the selection changes

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.

size

Type

'sm' | 'md'

Description

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

typeahead

Type

boolean

Description

Whether the tree supports typeahead search

unmountOnExit

Type

boolean

Description

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

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

className

Value

'qui-tree__root'

data-part

Value

'root'

data-scope

Value

'tree'

data-size

Value

'sm' | 'md'

tabIndex

Value

-1

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

<Tree.Label>

An optional accessible label for the tree. Renders a <div> element by default.

Prop	Type
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

Type

string

Description

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

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__label'
`data-part`	'label'
`data-scope`	'tree'
`data-size`	'sm' \| 'md'

className

Value

'qui-tree__label'

data-part

Value

'label'

data-scope

Value

'tree'

data-size

Value

'sm' | 'md'

<Tree.Branch>

Groups the branch node and its content element. 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-tree__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-tree__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

<Tree.BranchNode>

An interactive tree item 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-tree__node-root'
`data-depth`	number
`data-disabled`
`data-focus`
`data-loading`
`data-part`	'branch-node'
`data-path`	string
`data-scope`	'tree'
`data-selected`
`data-size`	'sm' \| 'md'
`data-state`	\| 'open' \| 'closed'
`data-value`	string
`tabIndex`	-1 \| 0

className

Value

'qui-tree__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-size

Value

'sm' | 'md'

data-state

Value

| 'open'
| 'closed'

data-value

Value

string

tabIndex

Value

-1 | 0

<Tree.BranchTrigger>

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

Prop	Type	Default
icon	\| LucideIcon \| ReactNode	ChevronRight
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

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-trigger'
`data-disabled`
`data-loading`
`data-part`	'branch-trigger'
`data-scope`	'tree'
`data-state`	\| 'open' \| 'closed'
`data-value`	string

className

Value

'qui-tree__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

<Tree.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-tree__branch-content'
`data-depth`	number
`data-part`	'branch-content'
`data-path`	string
`data-scope`	'tree'
`data-value`	string

className

Value

'qui-tree__branch-content'

data-depth

Value

number

data-part

Value

'branch-content'

data-path

Value

string

data-scope

Value

'tree'

data-value

Value

string

<Tree.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
`data-depth`	number
`data-part`	'branch-indent-guide'
`data-scope`	'tree'
`style`	CSSProperties

data-depth

Value

number

data-part

Value

'branch-indent-guide'

data-scope

Value

'tree'

style

Value

CSSProperties

<Tree.LeafNode>

A childless tree item. 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__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-size`	'sm' \| 'md'
`data-value`	string
`hidden`	boolean
`style`	CSSProperties
`tabIndex`	-1 \| 0

className

Value

'qui-tree__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-size

Value

'sm' | 'md'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

tabIndex

Value

-1 | 0

<Tree.NodeCheckbox>

A checkbox control within a tree item. Renders a <span> element by default.

Prop	Type	Default
checked React Node rendered when the node is checked.	ReactNode	CheckmarkCheckedIcon
indeterminate React Node rendered when the node is indeterminate.	ReactNode	CheckmarkIndeterminateIcon
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)
unchecked React Node rendered when the node is unchecked.	ReactNode

checked

Type

ReactNode

Description

React Node rendered when the node is checked.

indeterminate

Type

ReactNode

Description

React Node rendered when the node is indeterminate.

render

Type

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

Description

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

unchecked

Type

ReactNode

Description

React Node rendered when the node is unchecked.

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

className

Value

'qui-checkbox__control qui-checkmark__root'

data-disabled

Value

data-part

Value

'node-checkbox'

data-scope

Value

'tree'

data-state

Value

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

tabIndex

Value

-1

<Tree.NodeAction>

An action button within a tree item'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-tree__node-action'
`data-disabled`
`data-focus`
`data-part`	'node-action'
`data-scope`	'tree'
`data-selected`

className

Value

'qui-tree__node-action'

data-disabled

Value

data-focus

Value

data-part

Value

'node-action'

data-scope

Value

'tree'

data-selected

Value

<Tree.NodeIndicator>

Indicates whether the tree item 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-tree__node-indicator'
`data-disabled`
`data-focus`
`data-part`	'node-indicator'
`data-scope`	'tree'
`data-selected`
`hidden`	boolean

className

Value

'qui-tree__node-indicator'

data-disabled

Value

data-focus

Value

data-part

Value

'node-indicator'

data-scope

Value

'tree'

data-selected

Value

hidden

Value

boolean

<Tree.NodeIcon>

The icon for the tree item. 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-tree__node-icon'
`data-disabled`
`data-focus`
`data-part`	'node-icon'
`data-scope`	'tree'
`data-selected`
`data-size`	'sm' \| 'md'

className

Value

'qui-tree__node-icon'

data-disabled

Value

data-focus

Value

data-part

Value

'node-icon'

data-scope

Value

'tree'

data-selected

Value

data-size

Value

'sm' | 'md'

<Tree.NodeProvider>

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

indexPath

Type

number[]

Description

The index path of the tree node

node

Type

Description

The tree node to apply context from.

children

Type

ReactNode

Description

React children prop.

<Tree.NodeText>

The primary title of the tree item. 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

Tabs

Inline Notification