sl-vue-tree-next

Vue3 supported version of sl-vue-tree. A customizable draggable tree component for Vue.js.

demo

install

npm i sl-vue-tree-next

Quick start

1
2<template>
3    <h2>Vue 3 Tree</h2>
4    <sl-vue-tree-next v-model="nodes" />
5
6</template>
7
8<script setup lang="ts">
9import { SlVueTreeNext } from 'sl-vue-tree-next'
10
11const nodes = [
12    { title: 'Item1', isLeaf: true },
13    { title: 'Item2', isLeaf: true, data: { visible: false } },
14    { title: 'Folder1' },
15    {
16        title: 'Folder2',
17        isExpanded: true,
18        children: [
19            { title: 'Item3', isLeaf: true },
20            { title: 'Item4', isLeaf: true },
21            {
22                title: 'Folder3',
23                children: [{ title: 'Item5', isLeaf: true }],
24            },
25        ],
26    },
27    { title: 'Folder5', isExpanded: false },
28    { title: 'Item6', isLeaf: true },
29    { title: 'Item7', isLeaf: true, data: { visible: false } },
30    {
31        title: 'Folder6',
32        children: [
33            {
34                title: 'Folder7',
35                children: [
36                    { title: 'Item8', isLeaf: true },
37                    { title: 'Item9', isLeaf: true },
38                ],
39            },
40        ],
41    },
42]
43</script>
44
45<style>
46  @import 'sl-vue-tree-next/sl-vue-tree-next-minimal.css';
47</style>

You can also use dark version.

1<style>
2  @import 'sl-vue-tree-next/sl-vue-tree-next-dark.css';
3</style>

The value property is an array of NodeModel nodes:

1interface NodeModel<TDataType> {
2    title: string;
3    isLeaf?: boolean;
4    children?: NodeModel<TDataType>[];
5    isExpanded?: boolean;
6    isSelected?: boolean;
7    isDraggable?: boolean;
8    isSelectable?: boolean;
9    data?: TDataType; // any serializable user data
10}

For convenience the component's events return Node objects. Those actually are NodeModel with some computed props:

1interface TreeNode<TDataType> extends NodeModel<TDataType> {
2    isFirstChild: boolean;
3    isLastChild: boolean;
4    isVisible: boolean;	// node is visible if all of its parents are expanded
5    level: number; // nesting level
6    ind: number; // index in the array of siblings
7    path: number[]; // path to node as array of indexes, for example [2, 0, 1] in the example above is path to `Item4`
8    pathStr: string; // serialized path to node
9    children: TreeNode<TDataType>[];
10}

You can get the list of Node from the computed slVueTree.currentNodes property

Props

prop	type	default	description
value	NodeModel[]	[]	An array of nodes to show. Each node is represented by NodeModel interface
allowMultiselect	Boolean	true	Disable or enable the multiselect feature
allowToggleBranch	Boolean	true	Disable or enable the expand/collapse button
edgeSize	Number	3	Offset in pixels from top and bottom for folder-node element. While dragging cursor is in that offset, the dragging node will be placed before or after the folder-node instead of being placed inside the folder.
scrollAreaHeight	Number	70	Offset in pixels from top and bottom for the component element. While dragging cursor is in that area, the scrolling starts.
maxScrollSpeed	Number	20	The scroll speed is relative to the cursor position. Defines the max scroll speed.
multiselectKey	String/String[]	['ctrlKey', 'metaKey']	The keys for multiselect mode. Allowed values are ['ctrlKey', 'metaKey', 'altKey']

Computed props

prop	type	description
currentNodes	TreeNode[]	List of nodes with some computed props. See Node interface.
cursorPosition	ICursorPosition	Represents the current cursor position that describes the action that will be applied to the dragged node on mouseup event. See ICursorPosition interface
selectionSize	Number	The count of selected nodes
dragSize	Number	The count of selected and draggable nodes
isDragging	Boolean	True if nodes are dragging

