tree-element

Appearance

Options ​

All options are passed to the constructor:

js
const tree = new TreeElement({
  autoOpen: 0,
  data,
  dragAndDrop: true,
  htmlElement: document.getElementById("tree1"),
});

htmlElement is required: it is the element the tree is rendered into, and its content is replaced. All other options are optional.

Data ​

autoEscape ​

ts
autoEscape: boolean;

Escape node names. With false, names are inserted as html — only do that for data you control.

Default Value ​

true

data? ​

ts
data?: NodeData[];

The nodes of the tree. See Data for the format.

dataFilter? ​

ts
dataFilter?: DataFilter;

Transforms a response from dataUrl into node data. Use it when the server wraps the nodes in another object.

Type: (data: unknown) => NodeData[]

dataUrl? ​

ts
dataUrl?: DataUrl;

A url to fetch the data from, or a function that returns one. The function is called with the node that is being loaded, and without an argument for the initial load. See Loading on demand.

Type: string | ((node?: Node) => string)

Default Value ​

The element's data-url attribute.

Appearance ​

animationSpeed ​

ts
animationSpeed: AnimationSpeed;

The duration of the slide animation: "fast" is 200ms, "slow" is 600ms, a number is milliseconds.

Default Value ​

"fast", or 0 when the user prefers reduced motion (prefers-reduced-motion: reduce).

ariaLabel? ​

ts
ariaLabel?: string;

The accessible name of the tree, set as aria-label on the root ul. Use ariaLabelledBy instead when the name is visible on the page.

ariaLabelledBy? ​

ts
ariaLabelledBy?: string;

The id of the element that names the tree, set as aria-labelledby on the root ul.

autoOpen ​

ts
autoOpen: number | boolean;

Which levels are open initially: false none, true all, a number that many levels starting at 0 (so 0 opens the top level, 1 the first two levels).

Default Value ​

false

buttonLeft ​

ts
buttonLeft: boolean;

Put the open/close button before the node title. With false it goes after it.

Default Value ​

true

classPrefix ​

ts
classPrefix: string;

The prefix of the css classes the widget puts on the elements it creates: with "my-tree" a title gets my-tree-title instead of tree-element-title. The bundled stylesheet uses the default prefix, so change it only if you bring your own css. See Styling.

Default Value ​

"tree-element"

closedIcon? ​

ts
closedIcon?: IconElement;

The icon of a closed folder. A string is inserted as html; an element is cloned for every node.

Type: HTMLElement | string

Default Value ​

An svg triangle pointing right, or left when rtl is true. It is sized in em and filled with currentColor.

commonClassName? ​

ts
commonClassName?: string;

The class that every element of the widget gets.

Default Value ​

"<classPrefix>-common"

onCreateLi? ​

ts
onCreateLi?: OnCreateLi;

Called after the li of a node is created, so you can add to it. See Styling.

Type: (node: Node, li: HTMLElement, isSelected: boolean) => void

openedIcon? ​

ts
openedIcon?: IconElement;

The icon of an open folder.

Type: HTMLElement | string

Default Value ​

An svg triangle pointing down, sized in em and filled with currentColor.

rtl? ​

ts
rtl?: boolean;

Mirror the tree for right-to-left languages.

Default Value ​

The element's data-rtl attribute, otherwise false.

showEmptyFolder ​

ts
showEmptyFolder: boolean;

Render a node with children: [] as a folder instead of as a leaf.

Default Value ​

false

slide ​

ts
slide: boolean;

Animate opening and closing folders.

Default Value ​

true

treeClassName? ​

ts
treeClassName?: string;

The class of the root ul.

Default Value ​

The value of classPrefix.

Selection ​

keyboardSupport ​

ts
keyboardSupport: boolean;

Handle the keyboard when the focus is on the tree. See Selection.

Default Value ​

true

multiSelect ​

ts
multiSelect: boolean;

Let the user select multiple nodes: a click adds a node to the selection, or removes it when it is selected. The arrow keys move the focus instead of the selection, and Space adds the focused node or removes it. See Selection.

Default Value ​

false

onCanSelectNode? ​

ts
onCanSelectNode?: OnCanSelectNode;

Called before a node is selected. Return false to refuse.

Type: (node: Node) => boolean

selectable ​

ts
selectable: boolean;

Allow the user to select nodes.

Default Value ​

true

tabIndex? ​

