Events

The tree dispatches CustomEvents on the element it was created in. They bubble and they are cancelable, and their data is in event.detail:

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

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

Everything you do in this tree is logged below it, most recent first:

Events

Click a node, open a folder, or drag something.

Because the events bubble, you can also listen higher up in the document, which is handy when the tree is re-created:

document.addEventListener("tree.select", (e) => {
  console.log(e.detail.node);
});

Lifecycle

tree.init

"tree.init": undefined;

Dispatched once, after the tree is rendered for the first time. With dataUrl this is after the data has arrived, so it is the moment the api is safe to use:

element.addEventListener("tree.init", () => {
  tree.selectNode(tree.getNodeByName("node1"));
});

No detail.

With inline data, the tree is rendered inside the constructor, so this event has already fired by the time the constructor returns. Add the listener to the element before creating the tree:

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

element.addEventListener("tree.init", () => {
  // ...
});

const tree = new TreeElement({ data, htmlElement: element });

---

tree.refresh

"tree.refresh": undefined;

Dispatched after the tree has been re-rendered. No detail.

Mouse

tree.click

"tree.click": object;

Dispatched when a node title is clicked. Call preventDefault() to stop the tree from selecting the node:

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

Name	Type
node	Node
originalEvent	MouseEvent

---

tree.dblclick

"tree.dblclick": object;

Dispatched when a node title is double clicked.

Name	Type
node	Node
originalEvent	MouseEvent

---

tree.contextmenu

"tree.contextmenu": object;

Dispatched on a right click on a node, unless useContextMenu is false. The browser's own menu is suppressed.

Name	Type
node	Node
originalEvent	MouseEvent

Opening and closing

tree.open

"tree.open": object;

Dispatched when a folder is opened, after the animation.

Name	Type
node	Node

---

tree.close

"tree.close": object;

Dispatched when a folder is closed, after the animation.

Name	Type
node	Node

Selection

tree.select

"tree.select": object;

Dispatched when a node is selected. A deselection is tree.deselect instead, so node is always a node here.

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

Name	Type	Description
deselectedNode	Node | null	The node that was selected before, if any. When several nodes were selected, this is the first; the others get a tree.deselect, dispatched before this event.
node	Node	The node that is now selected.

---

tree.deselect

"tree.deselect": object;

Dispatched when the selected node is deselected, which happens when it is clicked again or passed to selectNode again with mustToggle: true. No tree.select is dispatched for it.

When several nodes are selected and a click or selectNode selects just one node, it is dispatched for each node that loses the selection, except the one in the deselectedNode of tree.select.

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

Selecting another node does not dispatch it — that is a tree.select with the previous node in deselectedNode. It is also not dispatched by selectNode without mustToggle: true, selectNode(null), removeFromSelection, removeNode, loadData and restoring a saved state.

Name	Type
node	Node

Drag and drop

tree.move

"tree.move": object;

Dispatched when a node is dropped after a drag.

detail	Type
moveInfo.movedNode	Node
moveInfo.targetNode	Node
moveInfo.position	"before" | "after" | "inside"
moveInfo.previousParent	Node | null
moveInfo.originalEvent	Event
moveInfo.doMove	() => void

Call preventDefault() to keep the tree as it is, and moveInfo.doMove() to apply the move later. See Drag and drop.

Loading data

tree.set_data

"tree.set_data": object;

Dispatched when data is set on the tree, both from the data option and from a url.

Name	Type	Description
node?	Node	The node whose children were replaced, if it was a subtree.
treeData?	NodeData[]	-

---

tree.loading_data

"tree.loading_data": object;

Dispatched when a request starts.

Name	Type	Description
element	HTMLElement	-
node?	Node	The node whose children are loading, if it is a subtree.

---

tree.loaded_data

"tree.loaded_data": object;

Dispatched when a request finishes. It is dispatched when the request fails too; a tree.load_failed follows it.

Name	Type	Description
element	HTMLElement	-
node?	Node	The node whose children were loaded, if it was a subtree.

---

tree.load_failed

"tree.load_failed": object;

Dispatched when a request returns an error status or fails with a network error, after tree.loaded_data:

element.addEventListener("tree.load_failed", (e) => {
  if (e.detail.response) {
    console.error("loading the tree failed", e.detail.response.status);
  } else {
    console.error("loading the tree failed", e.detail.error);
  }
});

Name	Type	Description
error?	unknown	The error thrown by fetch, if the request failed with a network error.
response?	Response	The response, if the request returned an error status.

Keyboard

tree.activate

"tree.activate": object;

Dispatched when Enter is pressed on the selected node, or on the focused node when no node is selected. Use it for what a click on a link would do, like opening the edit page of the node:

element.addEventListener("tree.activate", (e) => {
  window.location.href = e.detail.node.url;
});

Name	Type
node	Node
originalEvent	KeyboardEvent

Types

The package types the events by their name, so in TypeScript the detail needs no cast:

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

This works on elements, on document and on window, in any file that imports tree-element.

Each event has its own detail, so a listener only sees the properties of the event it listens to:

element.addEventListener("tree.select", (e) => {
  console.log(
    "selected",
    e.detail.node.name,
    "instead of",
    e.detail.deselectedNode,
  );
});

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

The types are also exported, for a listener that is written separately:

import type { MoveInfo, TreeEvent, TreeEventName, TreeEvents } from "tree-element";

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

// TreeEvent<Name> is the CustomEvent, TreeEvents[Name] is its detail.
const onMove = (e: TreeEvent<"tree.move">): void => {
  const moveInfo: MoveInfo = e.detail.moveInfo;
  console.log(moveInfo.movedNode.name);
};

element.addEventListener("tree.move", onMove);

// TreeEventName is the name of any event: "tree.click" | "tree.close" | ...
const log = <Name extends TreeEventName>(
  name: Name,
  detail: TreeEvents[Name],
) => {
  console.log(name, detail);
};

Dispatching events differently

The overrideTriggerEventProvider option replaces the whole mechanism, if you want the tree to report to something other than DOM events. See Options.