Tree

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

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

node_modules

src

prettier.config.js

package.json

tsconfig.json

import type {ReactElement} from "react"

import {FileText, FolderIcon} from "lucide-react"

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

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

export function TreeNodeShorthandDemo(): ReactElement {
  return (
    <Tree.Root className="w-full max-w-sm" collection={collection}>
      {collection.rootNode.nodes?.map((parentNode, index) => {
        return (
          <Tree.Nodes
            key={parentNode.id}
            indexPath={[index]}
            node={parentNode}
            renderBranch={({node}) => (
              <Tree.BranchNode>
                <Tree.NodeIndicator />
                <Tree.BranchTrigger />
                <Tree.NodeIcon icon={FolderIcon} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.BranchNode>
            )}
            renderLeaf={({node}) => (
              <Tree.LeafNode>
                <Tree.NodeIndicator />
                <Tree.NodeIcon icon={FileText} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.LeafNode>
            )}
          />
        )
      })}
    </Tree.Root>
  )
}

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

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.

node_modules

src

prettier.config.js

package.json

tsconfig.json

import type {ReactElement} from "react"

import {FileText, FolderIcon} from "lucide-react"

import {createTreeCollection} from "@qualcomm-ui/core/tree"
import {Tree, type TreeNodeProviderProps} from "@qualcomm-ui/react/tree"

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

export function TreeNodesDemo(): ReactElement {
  return (
    <Tree.Root className="w-full max-w-sm" collection={collection}>
      {collection.rootNode.nodes?.map((node, index) => {
        return <TreeNodes key={node.id} indexPath={[index]} node={node} />
      })}
    </Tree.Root>
  )
}

function TreeNodes(props: TreeNodeProviderProps<Node>): ReactElement {
  const {indexPath, node} = props
  const childNodes = collection.getNodeChildren(node)
  return (
    <Tree.NodeProvider {...props}>
      {childNodes.length ? (
        <Tree.Branch>
          <Tree.BranchNode>
            <Tree.NodeIndicator />
            <Tree.BranchTrigger />
            <Tree.NodeIcon icon={FolderIcon} />
            <Tree.NodeText>{collection.stringifyNode(node)}</Tree.NodeText>
          </Tree.BranchNode>
          <Tree.BranchContent>
            <Tree.BranchIndentGuide />
            {collection.getNodeChildren(node).map((childNode, index) => (
              <TreeNodes
                key={collection.getNodeValue(childNode)}
                indexPath={[...indexPath, index]}
                node={childNode}
              />
            ))}
          </Tree.BranchContent>
        </Tree.Branch>
      ) : (
        <Tree.LeafNode>
          <Tree.NodeIndicator />
          <Tree.NodeIcon icon={FileText} />
          <Tree.NodeText>{collection.stringifyNode(node)}</Tree.NodeText>
        </Tree.LeafNode>
      )}
    </Tree.NodeProvider>
  )
}

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

Default Expanded

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

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.NodeCheckbox to add a checkbox to each node. The checked state of the tree can be controlled using the checkedValue, onCheckedValueChange, and defaultCheckedValue props, which follow our controlled state pattern.

Qualcomm

Snapdragon X Elite

Snapdragon X Plus

Intel

Intel Core Ultra

Intel Core i9

Intel Core i7

Intel Core i5

Intel Core i3

AMD

AMD Threadripper

AMD Ryzen 9

AMD Ryzen 7 / 5

<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>
  )
}

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

Qualcomm

Snapdragon X

Snapdragon X Elite

Snapdragon X Plus

<Tree.Root
  className="w-full max-w-sm"
  collection={collection}
  defaultCheckedValue={["elite", "plus"]}
  defaultExpandedValue={["qualcomm", "sdx"]}
>

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

qualcomm

snapdragon_x_elite

snapdragon_x_plus

intel

intel_core_ultra

intel_core_i9

amd

amd_threadripper

amd_ryzen_9

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

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

Disabled Nodes

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

node_modules

src

prettier.config.js

package.json

renovate.json

tsconfig.json

import type {ReactElement} from "react"

import {FileText, FolderIcon} from "lucide-react"

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

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

export function TreeDisabledNodeDemo(): ReactElement {
  return (
    <Tree.Root className="w-full max-w-sm" collection={collection}>
      {collection.rootNode.nodes?.map((parentNode, index) => {
        return (
          <Tree.Nodes
            key={parentNode.id}
            indexPath={[index]}
            node={parentNode}
            renderBranch={({node}) => (
              <Tree.BranchNode>
                <Tree.NodeIndicator />
                <Tree.BranchTrigger />
                <Tree.NodeIcon icon={FolderIcon} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.BranchNode>
            )}
            renderLeaf={({node}) => (
              <Tree.LeafNode>
                <Tree.NodeIndicator />
                <Tree.NodeIcon icon={FileText} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.LeafNode>
            )}
          />
        )
      })}
    </Tree.Root>
  )
}

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

