jameskerr/react-arborist

React Arborist

The tree view is ubiquitous in software applications. This library provides the React ecosystem with a complete solution to build the equivalent of a VSCode sidebar, Mac Finder, Windows Explorer, or Sketch/Figma layers panel.

Here is a Gmail sidebar clone built with react-arborist.

Features

Drag and drop sorting
Open/close folders
Inline renaming
Virtualized rendering
Custom styling
Keyboard navigation
Aria attributes
Tree filtering
Selection synchronization
Callbacks (onScroll, onActivate, onSelect)
Controlled or uncontrolled trees

Installation

react-arborist requires react-dnd and react-dnd-html5-backend as peer dependencies. Install them together:

npm install react-arborist react-dnd react-dnd-html5-backend

yarn add react-arborist react-dnd react-dnd-html5-backend

Examples

Assume our data is this:

const data = [
  { id: "1", name: "Unread" },
  { id: "2", name: "Threads" },
  {
    id: "3",
    name: "Chat Rooms",
    children: [
      { id: "c1", name: "General" },
      { id: "c2", name: "Random" },
      { id: "c3", name: "Open Source Projects" },
    ],
  },
  {
    id: "4",
    name: "Direct Messages",
    children: [
      { id: "d1", name: "Alice" },
      { id: "d2", name: "Bob" },
      { id: "d3", name: "Charlie" },
    ],
  },
];

The Simplest Tree

Use all the defaults. The initialData prop makes the tree an uncontrolled component. Create, move, rename, and delete will be handled internally.

import { Tree } from 'react-arborist';

function App() {
  return <Tree initialData={data} />;
}

Demo

Customize the Appearance

We provide our own dimensions and our own Node component.

function App() {
  return (
    <Tree
      initialData={data}
      openByDefault={false}
      width={600}
      height={1000}
      indent={24}
      rowHeight={36}
      overscanCount={1}
      paddingTop={30}
      paddingBottom={10}
      padding={25 /* sets both */}
    >
      {Node}
    </Tree>
  );
}

function Node({ node, style, dragHandle }) {
  /* This node instance can do many things. See the API reference. */
  return (
    <div style={style} ref={dragHandle}>
      {node.isLeaf ? "🍁" : "🗀"}
      {node.data.name}
    </div>
  );
}

Demo

Control the Tree data

Here we use the data prop to make the tree a controlled component. We must handle all the data modifications ourselves using the props below.

function App() {
  /* Handle the data modifications outside the tree component */
  const onCreate = ({ parentId, index, type }) => {};
  const onRename = ({ id, name }) => {};
  const onMove = ({ dragIds, parentId, index }) => {};
  const onDelete = ({ ids }) => {};

  return (
    <Tree
      data={data}
      onCreate={onCreate}
      onRename={onRename}
      onMove={onMove}
      onDelete={onDelete}
    />
  );
}

The `onMove` index

