Skip to main content

Get Started

The following document shows how React Complex Tree can be installed and used in your web projects.

Installation#

To start using React Complex Table, install it to your project as a dependency via

npm install react-complex-tree

or

yarn add react-complex-tree

Importing#

You can always import any of the entities used in the examples directly as named imports from the react-complex-tree package.

import { UncontrolledTreeEnvironment, Tree, StaticTreeDataProvider } from 'react-complex-tree';

Make sure to also import the CSS file that defines the default styling of React Complex Tree, if you do not intent do provide manual CSS declarations. More on the default stylings and possibilities to modify those are given in the guide on styling customizability. Import the CSS in one of the following ways:

  • Import it directly in your JS code, if you use Webpack with a loader that can load CSS files:
    import 'react-complex-tree/lib/style.css';
  • Import it from within a CSS file with node-style package resolution:
    @import '~react-complex-tree/lib/style.css';
  • Import it in your HTML by linking to the CSS file in your node_modules or on unpkg:
    <head>  <link href="https://unpkg.com/react-complex-tree/lib/style.css" rel="stylesheet" /></head>

React Complex Tree comes compiled as CommonJS package, ESM package and ESNext package.

Using CDNs#

The package is also available as UMD bundle which can be consumed from the unpkg CDN. You can import it in your HTML by copying the following snippet:

<head>  <link href="https://unpkg.com/react-complex-tree/lib/style.css" rel="stylesheet" />  <script src="https://unpkg.com/react-complex-tree/lib/bundle.js"></script></head>

Importing the file https://unpkg.com/react-complex-tree/lib/bundle.js will make the variable ReactComplexTree available to the global scope. All exports from the package are then available as children of that variable, i.e. ReactComplexTree.UncontrolledTreeEnvironment can be used to reference the react component of an uncontrolled tree environment.

Integrating React Complex Tree into your project#

After installation, import the package and start using it by creating a new tree environment that contains a tree instance.

Live Editor
Result
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

The example above uses an UncontrolledTreeEnvironment, which is the easiest way to get started as it maintains the tree view state in itself. Inside the environment, the Tree itself is added to the DOM structure. You can add multiple trees within one environment, that share a common state. Each tree needs to provide

  • An individual ID for the tree, which remains unique for that tree.
  • Which item is used as root item for that tree. Different trees may show different items as root.
  • Optionally, a label, which is used as accessibility label for that tree to describe it to screen readers.

Individual trees do not provide their own state, but share the state that is provided by the environment.

For the environment, there are three ways to implement your tree environment:

  • Use an UncontrolledTreeEnvironment and a StaticTreeDataProvider that provides the items. This is the easiest approach and is described below.
  • Use an UncontrolledTreeEnvironment and implement a custom TreeDataProvider. This is similarly easy and provides the ability to directly react to change events and define a lazy item-loading strategy. This approach is most likely the best way to integrate React Complex Tree in realistic scenarios. This approach is described here TODO
  • Use an StaticTreeDataProvider. This requires you to define your own logic to manage the view state, thus requiring the most effort, but also provides the most customizability. This approach is described here TODO

Providing the data for the tree#

When integrating React Complex Tree with an uncontrolled environment and a static tree data provider, items must be provided as explicit data source. An example for such items looks like this:

const items = {  root: {    index: 'root',    canMove: true,    hasChildren: true,    children: ['child1', 'child2'],    data: 'Root item',    canRename: true,  },  child1: {    index: 'child1',    canMove: true,    hasChildren: false,    children: [],    data: 'Child item 1',    canRename: true,  },  child2: {    index: 'child2',    canMove: true,    hasChildren: false,    children: [],    data: 'Child item 2',    canRename: true,  },};

Each item needs to implement the TreeItem interface. The data attribute is generic and can contain any kind of data such as objects or strings. The environment then also needs to implement the getItemTitle method, which derives the title of the item given a TreeItem instance. In our example, where data is just a string that contains the title, we can use the trivial implementation of getItemTitle={item => item.data}.