Methods

Methods are called on the object returned by the constructor:

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

tree.openNode(tree.getNodeById(1));

Select a node and try them here — the buttons call appendNode, updateNode, removeNode, openNode and closeNode:

Events

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

Finding nodes

getNode()

getNode(element): Node | null;

Returns the node that belongs to a li element the tree rendered.

Parameters

Parameter	Type
element	HTMLElement

Returns

Node | null

---

getNodeByCallback()

getNodeByCallback(callback): Node | null;

Returns the first node for which the callback returns true.

Parameters

Parameter	Type
callback	(node) => boolean

Returns

Node | null

Example

const node = tree.getNodeByCallback((node) => node.children.length > 3);

---

getNodeById()

getNodeById(id): Node | null;

Returns the node with this id.

Parameters

Parameter	Type
id	NodeId

Returns

Node | null

Example

const node = tree.getNodeById(1);

---

getNodeByName()

getNodeByName(name): Node | null;

Returns the first node with this name.

Parameters

Parameter	Type
name	string

Returns

Node | null

---

getNodeByNameMustExist()

getNodeByNameMustExist(name): Node;

Like getNodeByName, but throws when there is no such node. Convenient in tests and when a missing node is a bug.

Parameters

Parameter	Type
name	string

Returns

Node

---

getNodesByProperty()

getNodesByProperty(key, value): Node[];

Returns all nodes with this property value.

Parameters

Parameter	Type
key	string
value	unknown

Returns

Node[]

Example

tree.getNodesByProperty("color", "green");

---

getTree()

getTree(): Node;

Returns the root node. It is not rendered; its children are the top-level nodes. Also available as the tree property.

Returns

Node

Opening and closing

closeNode()

closeNode(node, slide?): Promise<void>;

Closes a folder. Await the promise when you need to know the closing animation has finished.

Parameters

Parameter	Type	Description
node	Node	-
slide?	boolean	Override the slide option for this call.

Returns

Promise<void>

Example

await tree.closeNode(node);
console.log("closed");

---

openNode()

openNode(node, slide?): Promise<void>;

Opens a folder, and the folders above it. A node marked load_on_demand is fetched first, so await the promise when you need to know it is really open.

Parameters

Parameter	Type	Description
node	Node	-
slide?	boolean	Override the slide option for this call.

Returns

Promise<void>

Example

await tree.openNode(node);
console.log("open");

---

toggle()

toggle(node, slide?): Promise<void>;

Closes an open node and opens a closed one. Await the promise when you need to know the node is really open or closed, like with openNode and closeNode.

Parameters

Parameter	Type	Default value	Description
node	Node	undefined	-
slide?	boolean | null	null	Override the slide option for this call.

Returns

Promise<void>

Selection

addToSelection()

addToSelection(node, mustSetFocus?): void;

Adds a node to the selection instead of replacing it.

Parameters

Parameter	Type	Default value	Description
node	Node	undefined	-
mustSetFocus?	boolean	true	Move the focus to the node. Default true.

Returns

void

---

getSelectedNode()

getSelectedNode(): Node | null;

Returns the selected node, or null when nothing is selected.

Returns

Node | null

---

getSelectedNodes()

getSelectedNodes(): Node[];

Returns the selected nodes.

Returns

Node[]

---

isNodeSelected()

isNodeSelected(node): boolean;

Returns whether the node is selected.

Parameters

Parameter	Type
node	Node

Returns

boolean

---

moveDown()

moveDown(): void;

Selects the next visible node, like the down arrow key. With multiSelect it moves the focus instead.

Returns

void

---

moveUp()

moveUp(): void;

Selects the previous visible node, like the up arrow key. With multiSelect it moves the focus instead.

Returns

void

---

removeFromSelection()

removeFromSelection(node): void;

Removes a node from the selection.

Parameters

Parameter	Type
node	Node

Returns

void

---

scrollToNode()

scrollToNode(node): void;

Scrolls the node into view.

Parameters

Parameter	Type
node	Node

Returns

void

---

selectNode()

selectNode(node, options?): void;

Replaces the selection, and opens the parents of the node.

Parameters

Parameter	Type	Description
node	Node | null	null clears the selection.
options?	SelectNodeOptions	mustSetFocus: move focus to the node, default true. mustToggle: deselect the node if it is already selected, default false.

