react-bootstrap-tree-editor

Overview

An interactive tree editor built on react-bootstrap and powered by versatile-tree.

Features include:

🌲 Interactive tree editing
- React-Bootstrap powered components and hooks for editing trees.
🌐 Expansion Management
- Track which nodes are expanded/collapsed.
👉 Focus Management
- Track and retrieve which node has focus.
🔥 Shortcuts
- Customizable shortcuts for easy tree manipulation.
🖊️ Edit and View Modes
- Easily switch between editing and viewing.
🔍 Filters & Search
- Provide a filter function to make tree searchable and filterable.
🗑️ Deletion & Recovery
- Delete nodes and easily recover them.
🌴 Powered by versatile-tree
- Easy to use tree structure. Easily convert tree to/from Object and JSON forms.

Donate

If this project helped you, please consider buying me a coffee. Your support is much appreciated!

Documentation
Overview
- Features include:
Donate
Table of Contents
Installation
Quick Start
Available Components
Available Hooks
Tree Options
TypeScript
Icon Attribution
Contributing
⭐ Found It Helpful? Star It!
License

Installation

npm i react-bootstrap-tree-editor

Quick Start

It's highly recommended you check out the demo and its source to quickly get yourself up and running.

Import the following:

import {
  BasicTreeNodeComponent,
  defaultTreeControllerOptions,
  defaultTreeData,
  useTreeController,
  useTreeShortcuts,
  useTreeState,
} from 'react-bootstrap-tree-editor';

Inside your function component:

const treeOptions = defaultTreeControllerOptions;
const [tree, setTree] = useTreeState(defaultTreeData);
const treeController = useTreeController(tree, setTree, treeOptions);
const shortcuts = useTreeShortcuts(treeController, document);

// Ensure there's always at least one item to edit
React.useEffect(() => {
  if (!treeController.tree.hasChildren()) {
    const newNodeData = treeController.options.createNewData();
    const node = treeController.mutations.addChildNodeData(treeController.tree, newNodeData);
    treeController.focus.setFocusedNode(node);
  }
}, [treeController.focus, treeController.mutations, treeController.tree, treeController.options]);

Render the component:

<BasicTreeNodeComponent
  node={treeController.tree}
  treeController={treeController}
  editable={true}
  shortcuts={shortcuts}
  showBullets={false}
  showPointer={false}
/>

Available Components

BasicTreeNodeComponent - This is the main component used to render and edit trees. Use this as a starting point if you'd like to customize how trees are rendered.

Available Hooks

useTreeState - A convenience hook for managing tree state with React.useState().
useTreeController - This is the main hook used to control the tree editor.
useTreeShortcuts - A hook that listens for customizable shortcuts on the provided DOM object.

By default, tree nodes have an ID with property name id, and titles with property name title. New node data is created with an ID set to a random v4 UUID. For example, e7a422f6-d6f0-4c71-8545-9b2c71c50491.

The default options can be imported via the following:

import { defaultTreeControllerOptions } from 'react-bootstrap-tree-editor';

To customize options, you can provide useTreeController with your own tree options. For example, let's suppose we'd like to use uid as the ID prop and name as the title prop, and generate our own custom IDs. To support this, you can create your own custom tree controller options like so:

// Custom ID generator
const customIdGenerator = () => `${Date.now()}`;

// Configure custom ID, title, and new node data
const customTreeControllerOptions = {
  idPropertyName: 'uid',
  titlePropertyName: 'name',
  createNewData: () => ({ uid: customIdGenerator(), name: '' }),
};

// ...
const treeController = useTreeController(tree, setTree, customTreeControllerOptions);

For major changes, open an issue first to discuss what you'd like to change.

⭐ Found It Helpful? Star It!

If you found this project helpful, let the community know by giving it a star: 👉⭐

License

See LICENSE.md.

react-bootstrap-tree-editor