0
# jsTree
1

2
jsTree is a comprehensive jQuery plugin that provides interactive tree components for web applications. It offers a feature-rich tree interface with support for drag & drop, keyboard navigation, inline editing (create/edit/delete), tri-state checkboxes, fuzzy searching, and customizable node types. The library is designed for maximum flexibility with support for HTML & JSON data sources, AJAX & async callback loading, and works with both box-model types (content-box or border-box).
3

4
## Package Information
5

6
- **Package Name**: jstree
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jstree`
10

11
## Core Imports
12

13
```javascript
14
// ES6 Module
15
import $ from "jquery";
16
import "jstree";
17

18
// Or if jQuery is already available globally
19
import "jstree";
20
```
21

22
For CommonJS:
23

24
```javascript
25
const $ = require("jquery");
26
require("jstree");
27
```
28

29
For browser usage via CDN:
30

31
```html
32
<script src="https://code.jquery.com/jquery-3.5.0.min.js"></script>
33
<script src="path/to/jstree.min.js"></script>
34
```
35

36
## Basic Usage
37

38
```javascript
39
// Initialize a tree
40
$("#tree").jstree({
41
  "core": {
42
    "data": [
43
      { "text": "Root node", "children": [
44
        { "text": "Child node 1" },
45
        { "text": "Child node 2" }
46
      ]}
47
    ]
48
  }
49
});
50

51
// Get the tree instance
52
const tree = $("#tree").jstree(true);
53

54
// Select a node
55
tree.select_node("node_id");
56

57
// Create a new node
58
tree.create_node("#", { "text": "New node" });
59

60
// Listen to events
61
$("#tree").on("select_node.jstree", function (e, data) {
62
  console.log("Selected node:", data.node.text);
63
});
64
```
65

66
## Architecture
67

68
jsTree is built around several key components:
69

70
- **Core API**: Essential tree functionality including node management, selection, and state
71
- **Plugin System**: Modular extensions for specialized functionality (checkboxes, drag & drop, search, etc.)
72
- **Event System**: jQuery-based event system for handling tree interactions
73
- **Data Sources**: Support for HTML, JSON, AJAX, and function-based data loading
74
- **Theme System**: Customizable appearance with built-in themes and mobile support
75
- **Configuration**: Extensive options for customizing behavior and appearance
76

77
## Capabilities
78

79
### Core Tree Management
80

81
Essential tree functionality including initialization, node manipulation, selection, and basic operations.
82

83
```javascript { .api }
84
// Main plugin function
85
$(selector).jstree(options?: object): jQuery;
86
$(selector).jstree(method: string, ...args: any[]): any;
87
$(selector).jstree(true): jsTree;
88

89
// Static methods
90
$.jstree.create(el: Element|jQuery|string, options?: object): jsTree;
91
$.jstree.destroy(): void;
92
$.jstree.reference(needle: Element|jQuery|string): jsTree;
93

94
// Static properties
95
$.jstree.version: string;
96
$.jstree.defaults: object;
97
$.jstree.plugins: object;
98
$.jstree.path: string;
99
$.jstree.idregex: RegExp;
100
$.jstree.root: string;
101
```
102

103
[Core Tree Management](./core.md)
104

105
### Checkbox Plugin
106

107
Tri-state checkbox functionality with support for cascading selection, parent-child relationships, and individual checkbox control.
108

109
```javascript { .api }
110
// Checkbox configuration
111
interface CheckboxConfig {
112
  visible?: boolean;
113
  three_state?: boolean;
114
  whole_node?: boolean;
115
  keep_selected_style?: boolean;
116
  cascade?: string;
117
  tie_selection?: boolean;
118
}
119

120
// Key checkbox methods
121
tree.check_node(obj: string|object): boolean;
122
tree.uncheck_node(obj: string|object): boolean;
123
tree.get_checked(full?: boolean): Array<string|object>;
124
```
125

126
[Checkbox Functionality](./checkbox.md)
127

128
### Drag & Drop Plugin  
129

130
Advanced drag and drop support with customizable constraints, foreign element support, and visual feedback during operations.
131

132
```javascript { .api }
133
// DnD configuration  
134
interface DnDConfig {
135
  copy?: boolean;
136
  open_timeout?: number;
137
  move_timeout?: number;
138
  is_draggable?: boolean|function;
139
  check_while_dragging?: boolean;
140
  drag_selection?: boolean;
141
  touch?: boolean|string;
142
  large_drop_target?: boolean;
143
  large_drag_target?: boolean;
144
  use_html5?: boolean;
145
}
146
```
147

148
[Drag & Drop Operations](./dnd.md)
149

150
### Context Menu Plugin
151

152
Customizable right-click context menus with support for custom items, submenus, and conditional visibility.
153

154
```javascript { .api }
155
// Context menu configuration
156
interface ContextMenuConfig {
157
  select_node?: boolean;
158
  show_at_node?: boolean;
159
  items?: object|function;
160
}
161

162
// Show context menu
163
tree.show_contextmenu(obj: string|object, x?: number, y?: number, e?: Event): void;
164
```
165

166
[Context Menu System](./contextmenu.md)
167

168
### Search Plugin
169

170
Fuzzy search functionality with highlighting, show-only-matches mode, and customizable search patterns.
171

172
```javascript { .api }
173
// Search configuration
174
interface SearchConfig {
175
  ajax?: object|function;
176
  fuzzy?: boolean;
177
  case_sensitive?: boolean;
178
  show_only_matches?: boolean;
179
  show_only_matches_children?: boolean;
180
  close_opened_onclear?: boolean;
181
  search_leaves_only?: boolean;
182
  search_callback?: function;
183
}
184