onMove's index is a pre-removal slot: it counts positions in the destination parent's child list as shown on screen, with the dragged rows still in place. If your handler removes the dragged rows before inserting them — the natural way to reorder an array — every dragged row that started before the drop slot shifts your target one place to the left, so dragging a row to just below itself would jump it past its neighbor (issue #247).

SimpleTree / useSimpleTree insert before removing, so they need no adjustment. If you manage the data yourself, use the exported adjustMoveIndex helper:

import { adjustMoveIndex } from "react-arborist";

const onMove = ({ dragIds, index }) => {
  const to = adjustMoveIndex({ index, dragIds, siblingIds: data.map((d) => d.id) });
  const dragged = data.filter((d) => dragIds.includes(d.id));
  const rest = data.filter((d) => !dragIds.includes(d.id));
  rest.splice(to, 0, ...dragged);
  setData(rest);
};

Pass the destination parent's current child ids in display order (for a root-level move, that's your top-level data's ids). Ids that aren't among them — rows moving in from another parent — don't shift anything.

Tree Filtering

Providing a non-empty searchTerm will only show nodes that match. If a child matches, all its parents are shown too, so the tree keeps its structure. Internal nodes are opened when filtering. You can provide your own searchMatch function, or use the default, which searches a node's own data, excluding its children. The default is deliberately loose: it JSON-stringifies the data's values and looks for the term anywhere in the result, so a term can also hit the keys of a nested object. Pass searchMatch when you want to match specific fields.

function App() {
  const term = useSearchTermString()
  <Tree
    data={data}
    searchTerm={term}
    searchMatch={
      (node, term) => node.data.name.toLowerCase().includes(term.toLowerCase())
    }
  />
}

Sync the Selection

It's common to open something elsewhere in the app, but have the tree reflect the new selection.

Passing an id to the selection prop will select and scroll to that node whenever that id changes.

function App() {
  const chatId = useCurrentChatId();

  /* 
    Whenever the currentChatRoomId changes, 
    the tree will automatically select it and scroll to it. 
  */

  return <Tree initialData={data} selection={chatId} />;
}

Use the Tree Api Instance

You can access the Tree Api in the parent component by giving a ref to the tree.

function App() {
  const treeRef = useRef();

  useEffect(() => {
    const tree = treeRef.current;
    tree.selectAll();
    /* See the Tree API reference for all you can do with it. */
  }, []);

  return <Tree initialData={data} ref={treeRef} />;
}

Data with Different Property Names

The idAccessor and childrenAccessor props allow you to specify the children and id fields in your data.

function App() {
  const data = [
    {
      category: "Food",
      subCategories: [{ category: "Restaurants" }, { category: "Groceries" }],
    },
  ];
  return (
    <Tree
      data={data}
      /* An accessor can provide a string property name */
      idAccessor="category"
      /* or a function with the data as the argument */
      childrenAccessor={(d) => d.subCategories}
    />
  );
}

Custom Rendering

Render every single piece of the tree yourself. See the API reference for the props passed to each renderer.

function App() {
  return (
    <Tree
      data={data}
      /* The outer most element in the list */
      renderRow={MyRow}
      /* The "ghost" element that follows the mouse as you drag */
      renderDragPreview={MyDragPreview}
      /* The line that shows where an element will be dropped */
      renderCursor={MyCursor}
    >
      {/* The inner element that shows the indentation and data */}
      {MyNode}
    </Tree>
  );
}

Dynamic sizing

You can add a ref to it with this package Pmndrs/react-use-measure

That hook will measure the boundaries (for instance width, height, top, left) of a view you reference. Then you pass the width and the height to the Tree.

import useMeasure from "react-use-measure";

const [ref, bounds] = useMeasure();
 
<div className="parent" ref={ref}>
  <Tree height={bounds.height} width={bounds.width} />
</div>

Tree Component Props

These are all the props you can pass to the Tree component.

interface TreeProps<T> {
  /* Data Options */
  data?: readonly T[];
  initialData?: readonly T[];

  /* Data Handlers */
  onCreate?: handlers.CreateHandler<T>;
  onMove?: handlers.MoveHandler<T>;
  onRename?: handlers.RenameHandler<T>;
  onDelete?: handlers.DeleteHandler<T>;

  /* Renderers*/
  children?: ElementType<renderers.NodeRendererProps<T>>;
  renderRow?: ElementType<renderers.RowRendererProps<T>>;
  renderDragPreview?: ElementType<renderers.DragPreviewProps>;
  renderCursor?: ElementType<renderers.CursorProps>;
  renderContainer?: ElementType<{}>;

  /* Sizes */
  rowHeight?: number;
  overscanCount?: number;
  width?: number | string;
  height?: number;
  indent?: number;
  paddingTop?: number;
  paddingBottom?: number;
  padding?: number;

  /* Config */
  childrenAccessor?: string | ((d: T) => readonly T[] | null);
  idAccessor?: string | ((d: T) => string);
  openByDefault?: boolean;
  selectionFollowsFocus?: boolean;
  disableMultiSelection?: boolean;
  disableDeselectOnClick?: boolean;
  disableSelect?: string | boolean | BoolFunc<T>;
  disableEdit?: string | boolean | BoolFunc<T>;
  disableDrag?: string | boolean | BoolFunc<T>;
  disableDrop?:
    | string
    | boolean
    | ((args: {
        parentNode: NodeApi<T>;
        dragNodes: NodeApi<T>[];
        index: number;
      }) => boolean);

  /* Event Handlers */
  onActivate?: (node: NodeApi<T>) => void;
  onSelect?: (nodes: NodeApi<T>[]) => void;
  onScroll?: (props: ListOnScrollProps) => void;
  onToggle?: (id: string) => void;
  onFocus?: (node: NodeApi<T>) => void;

  /* Selection */
  selection?: string;

  /* Open State */
  initialOpenState?: OpenMap;

  /* Search */
  searchTerm?: string;
  searchMatch?: (node: NodeApi<T>, searchTerm: string) => boolean;

  /* Extra */
  className?: string | undefined;
  rowClassName?: string | undefined;

  /* Tree container mouse events — fire for clicks / right-clicks anywhere in
     the tree (see "Handling Clicks on the Tree Container" below). */
  onClick?: MouseEventHandler;
  onContextMenu?: MouseEventHandler;

  dndRootElement?: globalThis.Node | null;
  dndBackend?: Extract<
    DndProviderProps<unknown, unknown>,
    { backend: unknown }
  >["backend"];
  dndManager?: ReturnType<typeof useDragDropManager>;
  dragType?: string | ((node: NodeApi<T>) => string);
}

Handling Clicks on the Tree Container

onClick and onContextMenu are attached to the tree's outer container, so they fire for mouse events anywhere in the tree — clicks that bubble up from a row, as well as clicks on the empty space below the last row. Use them for interactions that aren't tied to a single node, such as clearing the selection or opening your own context menu for the tree as a whole.

To act only when the empty area was clicked (and not a row), check whether the event started inside a row — rows carry role="treeitem":

<Tree
  data={data}
  onClick={(e) => {
    const onRow = (e.target as Element).closest('[role="treeitem"]');
    if (!onRow) {
      // clicked the empty area, not a row
    }
  }}
  onContextMenu={(e) => {
    e.preventDefault(); // suppress the native menu
    // open a custom context menu for the tree
  }}
/>

Clicking empty space already clears the selection by default; pass the disableDeselectOnClick prop to keep the selection instead.

Dragging Nodes to External Drop Targets

The react-dnd drag item created for each row carries the dragged node's data, so a drop target rendered outside the tree can read it:

const [, drop] = useDrop(() => ({
  accept: "NODE",
  drop: (item) => console.log(item.data), // the dragged node's data
}));

The tree and your external target must share one react-dnd backend. Wrap both in a single DndProvider and pass its manager to the tree via the dndManager prop. By default rows advertise the "NODE" item type; set the dragType prop (a fixed string, or a function of the node) to advertise a custom type instead. Note that the tree's own drop targets only accept "NODE", so a row given a custom dragType is no longer reorderable within the tree.

react-dnd Compatibility

react-arborist requires React 18+ and react-dnd v16.

react-arborist ships a single ESM build, as does react-dnd v16. import and require both resolve to it, so an app never loads two copies of react-arborist with separate React contexts. require("react-arborist") from CommonJS relies on require(esm), unflagged from Node.js 22.12, which is what engines.node declares. Only the require path actually needs that Node version, but engines is checked at install time: package managers that enforce it (Yarn Classic by default, pnpm with engine-strict) will refuse to install on older Node even for bundler and browser consumers.

CommonJS TypeScript projects that use Node module resolution need a module setting that understands require(esm): "nodenext" (TypeScript ≥ 5.8) or "node20" (TypeScript ≥ 5.9). "node16" and "node18" report error TS1479 on import ... from "react-arborist". Projects using moduleResolution: "bundler" or "node10" are unaffected.

Why react-dnd is a peer dependency

From react-arborist v4, react-dnd and react-dnd-html5-backend are peer dependencies rather than bundled dependencies. This matters because react-dnd registers a global singleton (globalThis[Symbol.for('__REACT_DND_CONTEXT_INSTANCE__')]). If your application and react-arborist each bundled their own copy, you would end up with two independent singletons, causing drag-and-drop to silently break or throw "Cannot have two HTML5 backends at the same time".

Making react-dnd a peer dependency means npm/yarn/pnpm will always resolve a single shared copy for your entire application.

Multiple trees on the same page

Rendering several <Tree> components side by side needs no special setup. react-dnd v16 memoizes one drag-drop manager per context object, and the default context is the global one, so every tree on the page already resolves to the same manager and the same backend.

Reach for the shared-provider pattern when you need the tree bound to a specific manager rather than to whatever the global slot holds: your <DndProvider> passes a custom context, or renders into another window or iframe. It is also the way to make the binding explicit — because the global manager is memoized on first use, whichever provider mounts first fixes the backend for everything after it, and a dndBackend passed to a later <Tree> is silently ignored. Wrap everything in one <DndProvider> and pass its manager to each tree:

import { DndProvider, useDragDropManager } from "react-dnd";
import { HTML5Backend } from "react-dnd-html5-backend";

function App() {
  return (
    <DndProvider backend={HTML5Backend}>
      <ForestView />
    </DndProvider>
  );
}

function ForestView() {
  const manager = useDragDropManager();
  return (
    <>
      <Tree data={leftData} dndManager={manager}>{Node}</Tree>
      <Tree data={rightData} dndManager={manager}>{Node}</Tree>
    </>
  );
}

Without the shared manager each <Tree> resolves through the global context instead. If your provider is on a custom context, that is a different manager, and drags started in the tree are invisible to your drop targets.

Custom backends

Pass any react-dnd-compatible backend via dndBackend:

import { TouchBackend } from "react-dnd-touch-backend";

<Tree data={data} dndBackend={TouchBackend}>{Node}</Tree>

Passing dndBackend or dndManager opts out of the default HTML5Backend. Custom-backend / dndManager users still need react-dnd-html5-backend installed as a peer: the drag preview calls into it (getEmptyImage()) on every drag regardless of which backend is active, so it's a hard requirement rather than an optional default.

dndBackend is only dependable when this <Tree> is the only react-dnd consumer in the page: as the previous section explains, react-dnd v16 memoizes one manager per context, so if another <Tree> or any other react-dnd consumer initialised the global manager first, this backend is silently dropped with no warning. Reach for the shared <DndProvider> + dndManager pattern above whenever the page has more than one.

react-dnd v16 and Jest

react-arborist, react-dnd v16, and react-dnd's transitive dependencies (dnd-core, @react-dnd/*) ship ESM-only builds. Jest's default CJS runtime can't load them directly. Add a transformIgnorePatterns entry so ts-jest (or babel-jest) transpiles them to CJS. Transpile-only mode is required — ts-jest's type-checking path won't emit for files outside your TS program. Set isolatedModules: true in the transformer's tsconfig block. Jest stopped bundling jest-environment-jsdom in v28, so install it too:

yarn add -D jest-environment-jsdom

// jest.config.js
module.exports = {
  transform: {
    "^.+\\.[jt]sx?$": ["ts-jest", { tsconfig: { allowJs: true, isolatedModules: true } }],
  },
  transformIgnorePatterns: [
    "/node_modules/(?!.*(react-arborist|react-dnd|react-dnd-html5-backend|dnd-core|@react-dnd)/)",
  ],
  testEnvironment: "jsdom",
  testEnvironmentOptions: {
    customExportConditions: ["browser", "require", "default"],
  },
};

Three details in that config are easy to get wrong:

testEnvironment: "jsdom" is required, not optional, once you restate customExportConditions. Jest's default environment is jest-environment-node, whose own conditions are ["node"] — and customExportConditions replaces rather than extends them. Drop jsdom while keeping ["browser", "require", "default"] and dependencies still resolve their browser builds, but now run them in plain Node without the DOM globals those builds expect. A browser build that touches window or document then fails with errors like ReferenceError: window is not defined.
The lookahead scans the rest of the path (.*) instead of just the next segment. Under pnpm these packages live at node_modules/.pnpm/react-dnd@16.0.1_.../node_modules/react-dnd/...; a next-segment-only pattern sees .pnpm, excludes them from transformation, and you get back the exact SyntaxError this is meant to prevent.
customExportConditions replaces the test environment's conditions rather than adding to them, so "browser" has to be restated — without it, a dependency whose exports map lists "browser" before "node" resolves its Node build under jsdom, and your tests pass while exercising code that never ships. Do not add "node": exports maps match in the package's own key order, so including "node" makes a package that lists "node" first resolve its Node build.

Why not --experimental-vm-modules? Node 22.12+ supports require() of ESM modules natively at the runtime level, but Jest intercepts require with its own CJS module system regardless of Node version. The transformIgnorePatterns approach works on all Jest versions without experimental flags.

Migrating from v3

v3 bundled react-dnd v14 as a regular dependency. v4 promotes it to a peer dependency.

# Before (v3) — react-dnd was pulled in automatically
npm install react-arborist

# After (v4) — install react-dnd alongside react-arborist
npm install react-arborist react-dnd react-dnd-html5-backend

If your app puts its <DndProvider> on a custom context, or renders one into another window, adopt the shared DndProvider + dndManager pattern shown above.

Row Component Props

The <RowRenderer> is responsible for attaching the drop ref, the row style (top, height) and the aria-attributes. The default should work fine for most use cases, but it can be replaced by your own component if you need. See the renderRow prop in the <Tree> component.

type RowRendererProps<T> = {
  node: NodeApi<T>;
  innerRef: (el: HTMLDivElement | null) => void;
  attrs: HTMLAttributes<any>;
  children: ReactElement;
};

Node Component Props

The <NodeRenderer> is responsible for attaching the drag ref, the node style (padding for indentation), the visual look of the node, the edit input of the node, and anything else you can dream up.

There is a default renderer, but it's only there as a placeholder to get started. You'll want to create your own component for this. It is passed as the <Tree> components only child.

export type NodeRendererProps<T> = {
  style: CSSProperties;
  node: NodeApi<T>;
  tree: TreeApi<T>;
  dragHandle?: (el: HTMLDivElement | null) => void;
  preview?: boolean;
};

DragPreview Component Props

The <DragPreview> is responsible for showing a "ghost" version of the node being dragged. The default is a semi-transparent version of the NodeRenderer and should work fine for most people. To customize it, pass your new component to the renderDragPreview prop.

type DragPreviewProps = {
  offset: XYCoord | null;
  mouse: XYCoord | null;
  id: string | null;
  dragIds: string[];
  isDragging: boolean;
};

Cursor Component Props

The <Cursor> is responsible for showing a line that indicates where the node will move to when it's dropped. The default is a blue line with circle on the left side. You may want to customize this. Pass your own component to the renderCursor prop.

export type CursorProps = {
  top: number;
  left: number;
  indent: number;
};

Node API Reference

State Properties

All these properties on the node instance return booleans related to the state of the node.

node.isRoot

Returns true if this is the root node. The root node is added internally by react-arborist and not shown in the UI.

node.isLeaf

Returns true if the children property is not an array.

node.isInternal

Returns true if the children property is an array.

node.isOpen

Returns true if node is internal and in an open state.

node.isEditing

Returns true if this node is currently being edited. Use this property in the NodeRenderer to render the rename form.

node.isSelected

Returns true if node is selected.

node.isSelectedStart

Returns true if node is the first of a contiguous group of selected nodes. Useful for styling.

node.isSelectedEnd

Returns true if node is the last of a contiguous group of selected nodes. Useful for styling.

node.isOnlySelection

Returns true if node is the only node selected in the tree.

node.isFocused

Returns true if node is focused.

node.isDragging

Returns true if node is being dragged.

node.willReceiveDrop

Returns true if node is internal and the user is hovering a dragged node over it.

node.state

Returns an object with all the above properties as keys and boolean values. Useful for adding class names to an element with a library like clsx or classnames.

type NodeState = {
  isEditing: boolean;
  isDragging: boolean;
  isSelected: boolean;
  isSelectedStart: boolean;
  isSelectedEnd: boolean;
  isFocused: boolean;
  isOpen: boolean;
  isClosed: boolean;
  isLeaf: boolean;
  isInternal: boolean;
  willReceiveDrop: boolean;
};

Accessors

node.childIndex

Returns the node's index in relation to its siblings.

node.next

Returns the next visible node. The node directly under this node in the tree component. Returns null if none exist.

node.prev

Returns the previous visible node. The node directly above this node in the tree component. Returns null if none exist.

node.nextSibling

Returns the next sibling in the data of this node. Returns null if none exist.

Selection Methods

node.select()

Select only this node.

node.deselect()

Deselect this node. Other nodes may still be selected.

node.selectMulti()

Select this node while maintaining all other selections.

node.selectContiguous()

Deselect all nodes from the anchor node to the last selected node, the select all nodes from the anchor node to this node. The anchor changes to the focused node after calling select() or selectMulti().

Activation Methods

node.activate()

Runs the Tree props' onActivate callback passing in this node.

node.focus()

Focus this node.

Open/Close Methods

node.open()

Opens the node if it is an internal node.

node.close()

Closes the node if it is an internal node.

node.toggle()

Toggles the open/closed state of the node if it is an internal node.

node.openParents()

Opens all the parents of this node.

node.edit()

Moves this node into the editing state. Calling node.isEditing will return true.

node.submit(newName)

Submits newName string to the onRename handler. Moves this node out of the editing state.

node.reset()

Moves this node out of the editing state without submitting a new name.

Event Handlers

node.handleClick(event)

Useful for using the standard selection methods when a node is clicked. If the meta key is down, call multiSelect(). If the shift key is down, call selectContiguous(). Otherwise, call select() and activate().

Tree API Reference

The tree api reference is stable across re-renders. It always has the most recent state and props.

Node Accessors

tree.get(id) : NodeApi | null

Get node by id from the visibleNodes array.

tree.at(index) : NodeApi | null

Get node by index from the visibleNodes array.

tree.visibleNodes : NodeApi[]

Returns an array of the visible nodes.

tree.firstNode : NodeApi | null

The first node in the visibleNodes array.

tree.lastNode : NodeApi | null

The last node in the visibleNodes array.

tree.focusedNode : NodeApi | null

The currently focused node.

tree.mostRecentNode : NodeApi | null

The most recently selected node.

tree.nextNode : NodeApi | null

The node directly after the focusedNode in the visibleNodes array.

tree.prevNode : NodeApi | null

The node directly before the focusedNode in the visibleNodes array.

Focus Methods

tree.hasFocus : boolean

Returns true if the the tree has focus somewhere within it.

tree.focus(id)

Focus on the node with id.

tree.isFocused(id) : boolean

Check if the node with id is focused.

tree.pageUp()

Move focus up one page.

tree.pageDown()

Move focus down one page.

Selection Methods

tree.selectedIds : Set<string>

Returns a set of ids that are selected.

tree.selectedNodes : NodeApi[]

Returns an array of nodes that are selected.

tree.hasNoSelection : boolean

Returns true if nothing is selected in the tree.

tree.hasSingleSelection : boolean

Returns true if there is only one selection.

tree.hasMultipleSelections : boolean

Returns true if there is more than one selection.

tree.isSelected(id) : boolean

Returns true if the node with id is selected.

tree.select(id, [opts])

Select only the node with id. Accepts an optional options object: { align?: "auto" | "smart" | "center" | "end" | "start"; focus?: boolean }. align is forwarded to the scroll behavior; passing focus: false suppresses the focus change and the onFocus callback.

tree.deselect(id)

Deselect the node with id.

tree.selectMulti(id, [opts])

Add to the selection the node with id. Accepts the same options object as select.

tree.selectContiguous(id)

Deselected nodes between the anchor and the last selected node, then select the nodes between the anchor and the node with id.

tree.deselectAll()

Deselect all nodes.

tree.selectAll()

Select all nodes.

Visibility

tree.open(id)

Open the node with id.

tree.close(id)

Close the node with id.

tree.toggle(id)

Toggle the open state of the node with id.

tree.openParents(id)

Open all parents of the node with id.

tree.openSiblings(id)

Open all siblings of the node with id.

tree.openAll()

Open all internal nodes.

tree.closeAll()

Close all internal nodes.

tree.isOpen(id) : boolean

Returns true if the node with id is open.

Drag and Drop

tree.isDragging(id) : boolean

Returns true if the node with id is being dragged.

tree.willReceiveDrop(id) : boolean

Returns true if the node with id is internal and is under the dragged node.

Scrolling

tree.scrollTo(id, [align])

Scroll to the node with id. If this node is not visible, this method will open all its parents. The align argument can be "auto" | "smart" | "center" | "end" | "start".

tree.scrollToOffset(offset)

Scroll the list vertically to an exact pixel offset from the top — the offset-based counterpart to scrollTo, useful for saving and restoring a scroll position. Negative or non-finite values are clamped to the top, and react-window clamps the upper bound to the scrollable range.

tree.scrollOffset : number

Returns the list's current vertical scroll offset, in pixels from the top. Pairs with scrollToOffset to persist and restore the scroll position.

Properties

tree.isEditing : boolean

Returns true if the tree is editing a node.

tree.isFiltered : boolean

Returns true if the searchTerm prop is not an empty string when trimmed.

tree.filteredCount : number

Returns how many nodes match the current searchTerm, counted across the whole tree regardless of which folders are open. Returns 0 when there is no active search. Useful for rendering a match count or a "no results" message (isFiltered && filteredCount === 0). Ancestors that appear in the filtered list only to keep the tree's structure intact are not counted. Matches are determined by the same predicate as filtering, so a searchMatch prop changes what counts.

tree.props : TreeProps

Returns all the props that were passed to the <Tree> component.

tree.root : NodeApi

Returns the root NodeApi instance. Its children are the Node representations of the data prop array.

Utilities

getTreeLinePrefix

Generates a tree-line prefix string (using Unix tree-style box-drawing characters like ├, └, │) for a given node. Useful when you want ASCII/Unicode connector lines in a custom node renderer.

function getTreeLinePrefix(
  node: NodeApi<any>,
  chars?: Partial<TreeLineChars>
): string;

type TreeLineChars = {
  last: string;   // default: "└ "
  middle: string; // default: "├ "
  pipe: string;   // default: "│ "
  blank: string;  // default: "\u3000 "
};

Wrap the prefix in a monospace span so the connectors line up:

import { Tree, getTreeLinePrefix } from "react-arborist";

function Node({ node, style }) {
  return (
    <div style={style}>
      <span style={{ fontFamily: "monospace" }}>{getTreeLinePrefix(node)}</span>
      {node.data.name}
    </div>
  );
}

Pass a partial chars object to override any of the default characters (e.g. for an ASCII-only style).

Contributing

The package ships with Jest tests under modules/react-arborist/src/**/*.test.ts?(x). From the package directory you can run:

cd modules/react-arborist
yarn test

Good starting points:

src/interfaces/tree-api.test.ts for pure API behavior
src/components/provider.test.tsx for rendered tree behavior
src/dnd/drag-hook.test.

React Arborist

See the Demos

Here is a Gmail sidebar clone built with react-arborist.

Features

Drag and drop sorting
Open/close folders
Inline renaming
Virtualized rendering
Custom styling
Keyboard navigation
Aria attributes
Tree filtering
Selection synchronization
Callbacks (onScroll, onActivate, onSelect)
Controlled or uncontrolled trees

Installation

react-arborist requires react-dnd and react-dnd-html5-backend as peer dependencies. Install them together:

npm install react-arborist react-dnd react-dnd-html5-backend

yarn add react-arborist react-dnd react-dnd-html5-backend

Examples

Assume our data is this:

const data = [
  { id: "1", name: "Unread" },
  { id: "2", name: "Threads" },
  {
    id: "3",
    name: "Chat Rooms",
    children: [
      { id: "c1", name: "General" },
      { id: "c2", name: "Random" },
      { id: "c3", name: "Open Source Projects" },
    ],
  },
  {
    id: "4",
    name: "Direct Messages",
    children: [
      { id: "d1", name: "Alice" },
      { id: "d2", name: "Bob" },
      { id: "d3", name: "Charlie" },
    ],
  },
];

The Simplest Tree

Use all the defaults. The initialData prop makes the tree an uncontrolled component. Create, move, rename, and delete will be handled internally.

import { Tree } from 'react-arborist';

function App() {
  return <Tree initialData={data} />;
}

Demo

Customize the Appearance

We provide our own dimensions and our own Node component.

function App() {
  return (
    <Tree
      initialData={data}
      openByDefault={false}
      width={600}
      height={1000}
      indent={24}
      rowHeight={36}
      overscanCount={1}
      paddingTop={30}
      paddingBottom={10}
      padding={25 /* sets both */}
    >
      {Node}
    </Tree>
  );
}

function Node({ node, style, dragHandle }) {
  /* This node instance can do many things. See the API reference. */
  return (
    <div style={style} ref={dragHandle}>
      {node.isLeaf ? "🍁" : "🗀"}
      {node.data.name}
    </div>
  );
}

Demo

Control the Tree data

Here we use the data prop to make the tree a controlled component. We must handle all the data modifications ourselves using the props below.

function App() {
  /* Handle the data modifications outside the tree component */
  const onCreate = ({ parentId, index, type }) => {};
  const onRename = ({ id, name }) => {};
  const onMove = ({ dragIds, parentId, index }) => {};
  const onDelete = ({ ids }) => {};

  return (
    <Tree
      data={data}
      onCreate={onCreate}
      onRename={onRename}
      onMove={onMove}
      onDelete={onDelete}
    />
  );
}

The `onMove` index

SimpleTree / useSimpleTree insert before removing, so they need no adjustment. If you manage the data yourself, use the exported adjustMoveIndex helper:

import { adjustMoveIndex } from "react-arborist";

const onMove = ({ dragIds, index }) => {
  const to = adjustMoveIndex({ index, dragIds, siblingIds: data.map((d) => d.id) });
  const dragged = data.filter((d) => dragIds.includes(d.id));
  const rest = data.filter((d) => !dragIds.includes(d.id));
  rest.splice(to, 0, ...dragged);
  setData(rest);
};

Tree Filtering

function App() {
  const term = useSearchTermString()
  <Tree
    data={data}
    searchTerm={term}
    searchMatch={
      (node, term) => node.data.name.toLowerCase().includes(term.toLowerCase())
    }
  />
}

Sync the Selection

It's common to open something elsewhere in the app, but have the tree reflect the new selection.

Passing an id to the selection prop will select and scroll to that node whenever that id changes.

function App() {
  const chatId = useCurrentChatId();

  /* 
    Whenever the currentChatRoomId changes, 
    the tree will automatically select it and scroll to it. 
  */

  return <Tree initialData={data} selection={chatId} />;
}

Use the Tree Api Instance

You can access the Tree Api in the parent component by giving a ref to the tree.

function App() {
  const treeRef = useRef();

  useEffect(() => {
    const tree = treeRef.current;
    tree.selectAll();
    /* See the Tree API reference for all you can do with it. */
  }, []);

  return <Tree initialData={data} ref={treeRef} />;
}

Data with Different Property Names

The idAccessor and childrenAccessor props allow you to specify the children and id fields in your data.

function App() {
  const data = [
    {
      category: "Food",
      subCategories: [{ category: "Restaurants" }, { category: "Groceries" }],
    },
  ];
  return (
    <Tree
      data={data}
      /* An accessor can provide a string property name */
      idAccessor="category"
      /* or a function with the data as the argument */
      childrenAccessor={(d) => d.subCategories}
    />
  );
}

Custom Rendering

Render every single piece of the tree yourself. See the API reference for the props passed to each renderer.

function App() {
  return (
    <Tree
      data={data}
      /* The outer most element in the list */
      renderRow={MyRow}
      /* The "ghost" element that follows the mouse as you drag */
      renderDragPreview={MyDragPreview}
      /* The line that shows where an element will be dropped */
      renderCursor={MyCursor}
    >
      {/* The inner element that shows the indentation and data */}
      {MyNode}
    </Tree>
  );
}

Dynamic sizing

You can add a ref to it with this package Pmndrs/react-use-measure

That hook will measure the boundaries (for instance width, height, top, left) of a view you reference. Then you pass the width and the height to the Tree.

import useMeasure from "react-use-measure";

const [ref, bounds] = useMeasure();
 
<div className="parent" ref={ref}>
  <Tree height={bounds.height} width={bounds.width} />
</div>

API Reference

Components
Interfaces
- Node API
- Tree API
Utilities
- getTreeLinePrefix

Tree Component Props

These are all the props you can pass to the Tree component.

interface TreeProps<T> {
  /* Data Options */
  data?: readonly T[];
  initialData?: readonly T[];

  /* Data Handlers */
  onCreate?: handlers.CreateHandler<T>;
  onMove?: handlers.MoveHandler<T>;
  onRename?: handlers.RenameHandler<T>;
  onDelete?: handlers.DeleteHandler<T>;

  /* Renderers*/
  children?: ElementType<renderers.NodeRendererProps<T>>;
  renderRow?: ElementType<renderers.RowRendererProps<T>>;
  renderDragPreview?: ElementType<renderers.DragPreviewProps>;
  renderCursor?: ElementType<renderers.CursorProps>;
  renderContainer?: ElementType<{}>;

  /* Sizes */
  rowHeight?: number;
  overscanCount?: number;
  width?: number | string;
  height?: number;
  indent?: number;
  paddingTop?: number;
  paddingBottom?: number;
  padding?: number;

  /* Config */
  childrenAccessor?: string | ((d: T) => readonly T[] | null);
  idAccessor?: string | ((d: T) => string);
  openByDefault?: boolean;
  selectionFollowsFocus?: boolean;
  disableMultiSelection?: boolean;
  disableDeselectOnClick?: boolean;
  disableSelect?: string | boolean | BoolFunc<T>;
  disableEdit?: string | boolean | BoolFunc<T>;
  disableDrag?: string | boolean | BoolFunc<T>;
  disableDrop?:
    | string
    | boolean
    | ((args: {
        parentNode: NodeApi<T>;
        dragNodes: NodeApi<T>[];
        index: number;
      }) => boolean);

  /* Event Handlers */
  onActivate?: (node: NodeApi<T>) => void;
  onSelect?: (nodes: NodeApi<T>[]) => void;
  onScroll?: (props: ListOnScrollProps) => void;
  onToggle?: (id: string) => void;
  onFocus?: (node: NodeApi<T>) => void;

  /* Selection */
  selection?: string;

  /* Open State */
  initialOpenState?: OpenMap;

  /* Search */
  searchTerm?: string;
  searchMatch?: (node: NodeApi<T>, searchTerm: string) => boolean;

  /* Extra */
  className?: string | undefined;
  rowClassName?: string | undefined;

  /* Tree container mouse events — fire for clicks / right-clicks anywhere in
     the tree (see "Handling Clicks on the Tree Container" below). */
  onClick?: MouseEventHandler;
  onContextMenu?: MouseEventHandler;

  dndRootElement?: globalThis.Node | null;
  dndBackend?: Extract<
    DndProviderProps<unknown, unknown>,
    { backend: unknown }
  >["backend"];
  dndManager?: ReturnType<typeof useDragDropManager>;
  dragType?: string | ((node: NodeApi<T>) => string);
}

Handling Clicks on the Tree Container

To act only when the empty area was clicked (and not a row), check whether the event started inside a row — rows carry role="treeitem":

<Tree
  data={data}
  onClick={(e) => {
    const onRow = (e.target as Element).closest('[role="treeitem"]');
    if (!onRow) {
      // clicked the empty area, not a row
    }
  }}
  onContextMenu={(e) => {
    e.preventDefault(); // suppress the native menu
    // open a custom context menu for the tree
  }}
/>

Clicking empty space already clears the selection by default; pass the disableDeselectOnClick prop to keep the selection instead.

Dragging Nodes to External Drop Targets

The react-dnd drag item created for each row carries the dragged node's data, so a drop target rendered outside the tree can read it:

const [, drop] = useDrop(() => ({
  accept: "NODE",
  drop: (item) => console.log(item.data), // the dragged node's data
}));

react-dnd Compatibility

react-arborist requires React 18+ and react-dnd v16.

Why react-dnd is a peer dependency

Making react-dnd a peer dependency means npm/yarn/pnpm will always resolve a single shared copy for your entire application.

Multiple trees on the same page

import { DndProvider, useDragDropManager } from "react-dnd";
import { HTML5Backend } from "react-dnd-html5-backend";

function App() {
  return (
    <DndProvider backend={HTML5Backend}>
      <ForestView />
    </DndProvider>
  );
}

function ForestView() {
  const manager = useDragDropManager();
  return (
    <>
      <Tree data={leftData} dndManager={manager}>{Node}</Tree>
      <Tree data={rightData} dndManager={manager}>{Node}</Tree>
    </>
  );
}

Custom backends

Pass any react-dnd-compatible backend via dndBackend:

import { TouchBackend } from "react-dnd-touch-backend";

<Tree data={data} dndBackend={TouchBackend}>{Node}</Tree>

react-dnd v16 and Jest

yarn add -D jest-environment-jsdom

// jest.config.js
module.exports = {
  transform: {
    "^.+\\.[jt]sx?$": ["ts-jest", { tsconfig: { allowJs: true, isolatedModules: true } }],
  },
  transformIgnorePatterns: [
    "/node_modules/(?!.*(react-arborist|react-dnd|react-dnd-html5-backend|dnd-core|@react-dnd)/)",
  ],
  testEnvironment: "jsdom",
  testEnvironmentOptions: {
    customExportConditions: ["browser", "require", "default"],
  },
};

Three details in that config are easy to get wrong:

testEnvironment: "jsdom" is required, not optional, once you restate customExportConditions. Jest's default environment is jest-environment-node, whose own conditions are ["node"] — and customExportConditions replaces rather than extends them. Drop jsdom while keeping ["browser", "require", "default"] and dependencies still resolve their browser builds, but now run them in plain Node without the DOM globals those builds expect. A browser build that touches window or document then fails with errors like ReferenceError: window is not defined.
The lookahead scans the rest of the path (.*) instead of just the next segment. Under pnpm these packages live at node_modules/.pnpm/react-dnd@16.0.1_.../node_modules/react-dnd/...; a next-segment-only pattern sees .pnpm, excludes them from transformation, and you get back the exact SyntaxError this is meant to prevent.
customExportConditions replaces the test environment's conditions rather than adding to them, so "browser" has to be restated — without it, a dependency whose exports map lists "browser" before "node" resolves its Node build under jsdom, and your tests pass while exercising code that never ships. Do not add "node": exports maps match in the package's own key order, so including "node" makes a package that lists "node" first resolve its Node build.

Why not --experimental-vm-modules? Node 22.12+ supports require() of ESM modules natively at the runtime level, but Jest intercepts require with its own CJS module system regardless of Node version. The transformIgnorePatterns approach works on all Jest versions without experimental flags.

Migrating from v3

v3 bundled react-dnd v14 as a regular dependency. v4 promotes it to a peer dependency.

# Before (v3) — react-dnd was pulled in automatically
npm install react-arborist

# After (v4) — install react-dnd alongside react-arborist
npm install react-arborist react-dnd react-dnd-html5-backend

If your app puts its <DndProvider> on a custom context, or renders one into another window, adopt the shared DndProvider + dndManager pattern shown above.

Row Component Props

type RowRendererProps<T> = {
  node: NodeApi<T>;
  innerRef: (el: HTMLDivElement | null) => void;
  attrs: HTMLAttributes<any>;
  children: ReactElement;
};

Node Component Props

The <NodeRenderer> is responsible for attaching the drag ref, the node style (padding for indentation), the visual look of the node, the edit input of the node, and anything else you can dream up.

There is a default renderer, but it's only there as a placeholder to get started. You'll want to create your own component for this. It is passed as the <Tree> components only child.

export type NodeRendererProps<T> = {
  style: CSSProperties;
  node: NodeApi<T>;
  tree: TreeApi<T>;
  dragHandle?: (el: HTMLDivElement | null) => void;
  preview?: boolean;
};

DragPreview Component Props

type DragPreviewProps = {
  offset: XYCoord | null;
  mouse: XYCoord | null;
  id: string | null;
  dragIds: string[];
  isDragging: boolean;
};

Cursor Component Props

export type CursorProps = {
  top: number;
  left: number;
  indent: number;
};

Node API Reference

State Properties

All these properties on the node instance return booleans related to the state of the node.

node.isRoot

Returns true if this is the root node. The root node is added internally by react-arborist and not shown in the UI.

node.isLeaf

Returns true if the children property is not an array.

node.isInternal

Returns true if the children property is an array.

node.isOpen

Returns true if node is internal and in an open state.

node.isEditing

Returns true if this node is currently being edited. Use this property in the NodeRenderer to render the rename form.

node.isSelected

Returns true if node is selected.

node.isSelectedStart

Returns true if node is the first of a contiguous group of selected nodes. Useful for styling.

node.isSelectedEnd

Returns true if node is the last of a contiguous group of selected nodes. Useful for styling.

node.isOnlySelection

Returns true if node is the only node selected in the tree.

node.isFocused

Returns true if node is focused.

node.isDragging

Returns true if node is being dragged.

node.willReceiveDrop

Returns true if node is internal and the user is hovering a dragged node over it.

node.state

Returns an object with all the above properties as keys and boolean values. Useful for adding class names to an element with a library like clsx or classnames.

type NodeState = {
  isEditing: boolean;
  isDragging: boolean;
  isSelected: boolean;
  isSelectedStart: boolean;
  isSelectedEnd: boolean;
  isFocused: boolean;
  isOpen: boolean;
  isClosed: boolean;
  isLeaf: boolean;
  isInternal: boolean;
  willReceiveDrop: boolean;
};

Accessors

node.childIndex

Returns the node's index in relation to its siblings.

node.next

Returns the next visible node. The node directly under this node in the tree component. Returns null if none exist.

node.prev

Returns the previous visible node. The node directly above this node in the tree component. Returns null if none exist.

node.nextSibling

Returns the next sibling in the data of this node. Returns null if none exist.

Selection Methods

node.select()

Select only this node.

node.deselect()

Deselect this node. Other nodes may still be selected.

node.selectMulti()

Select this node while maintaining all other selections.

node.selectContiguous()

Activation Methods

node.activate()

Runs the Tree props' onActivate callback passing in this node.

node.focus()

Focus this node.

Open/Close Methods

node.open()

Opens the node if it is an internal node.

node.close()

Closes the node if it is an internal node.

node.toggle()

Toggles the open/closed state of the node if it is an internal node.

node.openParents()

Opens all the parents of this node.

node.edit()

Moves this node into the editing state. Calling node.isEditing will return true.

node.submit(newName)

Submits newName string to the onRename handler. Moves this node out of the editing state.

node.reset()

Moves this node out of the editing state without submitting a new name.

Event Handlers

node.handleClick(event)

Tree API Reference

The tree api reference is stable across re-renders. It always has the most recent state and props.

Node Accessors

tree.get(id) : NodeApi | null

Get node by id from the visibleNodes array.

tree.at(index) : NodeApi | null

Get node by index from the visibleNodes array.

tree.visibleNodes : NodeApi[]

Returns an array of the visible nodes.

tree.firstNode : NodeApi | null

The first node in the visibleNodes array.

tree.lastNode : NodeApi | null

The last node in the visibleNodes array.

tree.focusedNode : NodeApi | null

The currently focused node.

tree.mostRecentNode : NodeApi | null

The most recently selected node.

tree.nextNode : NodeApi | null

The node directly after the focusedNode in the visibleNodes array.

tree.prevNode : NodeApi | null

The node directly before the focusedNode in the visibleNodes array.

Focus Methods

tree.hasFocus : boolean

Returns true if the the tree has focus somewhere within it.

tree.focus(id)

Focus on the node with id.

tree.isFocused(id) : boolean

Check if the node with id is focused.

tree.pageUp()

Move focus up one page.

tree.pageDown()

Move focus down one page.

Selection Methods

tree.selectedIds : Set<string>

Returns a set of ids that are selected.

tree.selectedNodes : NodeApi[]

Returns an array of nodes that are selected.

tree.hasNoSelection : boolean

Returns true if nothing is selected in the tree.

tree.hasSingleSelection : boolean

Returns true if there is only one selection.

tree.hasMultipleSelections : boolean

Returns true if there is more than one selection.

tree.isSelected(id) : boolean

Returns true if the node with id is selected.

tree.select(id, [opts])

tree.deselect(id)

Deselect the node with id.

tree.selectMulti(id, [opts])

Add to the selection the node with id. Accepts the same options object as select.

tree.selectContiguous(id)

Deselected nodes between the anchor and the last selected node, then select the nodes between the anchor and the node with id.

tree.deselectAll()

Deselect all nodes.

tree.selectAll()

Select all nodes.

Visibility

tree.open(id)

Open the node with id.

tree.close(id)

Close the node with id.

tree.toggle(id)

Toggle the open state of the node with id.

tree.openParents(id)

Open all parents of the node with id.

tree.openSiblings(id)

Open all siblings of the node with id.

tree.openAll()

Open all internal nodes.

tree.closeAll()

Close all internal nodes.

tree.isOpen(id) : boolean

Returns true if the node with id is open.

Drag and Drop

tree.isDragging(id) : boolean

Returns true if the node with id is being dragged.

tree.willReceiveDrop(id) : boolean

Returns true if the node with id is internal and is under the dragged node.

Scrolling

tree.scrollTo(id, [align])

Scroll to the node with id. If this node is not visible, this method will open all its parents. The align argument can be "auto" | "smart" | "center" | "end" | "start".

tree.scrollToOffset(offset)

tree.scrollOffset : number

Returns the list's current vertical scroll offset, in pixels from the top. Pairs with scrollToOffset to persist and restore the scroll position.

Properties

tree.isEditing : boolean

Returns true if the tree is editing a node.

tree.isFiltered : boolean

Returns true if the searchTerm prop is not an empty string when trimmed.

tree.filteredCount : number

tree.props : TreeProps

Returns all the props that were passed to the <Tree> component.

tree.root : NodeApi

Returns the root NodeApi instance. Its children are the Node representations of the data prop array.

Utilities

getTreeLinePrefix

function getTreeLinePrefix(
  node: NodeApi<any>,
  chars?: Partial<TreeLineChars>
): string;

type TreeLineChars = {
  last: string;   // default: "└ "
  middle: string; // default: "├ "
  pipe: string;   // default: "│ "
  blank: string;  // default: "\u3000 "
};

Wrap the prefix in a monospace span so the connectors line up:

import { Tree, getTreeLinePrefix } from "react-arborist";

function Node({ node, style }) {
  return (
    <div style={style}>
      <span style={{ fontFamily: "monospace" }}>{getTreeLinePrefix(node)}</span>
      {node.data.name}
    </div>
  );
}

Pass a partial chars object to override any of the default characters (e.g. for an ASCII-only style).

Contributing

The package ships with Jest tests under modules/react-arborist/src/**/*.test.ts?(x). From the package directory you can run:

cd modules/react-arborist
yarn test

Good starting points:

src/interfaces/tree-api.test.ts for pure API behavior
src/components/provider.test.tsx for rendered tree behavior
src/dnd/drag-hook.test.