Returns

void

Changing the tree

addNodeAfter()

addNodeAfter(nodeData, existingNode): Node | null;

Adds a sibling after a node.

Parameters

Parameter	Type
nodeData	NodeData
existingNode	Node

Returns

Node | null

The new node, or null when the node has no parent.

---

addNodeBefore()

addNodeBefore(nodeData, existingNode): Node | null;

Adds a sibling before a node.

Parameters

Parameter	Type
nodeData	NodeData
existingNode	Node

Returns

Node | null

The new node, or null when the node has no parent.

---

addParentNode()

addParentNode(nodeData, existingNode): Node | null;

Inserts a new node between a node and its parent, taking the node as its child.

Parameters

Parameter	Type
nodeData	NodeData
existingNode	Node

Returns

Node | null

The new node, or null when the node has no parent.

---

appendNode()

appendNode(nodeData, parentNode): Node;

Adds a node as the last child of a parent.

Parameters

Parameter	Type
nodeData	NodeData
parentNode	Node

Returns

Node

The new node.

Example

tree.appendNode({ name: "child", id: 5 }, tree.getNodeById(1));

---

moveNode()

moveNode(
   node, 
   targetNode, 
   position
): void;

Moves a node inside the tree.

Parameters

Parameter	Type	Description
node	Node	-
targetNode	Node	-
position	Position	"before", "after" or "inside".

Returns

void

Example

tree.moveNode(tree.getNodeById(2), tree.getNodeById(1), "inside");

---

prependNode()

prependNode(nodeData, parentNode): Node;

Adds a node as the first child of a parent.

Parameters

Parameter	Type
nodeData	NodeData
parentNode	Node

Returns

Node

The new node.

---

refresh()

refresh(): void;

Re-renders the whole tree. Needed after changing node data directly instead of through these methods.

Returns

void

---

removeNode()

removeNode(node): void;

Removes a node and its children.

Parameters

Parameter	Type
node	Node

Returns

void

---

updateNode()

updateNode(node, data): void;

Updates the data of a node and re-renders it. A string updates just the name.

Changing the id re-indexes the node. children and parent are ignored — use loadData or moveNode for those.

Parameters

Parameter	Type
node	Node
data	NodeData

Returns

void

Example

tree.updateNode(node, "new name");
tree.updateNode(node, { name: "new name", color: "red" });

Loading data

loadData()

loadData(data, parentNode?): void;

Loads data into the tree.

Parameters

Parameter	Type	Description
data	NodeData[] | null	-
parentNode?	Node	Replace this node's children instead of the whole tree.

Returns

void

---

loadDataFromUrl()

loadDataFromUrl(url?, parentNode?): Promise<void>;

Fetches data and loads it into the tree, or into parentNode.

Parameters

Parameter	Type	Description
url?	string	Defaults to the dataUrl option.
parentNode?	Node	-

Returns

Promise<void>

State

getState()

getState(): SavedState | null;

Returns the current state — open_nodes and selected_node — whether or not saveState is enabled.

Returns

SavedState | null

---

getStateFromStorage()

getStateFromStorage(): SavedState | null;

Returns the state as it is stored.

Returns

SavedState | null

---

setState()

setState(state): void;

Applies a state to the tree, and saves it to storage when saveState is enabled.

Parameters

Parameter	Type
state	SavedState

Returns

void

Other

deinit()

deinit(): void;

Empties the element and removes the tree's document-level keyboard listener. Call it when you remove the tree from the page.

Returns

void

---

getVersion()

getVersion(): string;

Returns the version of tree-element.

Returns

string

---

isDragging()

isDragging(): boolean;

Returns whether the user is dragging a node.

Returns

boolean

---

refreshHitAreas()

refreshHitAreas(): void;

Recomputes the drop targets. Call this if the layout changes during a drag.

Returns

void

---

setOption()

setOption(option, value): void;

Changes an option after construction. Only some options can be changed; the others throw an error. See Options.

Parameters

Parameter	Type
option	| "animationSpeed" | "dataUrl" | "dragAndDrop" | "keyboardSupport" | "multiSelect" | "onCanSelectNode" | "selectable" | "slide" | "startDndDelay" | "tabIndex"
value	unknown

Returns

void

---

toJson()

toJson(): string;

Returns the tree as a json string, including changes made through the api.

Returns

string