Filtering

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

node_modules

src

prettier.config.js

package.json

tsconfig.json

import {type ReactElement, useState} from "react"

import {FileText, FolderIcon, Search} from "lucide-react"

import {createTreeCollection} from "@qualcomm-ui/core/tree"
import {TextInput} from "@qualcomm-ui/react/text-input"
import {Tree} from "@qualcomm-ui/react/tree"
import type {TreeCollection} from "@qualcomm-ui/utils/collection"
import {matchSorter} from "@qualcomm-ui/utils/match-sorter"

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

export function TreeFilteringDemo(): ReactElement {
  const [collection, setCollection] =
    useState<TreeCollection<Node>>(initialCollection)
  const [expanded, setExpanded] = useState<string[]>([])
  const [query, setQuery] = useState<string>("")

  const search = (value: string) => {
    setQuery(value)

    if (!value) {
      setCollection(initialCollection)
      return
    }

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

  return (
    <Tree.Root
      className="w-full max-w-sm"
      collection={initialCollection}
      expandedValue={expanded}
      onExpandedValueChange={({expandedValue}) => setExpanded(expandedValue)}
    >
      <TextInput
        aria-label="Search for files"
        className="mb-1"
        onValueChange={search}
        placeholder="Search for files: 'react'"
        size="sm"
        startIcon={Search}
        value={query}
      />
      {collection.rootNode.nodes?.map((parentNode, index) => {
        return (
          <Tree.Nodes
            key={parentNode.id}
            indexPath={[index]}
            node={parentNode}
            renderBranch={({node}) => (
              <Tree.BranchNode>
                <Tree.NodeIndicator />
                <Tree.BranchTrigger />
                <Tree.NodeIcon icon={FolderIcon} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.BranchNode>
            )}
            renderLeaf={({node}) => (
              <Tree.LeafNode>
                <Tree.NodeIndicator />
                <Tree.NodeIcon icon={FileText} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.LeafNode>
            )}
          />
        )
      })}
    </Tree.Root>
  )
}

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

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.

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.

Small (sm)

node_modules

src

prettier.config.js

package.json

tsconfig.json

Medium (md)

node_modules

src

prettier.config.js

package.json

tsconfig.json

import type {ReactElement} from "react"

import {FileText, FolderIcon} from "lucide-react"

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

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

export function TreeSizeDemo(): ReactElement {
  return (
    <div className="flex w-full flex-col gap-4">
      <Tree.Root className="w-full max-w-sm" collection={collection} size="sm">
        <Tree.Label>Small (sm)</Tree.Label>
        <TreeContent />
      </Tree.Root>

      <Tree.Root className="w-full max-w-sm" collection={collection} size="md">
        <Tree.Label>Medium (md)</Tree.Label>
        <TreeContent />
      </Tree.Root>
    </div>
  )
}

function TreeContent() {
  return (
    <>
      {collection.rootNode.nodes?.map((parentNode, index) => {
        return (
          <Tree.Nodes
            key={parentNode.id}
            indexPath={[index]}
            node={parentNode}
            renderBranch={({node}) => (
              <Tree.BranchNode>
                <Tree.NodeIndicator />
                <Tree.BranchTrigger />
                <Tree.NodeIcon icon={FolderIcon} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.BranchNode>
            )}
            renderLeaf={({node}) => (
              <Tree.LeafNode>
                <Tree.NodeIndicator />
                <Tree.NodeIcon icon={FileText} />
                <Tree.NodeText>{node.name}</Tree.NodeText>
              </Tree.LeafNode>
            )}
          />
        )
      })}
    </>
  )
}

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

Add / Remove nodes

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

node_modules

src

prettier.config.js

package.json

tsconfig.json

import {type ReactElement, useState} from "react"

import {FileText, FolderIcon, Plus, Trash} from "lucide-react"

import {createTreeCollection} from "@qualcomm-ui/core/tree"
import {Tree, type TreeNodeProviderProps} from "@qualcomm-ui/react/tree"
import {useTreeContext} from "@qualcomm-ui/react-core/tree"

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

export function TreeAddRemoveDemo(): ReactElement {
  const [collection, setCollection] = useState(initialCollection)

  const removeNode = (nodeProps: TreeNodeActionsProps) => {
    setCollection(collection.remove([nodeProps.indexPath]))
  }

  const addNode = (nodeProps: TreeNodeActionsProps) => {
    const {indexPath, node} = nodeProps
    if (!collection.isBranchNode(node)) {
      return
    }

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

  return (
    <Tree.Root className="w-full max-w-sm" collection={collection}>
      {collection.getNodeChildren(collection.rootNode).map((node, index) => {
        return (
          <Tree.Nodes
            key={node.id}
            indexPath={[index]}
            node={node}
            renderBranch={({indexPath, node}) => (
              <Tree.BranchNode role="treeitem">
                <Tree.NodeIndicator />
                <Tree.BranchTrigger />
                <Tree.NodeIcon icon={FolderIcon} />
                <Tree.NodeText>{collection.stringifyNode(node)}</Tree.NodeText>
                <TreeNodeActions
                  indexPath={indexPath}
                  node={node}
                  onAdd={addNode}
                  onRemove={removeNode}
                />
              </Tree.BranchNode>
            )}
            renderLeaf={({indexPath, node}) => (
              <Tree.LeafNode>
                <Tree.NodeIndicator />
                <Tree.NodeIcon icon={FileText} />
                <Tree.NodeText>{collection.stringifyNode(node)}</Tree.NodeText>
                <TreeNodeActions
                  indexPath={indexPath}
                  node={node}
                  onAdd={addNode}
                  onRemove={removeNode}
                />
              </Tree.LeafNode>
            )}
          />
        )
      })}
    </Tree.Root>
  )
}

interface TreeNodeActionsProps extends TreeNodeProviderProps<Node> {
  onAdd?: (props: TreeNodeProviderProps<Node>) => void
  onRemove?: (props: TreeNodeProviderProps<Node>) => void
}

function TreeNodeActions(props: TreeNodeActionsProps) {
  const {node, onAdd, onRemove} = props
  const tree = useTreeContext<Node>()
  const isBranch = tree.collection.isBranchNode(node)
  return (
    <>
      <Tree.NodeAction
        aria-label="Remove node"
        icon={Trash}
        onClick={() => {
          onRemove?.(props)
        }}
        size="sm"
      />
      {isBranch && (
        <Tree.NodeAction
          aria-label="Add node"
          icon={Plus}
          onClick={() => {
            onAdd?.(props)
            tree.expand([node.id])
          }}
          size="sm"
        />
      )}
    </>
  )
}

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

Explorer

src

app.tsx

index.ts

package.json

tsconfig.json

Component Anatomy

Hover to highlight, click to view API

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

API

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

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

Type

(
  indexPath: number[],
) => T

Description

Gets the node at the specified index path.

indexPath:Array of indices representing the path to the node

contains

Type

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

Description

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

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

copy

Type

(
  rootNode: T,
) => any

Description

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

rootNode:The new root node for the copied collection

filter

Type

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

Description

Filters the tree keeping only nodes that match the predicate.

predicate:Function to test each node

findNode

Type

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

Description

Finds the first node with the specified value.

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

findNodeBy

Type

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

findNodes

Type

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

Description

Finds all nodes with values matching the provided array.

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

flatten

Type

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

Description

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

rootNode:The root node to start flattening from

getBranchValues

Type

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

Description

Gets all branch node values with optional depth filtering.

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

getDepth

Type

(
  value: string,
) => number

Description

Gets the depth of a node with the specified value.

value:The value to find the depth for

getDescendantNodes

Type

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

Description

Gets all descendant nodes of the specified node.

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

getDescendantValues

Type

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

Description

Gets all descendant values of the specified node.

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

getFirstNode

Type

(
  rootNode?: T,
) => T

Description

Gets the first non-disabled node in the tree.

rootNode:The root node to start searching from

getIndexPath

Type

(
  value: string,
) => number[]

Description

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

value:The value to find the index path for

getLastNode

Type

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

Description

Gets the last non-disabled node in the tree.

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

getNextNode

Type

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

Description

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

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

getNextSibling

Type

(
  indexPath: number[],
) => T

Description

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

indexPath:Array of indices representing the path to the node

getNodeChildren

Type

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

Description

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

getNodeChildrenCount

Type

(
  node: T,
) => number

Description

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

node:The node to get children count for

getNodeDisabled

Type

(
  node: T,
) => boolean

Description

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

node:The node to check

getNodeValue

Type

(
  node: T,
) => string

Description

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

node:The node to get the value from

getParentNode

Type

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

Description

Gets the parent node of the specified node.

valueOrIndexPath:Either a node value or index path

getParentNodes

Type

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

Description

Gets all parent nodes from root to the specified node.

valueOrIndexPath:Either a node value or index path

getPreviousNode

Type

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

Description

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

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

getPreviousSibling

Type

(
  indexPath: number[],
) => T

Description

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

indexPath:Array of indices representing the path to the node

getSiblingNodes

Type

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

Description

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

indexPath:Array of indices representing the path to the node

getValue

Type

(
  indexPath: number[],
) => string

Description

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

indexPath:Array of indices representing the path to the node

getValuePath

Type

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

Description

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

indexPath:Array of indices representing the path to the node

getValues

Type

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

Description

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

rootNode:The root node to start from

groupChildren

Type

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

Description

Groups children of a parent node by a specified key.

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

insertAfter

Type

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

Description

Inserts nodes after the node at the specified index path.

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

insertBefore

Type

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

Description

Inserts nodes before the node at the specified index path.

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

isBranchNode

Type

(
  node: T,
) => boolean

Description

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

node:The node to check

isEqual

Type

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

Description

Compares this tree collection with another for deep equality.

other:The other tree collection to compare with

isRootNode

Type

(
  node: T,
) => boolean

Description

Checks if a node is the root node.

node:The node to check

isSameNode

Type

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

Description

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

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

move

Type

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

Description

Moves nodes from one location to another in the tree.

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

remove

Type

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

Description

Removes nodes at the specified index paths.

indexPaths:Array of index paths to remove

replace

Type

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

Description

Replaces the node at the specified index path.

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

replaceChildren

Type

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

Description

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

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

rootNode

Type

Description

The root tree node.

sort

Type

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

Description

Sorts values according to their tree order.

values:Array of values to sort

stringify

Type

(
  value: string,
) => string

Description

Converts a node value to its string representation.

stringifyNode

Type

(
  T,
) => string

Description

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

toJSON

Type

() => string[]

Description

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

visit

Type

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

Description

Visits all nodes in the tree with optional skip functionality.

opts:Options for visiting nodes, including skip predicate

Element API

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

<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-path`	string
`data-selected`
`data-state`	\| 'open' \| 'closed'
`data-tree-part`	'branch'
`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-path

Value

string

data-selected

Value

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

<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-path`	string
`data-selected`
`data-size`	'sm' \| 'md'
`data-state`	\| 'open' \| 'closed'
`data-tree-part`	'branch-node'
`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-path

Value

string

data-selected

Value

data-size

Value

'sm' | 'md'

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch-node'

data-value

Value

string

tabIndex

Value

-1 | 0

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

className

Value

'qui-tree__branch-trigger'

data-disabled

Value

data-loading

Value

data-state

Value

| 'open'
| 'closed'

data-tree-part

Value

'branch-trigger'

data-value

Value

string

<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-path`	string
`data-tree-part`	'branch-content'
`data-value`	string

className

Value

'qui-tree__branch-content'

data-depth

Value

number

data-path

Value

string

data-tree-part

Value

'branch-content'

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-tree-part`	'branch-indent-guide'
`style`	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-path`	string
`data-selected`
`data-size`	'sm' \| 'md'
`data-tree-part`	'leaf-node'
`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-path

Value

string

data-selected

Value

data-size

Value

'sm' | 'md'

data-tree-part

Value

'leaf-node'

data-value

Value

string

hidden

Value

boolean

style

Value

CSSProperties

tabIndex

Value

-1 | 0

<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-checkmark-part`	'root'
`data-disabled`
`data-state`	\| 'checked' \| 'indeterminate' \| 'unchecked'
`data-tree-part`	'node-checkbox'
`tabIndex`	-1

className

Value

'qui-checkbox__control qui-checkmark__root'

data-checkmark-part

Value

'root'

data-disabled

Value

data-state

Value

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

data-tree-part

Value

'node-checkbox'

tabIndex

Value

-1

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

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-selected`
`data-tree-part`	'node-action'

className

Value

'qui-tree__node-action'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-action'

<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-selected`
`data-tree-part`	'node-indicator'
`hidden`	boolean

className

Value

'qui-tree__node-indicator'

data-disabled

Value

data-focus

Value

data-selected

Value

data-tree-part

Value

'node-indicator'

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-selected`
`data-size`	'sm' \| 'md'
`data-tree-part`	'node-icon'

className

Value

'qui-tree__node-icon'

data-disabled

Value

data-focus

Value

data-selected

Value

data-size

Value

'sm' | 'md'

data-tree-part

Value

'node-icon'

<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

Last updated on May 23, 2026 by Ryan Bower

Tooltip