React DnD TreeView

A draggable / droppable React-based treeview component.
You can use render props to create each node freely.

Demo

• JavaScript | TypeScript

Examples (on CodeSandbox)

Some of the examples below use Material-UI components, but TreeView does not depend on Material-UI, so you can use other libraries or your own custom components.

• Minimum configuration (JavaScript | TypeScript)
• Custom node (JavaScript | TypeScript)
• Custom drag preview (JavaScript | TypeScript)
• Select node (JavaScript | TypeScript)
• Multiple selections(checkobx) (JavaScript | TypeScript)
• Opening and closing all nodes (JavaScript | TypeScript)
• Auto expand with drag over node (JavaScript | TypeScript)
• Initialize with open parents (JavaScript | TypeScript)
• Editable nodes (JavaScript | TypeScript)
• Manual sort with placeholder (JavaScript | TypeScript)

Getting Started

Installation

$ npm install --save @minoru/react-dnd-treeview

Usage

import{Tree}from"@minoru/react-dnd-treeview";
...
const[treeData,setTreeData]=useState(initialData);consthandleDrop=(newTreeData)=>setTreeData(newTreeData);<Treetree={treeData}rootId={0}onDrop={handleDrop}render={(node,{depth, isOpen, onToggle})=>(<divstyle={{marginLeft: depth*10}}>{node.droppable&&(<spanonClick={onToggle}>{isOpen ? "[-]" : "[+]"}</span>)}{node.text}</div>)}/>

Data Structure

In order to display the tree,
we need to pass the following data to the Tree component

Basic example

The minimal data structure for representing the tree is shown in the following example

[
{
"id": 1,
"parent": 0,
"droppable": true,
"text": "Folder 1"
},
{
"id": 2,
"parent": 1,
"text": "File 1-1"
},
{
"id": 3,
"parent": 1,
"text": "File 1-2"
},
{
"id": 4,
"parent": 0,
"droppable": true,
"text": "Folder 2"
},
{
"id": 5,
"parent": 4,
"droppable": true,
"text": "Folder 2-1"
},
{
"id": 6,
"parent": 5,
"text": "File 2-1-1"
}
]

Optional data

If you want to pass custom properties to each node's rendering,
you can use the data property.

[
{
"id": 1,
"parent": 0,
"droppable": true,
"text": "Folder 1"
},
{
"id": 2,
"parent": 1,
"text": "File 1-1",
"data": {
"fileType": "csv",
"fileSize": "0.5MB"
}
},
{
"id": 3,
"parent": 1,
"text": "File 1-2",
"data": {
"fileType": "pdf",
"fileSize": "4.8MB"
}
},
{
"id": 4,
"parent": 0,
"droppable": true,
"text": "Folder 2"
},
{
"id": 5,
"parent": 4,
"droppable": true,
"text": "Folder 2-1"
},
{
"id": 6,
"parent": 5,
"text": "File 2-1-1",
"data": {
"fileType": "image",
"fileSize": "2.1MB"
}
}
]

Node Properties

Key	Type	Required	Default	Description
id	number | string	yes	-	Identifier of each node
parent	number | string	yes	-	Parent id of each node
text	string	yes	-	Node label
droppable	boolean	no	false	If true, child nodes will be accepted and it will be able to drop other node
data	any	no	undefined	Additional data to be injected into each node. These data are available in the render props.

Component API

Props	Type	Required	Default	Description
tree	array	yes		The data representing the tree structure. An array of node data.
rootId	number | string	yes		The id of the root node. It is the parent id of the shallowest node displayed in the tree view.
classes	object	no	undefined	A set of CSS class names to be applied to a specific area in the tree view. See the Component Styling section for more information.
listComponent	string	no	ul	HTML tag for list.
listItemComponent	string	no	li	HTML tag for list items.
render	function	yes		The render function of each node. Please refer to the Render prop section for more details about the render functions.
dragPreviewRender	function	no	undefined	Render function for customizing the drag preview. See the Dragging Preview section for more information on customizing the drag preview NOTE: The default preview is not displayed on touch devices. Therefore, if you want to support touch devices, please define a custom preview in dragPreviewRender.
onDrop	function	yes		Callback function for when the state of the tree is changed. The new data is passed as the argument. See the onDrop callback section for more information.
canDrop	function	no	undefined	A callback function to determine if a given node can be dropped to another node. If nothing is returned (or if undefined is returned), the default rules are followed. If it returns true or false, the default rules will be overridden and the dropable properties of each node will not be referenced. This callback takes the current tree and the same option object that is passed to the onDrop callback. See the canDrop callback section for more information.
canDrag	function	no	undefined	Callback function which should return true or false depending on if a give node should be draggable. By default, all nodes are draggable.
sort	function | boolean	no	true	This property controls the order of the child nodes. By default (true), they are sorted by the text property of each node. If false, sorting is disabled. In this case, the nodes will follow the order of the array passed to the tree property. It is also possible to customize the sorting by passing a callback function.
insertDroppableFirst	boolean	no	true	Specifies whether droppable nodes should be placed first in the list of child nodes.
placeholderRender	function	no	undefined	Render function for the drop destination placeholder. By default, placeholder is not displayed. See the Manual sort with placeholder section for more information on using placeholder.
placeholderComponent	string	no	li	HTML tag for placeholder.
dropTargetOffset	number	no	0	Effective drop range of a dropable node. It is specified in pixels from the top or bottom of the node. Used to insert a node anywhere using placeholders. See the Manual sort with placeholder placeholder section for more information on using placeholder.
initialOpen	boolean | array	no	false	If true, all parent nodes will be initialized to the open state. If an array of node IDs is passed instead of the boolean value, only the specified node will be initialized in the open state.

Render prop

To render each tree node, please pass a render function to the render property.

