@henliwu1491/react-tree

React Tree

React Tree is a tree data structure ui library designed for easily building tree components.

Live Demo

Check out our interactive demo showcasing basic usage, custom icons, and state management examples.

Note: This project is for testing purposes only and is not intended for production use.

Features

• 🪝  Hook provided: useTreeView hooks provide tree expanded & selected state for easily render tree component

• 🖼️  Custom Icons: Supports custom icons using React nodes for enhanced visual appeal

• 🎯  Flexible Selection: Support both single and multiple node selection

• 🎨  Customizable Labels: Easily customize node labels with your own render function

• 🌲  Nested Data: Handle deeply nested tree structures with ease

Installation

# Using npm
npm install @henliwu1491/react-tree

# Using yarn
yarn add @henliwu1491/react-tree

# Using pnpm
pnpm add @henliwu1491/react-tree

Include CSS

import "@henliwu1491/react-tree/dist/style.css"

Usage

Example:

<TreeView />

Basic usage

import { TreeView } from "@henliwu1491/react-tree";

export default function Tree() {
  const [selectedId] = React.useState(["12"]);
  const [expandedId] = React.useState(["2", "21", "221"]);

  return <TreeView initialState={{ selectedId, expandedId }} data={data} />;
}

With custom label

import { TreeView } from "@henliwu1491/react-tree";

export default function Tree() {
  const [selectedId] = React.useState(["12"]);
  const [expandedId] = React.useState(["2", "21", "221"]);

  return (
    <TreeView
      initialState={{ selectedId, expandedId }}
      data={data}
      getLabel={(item) => {
        if (item.type === "leaf") {
          return (
            <div className="flex">
              <div>Leaf: {item.label}</div>
            </div>
          );
        }
        return item.label;
      }}
    />
  );
}

With custom icon

import { TreeView } from "@henliwu1491/react-tree";

export default function Tree() {
  const [selectedId] = React.useState(["12"]);
  const [expandedId] = React.useState(["2", "21", "221"]);

  return (
    <TreeView
      initialState={{ selectedId, expandedId }}
      data={data}
      icon={{
        expand: "▲",
        collapse: "▼",
        leaf: "🌱",
        checked: "☑",
        unchecked: "☐",
        indeterminate: "-", // Or <span>your custom React component</span>
      }}
    />
  );
}

With controlled state

export default function Tree() {
  const [selectedId, setSelectedId] = React.useState(["12"]);
  const [expandedId, setExpandedId] = React.useState(["2", "21", "221"]);

  return (
    <TreeView
      value={{ selectedId, expandedId }}
      data={data}
      onExpand={(item) => {
        setExpandedId((prev) =>
          prev.length === 0
            ? [item.value]
            : prev.indexOf(item.value) === -1
              ? [...prev, item.value]
              : prev.filter((id) => id !== item.value),
        );
      }}
      onSelect={(item) => {
        setSelectedId((prev) =>
          prev.length === 0
            ? [item.value]
            : prev.indexOf(item.value) === -1
              ? [...prev, item.value]
              : prev.filter((id) => id !== item.value),
        );
      }}
    />
  );
}

useTreeView Props

Options

Below are the available configuration options for the hook:

Name	Type	Description	Default
initialState	TreeInitialState	Optional.
data	TreeRawData[]	Required. Your raw tree structure data. (must contain id, label and value key)
onExpand	function	Optional. Callback function you can get node item from the parameter.
onSelect	function	Optional. Callback function you can get node item from the parameter.
leafKey	string	Optional. Customized leaf node.	'leaf'

Instance

Name	Type	Description	Default
expandedId	string[]	Array of expanded node IDs	[]
selectedId	string[]	Array of selected node IDs	[]
data	TreeRawData[]	Processed tree data structure	[]
onExpand	function	Callback when node is expanded/collapsed	-
onSelect	function	Callback when node is selected/deselected	-
setExpand	(string) => void	Function to expand/collapse a node	-
checkNodeAndChildren	(string) => void	Select a node and all its children	-
checkSingleNode	(string) => void	Select only the specified node	-
setInitialState	(TreeInitialState) => void	Set the initial expanded and selected state	-

<TreeView /> Props

Options

Below are the available configuration options for the component:

Name	Type	Description	Default
initialState	TreeInitialState	Optional.
data	TreeRawData[]	Required. Your raw tree structure data. (must contain id, label and value key)
onExpand	function	Optional. Callback function you can get node item from the parameter.
onSelect	function	Optional. Callback function you can get node item from the parameter.
value	TreeInitialState	Optional. Control your own state.
icon	IconConfig	Optional. Provide your custom icon, React.ReactNode only.
getLabel	function	Optional. Your own label render function.
leafKey	string	Optional. Customized leaf node.	'leaf'

initialState

export type TreeInitialState = {
  expandedId: string[];
  selectedId: string[];
};

data

id, label, value are required. And if nested data is provided, children is also required.

export type TreeRawData = {
  id: string;
  label: string;
  value: string;
  children?: TreeRawData[];
  [key: string]: any;
};

Helper functions

Name	Type	Description	Default
getLeafNodes	function	(data: TreeData[], leafkey?: string) => TreeData[]
getNormalizedNodes	function	(data: TreeRawData[], level = 0) => TreeRawData[]
getFlattenNodes	function	(data: TreeRawData[]) => TreeRawData[]
getExpandedNodes	function	(nodes: TreeData[], expandedId: TreeData['value'][]) => TreeData[]
getSelectedNodes	function	(nodes: TreeData[], selectedId: TreeData['value'][]) => TreeData[]
getSelectedIdWithChildren	function	(nodes: TreeData[], selectedIds: TreeData['value'][], checkId: string, set: Set<string or number> = new Set(selectedIds)) => TreeData[]

🤝Contributing

We welcome contributions! If you find a bug or have an idea for improvement, please open an issue or submit a pull request on Github.

• Fork it
• Create your feature branch (git checkout -b new-feature)
• Commit your changes (git commit -am 'Add feature')
• Push to the branch (git push origin new-feature)
• Create a new Pull Request

Author ✨

💻   Henry Wu(吳亨利)

• Github

Licence

This project is licensed under the MIT License.