Getting started

Install

tree-element is published on npm:

npm install tree-element

The package contains:

File	What it is
lib/	The source compiled to ES modules, with type declarations. This is what import "tree-element" resolves to.
tree_element.js	The bundle: an IIFE that defines a global TreeElement.
tree_element.debug.js	The same bundle, unminified.
tree_element.css	The stylesheet.

If you do not use a bundler, copy tree_element.js and tree_element.css from node_modules/tree-element into your project and load them with a <link> and a <script> tag, as in the example below. You can also build these files yourself from a checkout with pnpm install && pnpm production.

Create a tree

tree-element renders into an element that you pass to the constructor. That element does not have to contain anything; the tree fills it.

<link rel="stylesheet" href="tree_element.css" />

<div id="tree1"></div>

<script src="tree_element.js"></script>
<script>
  const data = [
    {
      name: "Saurischia",
      id: 1,
      children: [
        { name: "Herrerasaurians", id: 2 },
        {
          name: "Theropods",
          id: 3,
          children: [
            { name: "Coelophysoids", id: 4 },
            { name: "Ceratosaurians", id: 5 },
          ],
        },
      ],
    },
    { name: "Ornithischia", id: 6 },
  ];

  const tree = new TreeElement({
    autoOpen: 0,
    data,
    htmlElement: document.getElementById("tree1"),
  });
</script>

That gives you this:

htmlElement is the only required option; everything else has a default. See Options for the full list, and Styling for the class names the stylesheet uses.

TIP

Every tree on this site is the real widget, compiled from src. If a demo behaves differently from what a page says, the page is wrong — please open an issue.

With a bundler

Import the package entry point. Bundlers pick up the ES modules in lib, so the class is the default export and the types come along:

import TreeElement from "tree-element";

const tree = new TreeElement({
  data: [{ name: "node1" }, { name: "node2" }],
  htmlElement: document.getElementById("tree1"),
});

The stylesheet can be imported the same way:

import "tree-element/tree_element.css";

Example project

tree-element-example is a small Vite project that uses the package from npm, with a page for each topic: the basics and events, drag and drop, loading on demand, saving state, styling and accessibility. Clone it to see a complete setup, or to start your own project from it.

Try it in this repository

The repository contains a dev server with a working example (devserver/index.html and devserver/devserver.js):

pnpm install
pnpm devserver

It builds the bundle, watches src, and serves the example on http://localhost:8080.

React to what the user does

The tree dispatches events on its element. They are regular CustomEvents, so addEventListener is all you need:

const element = document.getElementById("tree1");

element.addEventListener("tree.click", (e) => {
  console.log("clicked", e.detail.node.name);
});

Change the tree from code

Every node is a Node object, and the tree has methods to find them and change them:

const node = tree.getNodeByName("Theropods");

tree.openNode(node);
tree.selectNode(node);
tree.appendNode({ name: "Tyrannosauroids", id: 9 }, node);

Select a node and use the buttons — they call appendNode, updateNode, removeNode, openNode and closeNode on the tree below:

The methods reference has the full list.

Clean up

Call deinit when you remove the tree from the page. It empties the element and removes the document-level keyboard listener:

tree.deinit();

Next steps

• Data — the node data format
• Loading on demand — fetch subtrees from the server
• Selection — selecting nodes and keyboard navigation
• Drag and drop — moving nodes
• Saving state — remember open and selected nodes