<Tree{...props}render={(node,{ depth, isOpen, draggable, onToggle })=>(<divstyle={{marginLeft: depth*10}}>{node.droppable&&(<spanonClick={onToggle}>{isOpen ? "[-]" : "[+]"}</span>)}{node.text}</div>)}/>

The arguments passed to the render function are as follows

Name	Type	Description
data	object	Node data. (an element in the tree data array)
options.depth	number	The depth of the node hierarchy.
options.isOpen	boolean	The open and closed state of the node. If droppable is not true, isOpen is always false.
options.draggable	boolean	Indicates whether this node is draggable or not.
options.hasChild	boolean	Flag indicating whether or not the node has children. It is true if the node has children, false otherwise.
options.onToggle	function	An event handler for the open/close button of a node.

Dragging Preview

By default, the drag preview is a screenshot of a DOM node.
The dragPreviewRender property allows you to display a custom React component instead of a screenshot.

NOTE:
The default preview is not displayed on touch devices.
Therefore, if you want to support touch devices, please define a custom preview in dragPreviewRender.

<Tree{...props}dragPreviewRender={(monitorProps)=>{constitem=monitorProps.item;return(<div><p>{item.text}</p></div>);}}/>

The data passed to dragPreviewRender contains the following properties

Name	Type	Description
item	object	Node data. (an element in the tree data array) It also includes the ref property, which is a reference to the HTML element to be dragged.
clientOffset	object	The client offset of the pointer during the dragging operation. It is in the format of {x: number, y: number}. If the item is not being dragged, it is set to null.

onDrop callback

If the tree is modified by drag-and-drop, the changes can be retrieved by the onDrop callback.

const[treeData,setTreeData]=useState(initialTreeData);consthandleDrop=(newTree,{ dragSourceId, dropTargetId, dragSource, dropTarget })=>{// Do somethingsetTreeData(newTree);};return<Tree{...props}tree={treeData}onDrop={handleDrop}/>;

The arguments passed to the onDrop callback function are as follows

Name	Type	Description
newTree	array	This data represents the updated TreeView. To redraw the modified TreeView, you need to set this data to the tree property.
options.dragSourceId	number | string	node id of the dragging source
options.dropTargetId	number | string	node id of the drop destination. If the drop destination is the root node, it will be the value of the rootId property.
options.dragSource	object	node item of the dragging source
options.dropTarget	object | undefined	node item of the drop destination. If the drop destination is the root node, it will be undefined

canDrop callback

By default, it allows dropping to any dropable node (or root node) except its own descendants. This callback can override the default rules.

If it returns nothing or returns undefined, the default rules will be applied. If it returns a boolean value, it will override the default rules and the droppable property of each node will no longer be referenced.

If it returns false and the user drops the dragged node, no action will be taken and the onDrop callback will not be fired.

This callback takes the same parameters as the onDrop callback, but the first parameter specifies the current tree.

constcanDrop=(currentTree,{ dragSourceId, dropTargetId, dragSource, dropTarget })=>{returntrue;// orreturnfalse;// orreturn;// orreturnundefined;};return<Tree{...props}tree={treeData}canDrop={canDrop}/>;

NOTE:
When overriding the default rules by returning true or false, be careful of inconsistencies in the tree structure.
For example, if you allow dropping from a parent node to a child node as shown in the figure below, inconsistency will occur and the tree will collapse.

Manual sort with placeholder

By default, nodes are automatically sorted and cannot be sorted manually, but by combining some APIs, you can sort them manually and display placeholders as follows.

The following is an example (excerpt) of the implementation of manual sort of nodes and placeholder display.

import{CustomPlaceholder}from"./CustomPlaceholder";importstylesfrom"./App.module.css";functionApp(){const[treeData,setTreeData]=useState(SampleData);consthandleDrop=(newTree)=>setTreeData(newTree);<Tree{...props}tree={treData}onDrop={handleDrop}classes={{placeholder: styles.placeholder,}}sort={false}insertDroppableFirst={false}canDrop={(tree,{ dragSource, dropTargetId })=>{if(dragSource?.parent===dropTargetId){returntrue;}}}dropTargetOffset={5}placeholderRender={(node,{ depth })=>(<CustomPlaceholdernode={node}depth={depth}/>)}/>;}

Component Styling

You are free to define the styling of individual nodes in the tree in your Render props, but the rest of the tree can be styled by specifying the CSS class name for the classes property.

<Tree{...props}classes={{root: "my-root-classname",dragOver: "my-dragover-classname",}}/>

You can use the following keys for the objects you pass to the classes property. Neither key is required.

Name	Description
root	CSS class name to give to the top-level container element (by default, ul tag) that wraps all nodes.
container	CSS class name to give to the element wrapping the list of nodes of the same hierarchy (by default, ul tag).
dropTarget	CSS class name to give to the area that can be dropped during a node dragging operation.
draggingSource	CSS class name to give to the node during the dragging operation.
placeholder	CSS class name to give to the element wrapping the placeholder (by default, li tag).

Usage to open / close methods

The open/close status of a node is managed within the Tree component, but the methods for opening and closing nodes are public, so they can be controlled from outside the Tree component.

constref=useRef(null);consthandleOpenAll=()=>ref.current.openAll();consthandleCloseAll=()=>ref.current.closeAll();// open /close method can be passed a node ID or an array of node IDsconsthandleOpen=(nodeId)=>ref.current.open(nodeId);consthandleClose=(nodeId)=>ref.current.close(nodeId);<Treeref={ref}{...props}><buttononClick={handleOpenAll}>Open All Folders</button><buttononClick={handleCloseAll}>Close All Folders</button><buttononClick={handleOpen}>Open specific folder(s)</button><buttononClick={handleClose}>Close specific folder(s)</button>

License

MIT.