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 />

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} />;
}

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;
      }}
    />
  );
}

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>
      }}
    />
  );
}

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.

1. Fork it
2. Create your feature branch (git checkout -b new-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin new-feature)
5. Create a new Pull Request

Author ✨

💻   Henry Wu(吳亨利)

• Github

Licence

This project is licensed under the MIT License.