Tree

A collapsible, hierarchical tree component for organizing nested items like folders and files.

Folder 1

Folder 2

Folder 3

const tree = useTree(folderNodes, {});
return (
  <Tree tree={tree}>
    <TreeList nodeIds={tree.entity.rootIds} />
  </Tree>
);

const tree = useTree(folderNodes, {});return (  <Tree tree={tree}>    <TreeList nodeIds={tree.entity.rootIds} />  </Tree>);

Installation

pnpm add @notion-kit/ui

pnpm add @notion-kit/ui

Usage

The new tree package uses a modern, optimized architecture that accepts flat data (arrays with parentId relationships) and handles tree construction internally.

Basic Example

import { Tree, useTree } from "@notion-kit/ui/tree";
import { TreeList } from "@notion-kit/ui/tree/presets";

const data = [
  { id: "1", parentId: null, title: "Folder 1" },
  { id: "1.a", parentId: "1", title: "File A" },
  { id: "2", parentId: null, title: "Folder 2" },
];

export default function MyTree() {
  const tree = useTree(data, {});

  return (
    <Tree tree={tree}>
      <TreeList nodeIds={tree.entity.rootIds} />
    </Tree>
  );
}

Examples

Non-Collapsible Tree

Disable collapsing to show all nodes expanded by default.

Folder 1

Folder A

File 1 in folder A

File B

Folder 2

File C

File D

Folder 3

useTree(data, { collapsible: false })

useTree(data, { collapsible: false })

Multi-Select

Enable selection of multiple tree items.

Folder 1

Folder 2

Folder 3

useTree(data, { selectionMode: "multiple" })

useTree(data, { selectionMode: "multiple" })

Show Empty Children

Display an indicator when a folder has no children.

Folder 1

Folder 2

Folder 3

useTree(data, { showEmptyChild: true })

useTree(data, { showEmptyChild: true })

Combobox Tree

A searchable tree interface using a combobox.

<ComboboxTree tree={tree} />

<ComboboxTree tree={tree} />

API Reference

useTree

Creates a tree instance from flat data.

const tree = useTree<T>(data, options);

Parameters:

Parameter	Type	Description
`data`	`T[]`	Flat array of items with `id` and `parentId`
`options`	`TreeOptions`	Configuration options for the tree

TreeOptions:

Option	Type	Default	Description
`collapsible`	`boolean`	`true`	Whether nodes can be collapsed
`showEmptyChild`	`boolean`	`false`	Show indicator for empty folders
`selectionMode`	`"single" \| "multiple"`	`"single"`	Selection behavior
`initialExpanded`	`string[]`	`[]`	IDs of initially expanded nodes
`initialSelected`	`string[]`	`[]`	IDs of initially selected nodes
`onSelectionChange`	`(id: string) => void`	-	Called when selection changes

Returns: TreeInstance<T>

The tree instance exposes:

entity: The tree entity with rootIds, nodes, etc.
state: Current tree state (expanded, selected nodes)
expand(id): Expand/collapse a node
select(id): Select a node
getVisibleIds(): Get currently visible node IDs

Tree

Root container providing tree context.

Prop	Type	Description
`tree`*	`TreeInstance<T>`	Tree instance from `useTree`
`children`	`React.ReactNode`	Tree content (typically `Tree.List`)
`className`	`string`	Additional CSS classes

Tree.Item

A slottable tree item.

Tree.ExpandIndicator

A slottable button to expand/collapse a node.

Prop	Type	Description
`onToggle`	`() => void`	A handler that is called when the node is toggled

Tree.EmptyIndicator

A slottable indicator to show when a node has no children.

Tree.Group

A slottable tree group.

Tree.List

Renders tree nodes recursively.

Prop	Type	Description
`nodeIds`*	`string[]`	Array of node IDs to render
`renderItem`	`(props) => JSX`	Custom renderer for tree items (optional)
`renderEmpty`	`(props) => JSX`	Custom renderer for empty children (optional)

TreeList (Preset)

Pre-styled tree list component from @notion-kit/ui/tree/presets.

Prop	Type	Description
`nodeIds`*	`string[]`	Array of node IDs to render

ComboboxTree (Preset)

Searchable tree component with combobox behavior.

Prop	Type	Description
`tree`*	`TreeInstance<T>`	Tree instance from `useTree`

`type` TreeItemData (Preset)

Base interface for tree item data.

interface TreeItemData {
  id: string;
  parentId: string | null;
  title: string;
  icon?: IconData;
  group?: string | null;
}

Architecture

The tree package uses an optimized O(N) architecture:

Flat Data Input: Accepts arrays with parentId relationships (e.g., from database queries)
Automatic Tree Building: Constructs tree structure internally via BFS traversal
ID-Based Rendering: Uses node IDs for efficient recursive rendering
Derived Visibility: Computes visible nodes on-demand via getVisibleIds()
Smart State Management: Handles expand/collapse, selection via tree instance

This design eliminates the need for pre-structured tree data and provides better performance.

Tree

On this page