185
// Search methods  
186
tree.search(str: string, skip_async?: boolean, show_only_matches?: boolean, inside?: string, append?: boolean): void;
187
tree.clear_search(): void;
188
```
189

190
[Search and Filter](./search.md)
191

192
### Additional Plugins
193

194
State management, node types, sorting, and other specialized functionality.
195

196
```javascript { .api }
197
// State plugin
198
tree.save_state(): void;
199
tree.restore_state(): void;
200
tree.get_state(): object;
201
tree.set_state(state: object, callback?: function): void;
202

203
// Types plugin  
204
tree.get_type(obj: string|object): string;
205
tree.set_type(obj: string|object, type: string): boolean;
206

207
// Sort plugin
208
tree.sort(obj?: string|object, deep?: boolean): void;
209
```
210

211
[Additional Plugins](./plugins.md)
212

213
## Configuration System
214

215
### Core Configuration
216

217
```javascript { .api }
218
interface CoreConfig {
219
  data?: any;
220
  strings?: object;
221
  check_callback?: boolean|function;
222
  error?: function;
223
  animation?: number|boolean;
224
  multiple?: boolean;
225
  themes?: ThemesConfig;
226
  expand_selected_onload?: boolean;
227
  worker?: boolean;
228
  force_text?: boolean;
229
  dblclick_toggle?: boolean;
230
  loaded_state?: boolean;
231
  restore_focus?: boolean;
232
  compute_elements_positions?: boolean;
233
  keyboard?: object;
234
}
235

236
interface ThemesConfig {
237
  name?: string|boolean;
238
  url?: string|boolean;
239
  dir?: string;
240
  dots?: boolean;
241
  icons?: boolean;
242
  ellipsis?: boolean;
243
  stripes?: boolean;
244
  variant?: string|boolean;
245
  responsive?: boolean;
246
}
247
```
248

249
[Configuration and Options](./configuration.md)
250

251
## Event System
252

253
### Core Events
254

255
```javascript { .api }
256
// Tree lifecycle events
257
"init.jstree": TreeEvent;
258
"loading.jstree": TreeEvent;
259
"loaded.jstree": TreeEvent;
260
"ready.jstree": TreeEvent;
261
"redraw.jstree": TreeEvent;
262
"refresh.jstree": TreeEvent;
263

264
// Node events
265
"changed.jstree": SelectionEvent;
266
"select_node.jstree": NodeEvent;
267
"deselect_node.jstree": NodeEvent; 
268
"open_node.jstree": NodeEvent;
269
"close_node.jstree": NodeEvent;
270
"create_node.jstree": NodeEvent;
271
"rename_node.jstree": RenameEvent;
272
"delete_node.jstree": NodeEvent;
273
"move_node.jstree": MoveEvent;
274
"copy_node.jstree": MoveEvent;
275

276
interface NodeEvent {
277
  node: TreeNode;
278
  instance: jsTree;
279
}
280

281
interface RenameEvent extends NodeEvent {
282
  text: string;
283
  old: string;
284
}
285

286
interface MoveEvent extends NodeEvent {
287
  parent: string;
288
  position: number;
289
  old_parent: string;
290
  old_position: number;
291
  is_multi: boolean;
292
  old_instance: jsTree;
293
  new_instance: jsTree;
294
}
295

296
interface SelectionEvent {
297
  selected: Array<string>;
298
  instance: jsTree;
299
  action: string;
300
  node: TreeNode;
301
}
302
```
303

304
[Events and Callbacks](./events.md)
305

306
## Types
307

308
```javascript { .api }
309
// Main jsTree instance type
310
interface jsTree {
311
  // Core properties
312
  element: jQuery;
313
  settings: object;
314
  _id: number;
315
  _cnt: number;
316
  _data: object;
317
  _wrk: Worker|null;
318
  
319
  // All instance methods documented in sub-docs
320
  // (This interface would be extremely large, so methods are documented
321
  // in their respective capability sections)
322
}
323

324
// Tree node data structure  
325
interface TreeNode {
326
  id: string;
327
  text: string;
328
  icon?: string|boolean;
329
  state?: {
330
    loaded?: boolean;
331
    opened?: boolean;
332
    selected?: boolean;
333
    disabled?: boolean;  
334
    hidden?: boolean;
335
    checked?: boolean;
336
    undetermined?: boolean;
337
  };
338
  children?: Array<TreeNode>|boolean;
339
  li_attr?: object;
340
  a_attr?: object;
341
  parent?: string;
342
  parents?: Array<string>;
343
  data?: any;
344
  type?: string;
345
}
346

347
// Global jsTree namespace
348
interface jstreeStatic {
349
  version: string;
350
  defaults: object;
351
  plugins: object;
352
  path: string;
353
  idregex: RegExp;
354
  root: string;
355
}
356

357
// jQuery extensions
358
interface jQuery {
359
  jstree(options?: object): jQuery;
360
  jstree(method: string, ...args: any[]): any;
361
  jstree(getinstance: true): jsTree;
362
}
363

364
interface JQueryStatic {
365
  jstree: jstreeStatic;
366
}
367
```