React Sortable Tree

Drag-and-drop sortable representation of hierarchical data for React 18/19 with virtualized rendering powered by virtua and react-dnd. Storybook demos cover both basic and advanced scenarios.

Getting started

Install the package together with its peer dependencies:

npm install @nosferatu500/react-sortable-tree react-dnd react-dnd-html5-backend
# or
yarn add @nosferatu500/react-sortable-tree react-dnd react-dnd-html5-backend

The bundle is ESM-only and includes all styles via runtime injection (no separate CSS file is required).

Quick start

import { useState } from 'react'
import { SortableTree, TreeItem } from '@nosferatu500/react-sortable-tree'

const initialData: TreeItem[] = [
  { title: 'Chicken', children: [{ title: 'Egg' }] },
  { title: 'Fish', children: [{ title: 'Fingerling' }] },
]

export function ExampleTree() {
  const [treeData, setTreeData] = useState(initialData)

  return (
    <div style={{ height: 400 }}>
      <SortableTree
        treeData={treeData}
        onChange={setTreeData}
      />
    </div>
  )
}

Already have a surrounding react-dnd context? Use the context-less export instead:

import { SortableTreeWithoutDndContext } from '@nosferatu500/react-sortable-tree'

Component props

All props are typed in ReactSortableTreeProps (see src/react-sortable-tree.tsx).

Required props

Prop	Type	Description
treeData	TreeItem[]	Array of tree nodes with { title?, subtitle?, expanded?, children?, ...custom }
onChange	(treeData: TreeItem[]) => void	Called on every tree data change

Appearance & layout

Prop	Type	Default	Description
rowHeight	number | ((treeIndex, node, path) => number)	62	Height of each row in pixels
rowDirection	'ltr' | 'rtl'	'ltr'	Layout direction
scaffoldBlockPxWidth	number	44	Width of indent per level
slideRegionSize	number	100	Size of the drag slide region
style	CSSProperties	-	Styles for the outer container
innerStyle	CSSProperties	-	Styles for the virtual list
className	string	-	Class name for the outer container

Theming & custom renderers

Prop	Type	Description
theme	ThemeProps	Theme object (see Theming section)
nodeContentRenderer	ComponentType	Custom component for node content
treeNodeRenderer	ComponentType	Custom component for the entire tree row
placeholderRenderer	ComponentType	Custom component for empty tree state

Drag & drop

Prop	Type	Default	Description
canDrag	boolean | ((params) => boolean)	true	Whether nodes can be dragged
canDrop	(params) => boolean	-	Validate if a drop is allowed
canNodeHaveChildren	(node) => boolean	() => true	Whether a node can have children
maxDepth	number	-	Maximum nesting depth
shouldCopyOnOutsideDrop	boolean | ((params) => boolean)	false	Copy node when dropped outside
dndType	string	-	Custom drag type for multi-tree setups
onMoveNode	(params) => void	-	Called after a node is moved
onDragStateChanged	(params) => void	-	Called when drag state changes

Search

Prop	Type	Description
searchQuery	string	Search query string
searchMethod	(params) => boolean	Custom search matching function
searchFocusOffset	number	Index of the focused match
searchFinishCallback	(matches) => void	Called when search completes
onlyExpandSearchedNodes	boolean	Collapse non-matching paths

Other

Prop	Type	Description
generateNodeProps	(params) => object	Add custom props to each node
getNodeKey	(node) => string | number	Generate stable node keys
onVisibilityToggle	(params) => void	Called when node expands/collapses
loadCollapsedLazyChildren	boolean	Load lazy children before expanding
virtuaRef	RefObject<VListHandle>	Direct access to the virtual list
dragDropManager	object	External react-dnd manager

Theming

The component supports theming through CSS variables, the theme prop, and custom renderers.

CSS Variables

Override these CSS variables on the .rst__tree class or a parent element:

.my-custom-theme .rst__tree {
  --rst-row-height: 62px;
  --rst-block-width: 44px;
  --rst-handle-width: 44px;
  --rst-line-color: #000;
  --rst-line-highlight: #36c2f6;
  --rst-line-highlight-arrow: white;
  --rst-primary-color: #36c2f6;
  --rst-focus-color: #fc6421;
  --rst-match-color: #0080ff;
  --rst-bg-landing: lightblue;
  --rst-bg-cancel: #e6a8ad;
  --rst-text-color: #333;
  --rst-icon-color: #6DB3F2;
  --rst-button-bg: #fff;
  --rst-button-border: #989898;
}

Theme prop

The theme prop accepts an object with these properties:

type ThemeProps = {
  style?: React.CSSProperties
  innerStyle?: React.CSSProperties
  scaffoldBlockPxWidth?: number
  slideRegionSize?: number
  treeNodeRenderer?: React.ComponentType
  nodeContentRenderer?: React.ComponentType
  placeholderRenderer?: React.ComponentType
  dndType?: string
}

Theme values are merged with component props, with direct props taking precedence.

Example: File Explorer Theme

The library includes a File Explorer theme example in the Storybook demos:

import { SortableTree } from '@nosferatu500/react-sortable-tree'
import { fileExplorerTheme, FILE_EXPLORER_THEME_CLASS } from './themes/file-explorer'

function FileTree() {
  const [treeData, setTreeData] = useState([
    { title: 'src', isDirectory: true, expanded: true, children: [
      { title: 'index.ts' },
      { title: 'App.tsx' },
    ]},
    { title: 'package.json' },
  ])

  return (
    <div className={FILE_EXPLORER_THEME_CLASS}>
      <SortableTree
        treeData={treeData}
        onChange={setTreeData}
        theme={fileExplorerTheme}
        rowHeight={28}
        // Only folders can have children
        canNodeHaveChildren={(node) => node.isDirectory === true}
        // Only allow dropping into folders
        canDrop={({ nextParent }) =>
          !nextParent || nextParent.isDirectory === true
        }
      />
    </div>
  )
}

For dark mode, add the rst__file-explorer-dark class to the wrapper.

Creating custom themes

To create a custom theme:

1. Create a custom nodeContentRenderer component (see src/node-renderer-default.tsx for reference)
2. Add CSS styles with your theme class
3. Export a theme object:

export const myTheme = {
  nodeContentRenderer: MyCustomNodeRenderer,
  scaffoldBlockPxWidth: 24,
  slideRegionSize: 50,
}

Data helper functions

Utilities exported from the package:

Node manipulation

• addNodeUnderParent({ treeData, newNode, parentKey, getNodeKey, expandParent?, addAsFirstChild? }) - Add a node under a parent
• insertNode({ treeData, newNode, depth, minimumTreeIndex, getNodeKey, expandParent? }) - Insert a node at a specific position
• removeNode({ treeData, path, getNodeKey }) - Remove a node by path
• removeNodeAtPath({ treeData, path, getNodeKey }) - Remove a node at exact path
• changeNodeAtPath({ treeData, path, newNode, getNodeKey }) - Update a node at path

Tree inspection

• getNodeAtPath({ treeData, path, getNodeKey }) - Get node at path
• getDescendantCount({ node }) - Count all descendants
• getDepth(node) - Get nesting depth of a node
• isDescendant(older, younger) - Check parent-child relationship
• getVisibleNodeCount({ treeData }) - Count visible (expanded) nodes

Tree traversal

• walk({ treeData, getNodeKey, callback, ignoreCollapsed? }) - Walk tree depth-first
• map({ treeData, getNodeKey, callback, ignoreCollapsed? }) - Transform all nodes
• toggleExpandedForAll({ treeData, expanded }) - Expand or collapse all nodes
• find({ treeData, getNodeKey, searchQuery, searchMethod, expandAllMatchPaths? }) - Search with path expansion

Data conversion

• getFlatDataFromTree({ treeData, getNodeKey, ignoreCollapsed? }) - Convert to flat array
• getTreeFromFlatData({ flatData, getKey, getParentKey, rootKey? }) - Convert from flat array

Default handlers

• defaultGetNodeKey({ treeIndex }) - Default key generator (uses index)
• defaultSearchMethod({ node, searchQuery }) - Default search (matches title)

License

MIT