interface ICursorPosition<TDataType> {
  node: Node<TDataType>;
  placement: 'before' | 'inside' | 'after';
}

Events

event	callback arguments	description
input	nodes: NodeModel[]	triggers for any changes to value property
select	selectedNodes: TreeNode[], event: MouseEvent	triggers when a node has been selected/deselected
toggle	toggledNode: TreeNode, event: MouseEvent	triggers when a node has been collapsed/expanded
drop	draggingNodes: TreeNode[], position: ICursorPosition, event: MouseEvent	triggers when dragging nodes have been dropped
nodeclick	node: TreeNode, event: MouseEvent	handle click event on node
nodedblclick	node: TreeNode, event: MouseEvent	handle dblclick event on node
nodecontextmenu	node: TreeNode, event: MouseEvent	handle contextmenu event on node
externaldrop	cursorPosition: ICursorPosition, event: MouseEvent	handle drop event for external items demo

Methods

method	description
getNode(path: number[]): TreeNode	Find the node by using its path
traverse(cb: (node: TreeNode, nodeModel: NodeModel, siblings: NodeModel[]) => boolean)	Helpful method to traverse all nodes. The traversing will be stopped if callback returns false.
updateNode({ path: number[], patch: Partial })	Update the node by using its path
select(path: number[], addToSelection = false)	Select the node by using its path
getNodeEl(): HTMLElement	Get the node HTMLElement by using its path
getSelected(): TreeNode[]	Get selected nodes
insert(position: ICursorPosition, nodeModel: NodeModel)	Insert nodes by the current cursor position.
remove(paths: number[][])	Remove nodes by paths. For example .remove([[0,1], [0,2]])
getFirstNode(): TreeNode	Get the first node in the tree
getLastNode(): TreeNode	Get the last node in the tree
getNextNode(path: number[], filter?: (node: TreeNode) => boolean): TreeNode;	Get the next node. You can skip the next nodes by using filter
getPrevNode(path: number[], filter?: (node: TreeNode) => boolean): TreeNode;	Get the previous node. You can skip the previous nodes by using filter

Slots

slot	context	description
title	TreeNode	Slot for item title
toggle	TreeNode	Slot for expand/collapse button
sidebar	TreeNode	Sidebar content
draginfo	SlVueTree	Slot that follows the mouse cursor while dragging. By default shows the dragging nodes count.
empty-node	TreeNode	Slot for (optional) message when folder is open, but empty

Examples

Add a folder or item icon via title slot

1<sl-vue-tree-next v-model="nodes">
2    <template #title="{ node }">
3
4      <span class="item-icon">
5        <i class="fa fa-file" v-if="node.isLeaf"></i>
6        <i class="fa fa-folder" v-if="!node.isLeaf"></i>
7      </span>
8
9      {{ node.title }}
10
11    </template>
12</sl-vue-tree-next>
13

Select all nodes

1slVueTree.traverse((node, nodeModel, path) => {
2    Vue.set(nodeModel, 'isSelected', true);
3})

Handle keydown and keyup events via getNextNode and getPrevNode methods

Contributing

see CONTRIBUTING.md

Changelog

v0.0.14

• add support for touch devices
• fix multi-select prop typo

v0.0.13

• fixes duplicate node issue when moving multiple nodes
• uses deep merge to update node when using updateNode function
• fixes dark mode toggle button in demo

v0.0.12

• fixes wrong defineComponent not defined issue

v0.0.11

• fixes keyboard control issues
• exposes maxScrollSpeed and scrollAreaHeight as props
• exposes selectionSize to ref

v0.0.10

• fixes lower level icons not appearing bug
• fixes node update bug

v0.0.9

• update demo
• update readme

v0.0.8

• update demos

v0.0.7

• add support for generics

v0.0.6

• update readme.md

v0.0.5

• fix computed warnings in console
• fixed duplicate nodes bug

v0.0.4

• made minimal and dark css available

v0.0.3

• removed vue from dependency and added to peer dependency

v0.0.2

• added type safety to props and methods

v0.0.1

• migrated to vue 3