ts
tabIndex?: number;

The tabindex of the selected node's title, which is what makes the tree focusable. When no node is selected, the first node gets it. The other nodes get -1.

Default Value ​

0

useContextMenu ​

ts
useContextMenu: boolean;

Handle right clicks on a node: the browser menu is suppressed and tree.contextmenu is dispatched instead.

Default Value ​

true

Drag and drop ​

dragAndDrop ​

ts
dragAndDrop: boolean;

Let the user move nodes by dragging them.

Default Value ​

false

onCanMove? ​

ts
onCanMove?: OnCanMove;

Called before a drag starts. Return false to keep the node in place.

Type: (node: Node) => boolean

onCanMoveTo? ​

ts
onCanMoveTo?: OnCanMoveTo;

Called for a possible drop. position is "before", "after" or "inside". Return false to refuse the drop.

Type: (movedNode: Node, targetNode: Node, position: string) => boolean

onDragMove? ​

ts
onDragMove?: DragMethod;

Called while a node is being dragged.

Type: (node: Node, event: Event | Touch) => void

onDragStop? ​

ts
onDragStop?: DragMethod;

Called when a drag ends.

Type: (node: Node, event: Event | Touch) => void

onIsMoveHandle? ​

ts
onIsMoveHandle?: OnIsMoveHandle;

Decides whether an element inside a node starts a drag. Without it, the whole node is a handle.

Type: (element: HTMLElement) => boolean

openFolderDelay ​

ts
openFolderDelay: number | false;

How long, in milliseconds, a closed folder has to be hovered during a drag before it opens. false never opens folders while dragging.

Default Value ​

500

startDndDelay? ​

ts
startDndDelay?: number;

How long, in milliseconds, the mouse has to be held down on a node before a drag starts.

Default Value ​

300

State ​

onGetStateFromStorage? ​

ts
onGetStateFromStorage?: OnGetStateFromStorage;

Read the saved state, as a json string, from somewhere other than localStorage.

Type: () => string

onSetStateFromStorage? ​

ts
onSetStateFromStorage?: OnSetStateFromStorage;

Write the state, as a json string, to somewhere other than localStorage.

Type: (state: string) => void

saveState ​

ts
saveState: string | boolean;

Remember the open and selected nodes in localStorage. A string is used as the storage key; true uses tree. See Saving state.

Default Value ​

false

Advanced ​

nodeClass ​

ts
nodeClass: typeof Node;

The class used to create nodes. Subclass Node to add your own methods. The Node class is not exposed on the global TreeElement, so this option needs the lib build.

Example ​

js
import TreeElement from "tree-element/lib/index.js";
import { Node } from "tree-element/lib/node.js";

class MyNode extends Node {
  fullName() {
    return this.getParent()
      ? `${this.getParent().name}/${this.name}`
      : this.name;
  }
}

new TreeElement({ data, htmlElement, nodeClass: MyNode });

Default Value ​

Node

overrideTriggerEventProvider ​

  • Type: (element: HTMLElement, eventName: TreeEventName, values?: TreeEvents[TreeEventName]) => boolean
  • Default: dispatches a cancelable, bubbling CustomEvent

Replaces how events are dispatched. It must return whether the event was not cancelled. This exists for tests and for integrating with another event system.

Changing an option later ​

setOption updates an option after construction:

js
tree.setOption("selectable", false);

Only some options can be changed this way. The tree reads the others once, in the constructor, and setOption throws an error for them. To change one of those, create the tree again.

These options take effect when you change them:

  • animationSpeed
  • dataUrl
  • dragAndDrop
  • keyboardSupport
  • multiSelect
  • onCanSelectNode
  • selectable
  • slide
  • startDndDelay
  • tabIndex

These can only be set in the constructor, setOption throws an error for them:

  • ariaLabel, ariaLabelledBy
  • autoEscape
  • autoOpen
  • buttonLeft
  • classPrefix, commonClassName, treeClassName
  • closedIcon, openedIcon
  • data — use loadData to replace the nodes
  • dataFilter
  • nodeClass
  • onCanMove, onCanMoveTo, onDragMove, onDragStop, onIsMoveHandle
  • onCreateLi
  • onGetStateFromStorage, onSetStateFromStorage
  • openFolderDelay
  • rtl
  • saveState
  • showEmptyFolder
  • useContextMenu

Released under the Apache 2.0 License.