0
# Configuration and Options
1

2
Comprehensive guide to jsTree configuration options, themes, and global settings. This document covers all core configuration options and how to customize jsTree behavior to meet specific requirements.
3

4
## Capabilities
5

6
### Core Configuration
7

8
Primary configuration object for jsTree initialization.
9

10
```javascript { .api }
11
/**
12
 * Core configuration options
13
 */
14
interface CoreConfig {
15
  /** Data source configuration */
16
  data?: DataConfig;
17
  /** Localized strings */
18
  strings?: StringsConfig;
19
  /** Operation validation callback */
20
  check_callback?: boolean|CheckCallbackFunction;
21
  /** Error handling callback */
22
  error?: ErrorCallback;
23
  /** Animation settings */
24
  animation?: number|boolean;
25
  /** Allow multiple node selection */
26
  multiple?: boolean;
27
  /** Theme configuration */
28
  themes?: ThemesConfig;
29
  /** Auto-expand to selected nodes on load */
30
  expand_selected_onload?: boolean;
31
  /** Use web workers for performance */
32
  worker?: boolean;
33
  /** Force text-only mode (no HTML) */
34
  force_text?: boolean;
35
  /** Double-click to toggle node state */
36
  dblclick_toggle?: boolean;
37
  /** Preserve loaded state on refresh */
38
  loaded_state?: boolean;
39
  /** Restore focus after operations */
40
  restore_focus?: boolean;
41
  /** Compute element positions for performance */
42
  compute_elements_positions?: boolean;
43
  /** Keyboard navigation settings */
44
  keyboard?: KeyboardConfig;
45
}
46

47
type CheckCallbackFunction = (
48
  operation: string,
49
  node: object,
50
  parent: object,
51
  position: string|number,
52
  more?: object
53
) => boolean;
54

55
type ErrorCallback = (error: object) => void;
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
// Basic configuration
62
$("#tree").jstree({
63
  "core": {
64
    "data": ["Item 1", "Item 2", "Item 3"],
65
    "multiple": true,
66
    "animation": 200,
67
    "check_callback": true
68
  }
69
});
70

71
// Advanced configuration
72
$("#tree").jstree({
73
  "core": {
74
    "data": {
75
      "url": "/api/tree-data",
76
      "dataType": "json"
77
    },
78
    "check_callback": function(operation, node, parent, position, more) {
79
      // Custom validation logic
80
      if (operation === "delete_node") {
81
        return confirm("Are you sure you want to delete this node?");
82
      }
83
      return true;
84
    },
85
    "error": function(error) {
86
      console.error("jsTree error:", error);
87
      showErrorMessage("Tree operation failed");
88
    },
89
    "themes": {
90
      "name": "default",
91
      "dots": true,
92
      "icons": true,
93
      "stripes": true
94
    }
95
  }
96
});
97
```
98

99
### Data Configuration
100

101
Configuration for various data sources and formats.
102

103
```javascript { .api }
104
/**
105
 * Data source configuration
106
 */
107
interface DataConfig {
108
  /** Static data array */
109
  data?: Array<NodeData>|Array<string>;
110
  /** AJAX configuration */
111
  url?: string;
112
  /** AJAX data parameters */
113
  ajax?: AjaxConfig;
114
  /** Custom data function */
115
  dataType?: string;
116
  /** Data processing function */
117
  success?: function;
118
  /** Error handling for data loading */
119
  error?: function;
120
}
121

122
interface NodeData {
123
  /** Node display text */
124
  text: string;
125
  /** Node ID (auto-generated if not provided) */
126
  id?: string;
127
  /** Parent node ID */
128
  parent?: string;
129
  /** Child nodes */
130
  children?: Array<NodeData>|boolean;
131
  /** Node state */
132
  state?: NodeState;
133
  /** Additional data */
134
  data?: object;
135
  /** HTML attributes for LI element */
136
  li_attr?: object;
137
  /** HTML attributes for A element */
138
  a_attr?: object;
139
  /** Node icon */
140
  icon?: string|boolean;
141
  /** Node type (for types plugin) */
142
  type?: string;
143
}
144

145
interface NodeState {
146
  /** Node is opened */
147
  opened?: boolean;
148
  /** Node is selected */
149
  selected?: boolean;
150
  /** Node is disabled */
151
  disabled?: boolean;
152
  /** Node has children to load */
153
  loaded?: boolean;
154
}
155

156
interface AjaxConfig {
157
  /** Request URL */
158
  url?: string|function;
159
  /** HTTP method */
160
  method?: string;
161
  /** Request data */
162
  data?: object|function;
163
  /** Data type */
164
  dataType?: string;
165
  /** Content type */
166
  contentType?: string;
167
  /** Success callback */
168
  success?: function;
169
  /** Error callback */
170
  error?: function;
171
}
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
// Static array data
178
$("#tree").jstree({
179
  "core": {
180
    "data": [
181
      "Simple root node",
182
      {
183
        "text": "Root node 2",
184
        "children": [
185
          {"text": "Child 1"},
186
          {"text": "Child 2"}
187
        ]
188
      }
189
    ]
190
  }
191
});
192

193
// AJAX data loading
194
$("#tree").jstree({
195
  "core": {
196
    "data": {
197
      "url": "/api/tree-nodes",
198
      "dataType": "json",
199
      "data": function(node) {
200
        return {
201
          "id": node.id,
202
          "parent": node.parent
203
        };
204
      },
205
      "success": function(data) {
206
        return data.nodes;
207
      },
208
      "error": function(xhr, status, error) {
209
        console.error("Failed to load tree data:", error);
210
      }
211
    }
212
  }
213
});
214

215
// Function-based data
216
$("#tree").jstree({
217
  "core": {
218
    "data": function(node, callback) {
219
      if (node.id === "#") {
220
        // Root nodes
221
        callback([
222
          {"id": "1", "text": "Root 1", "children": true},
223
          {"id": "2", "text": "Root 2", "children": false}
224
        ]);
225
      } else {
226
        // Child nodes
227
        loadChildNodes(node.id, callback);
228
      }
229
    }
230
  }
231
});
232

233
// Complex node data
234
$("#tree").jstree({
235
  "core": {
236
    "data": [
237
      {
238
        "text": "Important Document",
239
        "id": "doc_1",
240
        "state": {"opened": true, "selected": true},
241
        "data": {"file_type": "pdf", "size": "2.5MB"},
242
        "li_attr": {"class": "important-node"},
243
        "a_attr": {"href": "/documents/1", "target": "_blank"},
244
        "icon": "fa fa-file-pdf-o",
245
        "type": "document",
246
        "children": [
247
          {"text": "Page 1", "type": "page"},
248
          {"text": "Page 2", "type": "page"}
249
        ]
250
      }
251
    ]
252
  }
253
});
254
```
255

256
### Theme Configuration
257

258
Appearance and styling options for the tree.
259

260
```javascript { .api }
261
/**
262
 * Theme configuration options
263
 */
264
interface ThemesConfig {
265
  /** Theme name or false to disable */
266
  name?: string|boolean;
267
  /** Theme CSS file URL */
268
  url?: string|boolean;
269
  /** Theme directory path */
270
  dir?: string;
271
  /** Show connecting dots/lines */
272
  dots?: boolean;
273
  /** Show node icons */
274
  icons?: boolean;
275
  /** Show text ellipsis for long names */
276
  ellipsis?: boolean;
277
  /** Show alternating row stripes */
278
  stripes?: boolean;
279
  /** Theme variant (e.g., "large", "small") */
280
  variant?: string|boolean;
281
  /** Enable responsive design */
282
  responsive?: boolean;
283
}
284
```
285

286
**Usage Examples:**
287

288
```javascript
289
// Custom theme configuration
290
$("#tree").jstree({
291
  "core": {
292
    "themes": {
293
      "name": "default",
294
      "url": "/css/custom-jstree-theme.css",
295
      "dots": true,
296
      "icons": true,
297
      "stripes": true,
298
      "variant": "large",
299
      "responsive": true
300
    }
301
  }
302
});
303

304
// Programmatic theme changes
305
const tree = $("#tree").jstree(true);
306
tree.set_theme("proton");
307
tree.set_theme_variant("large");
308
tree.show_dots();
309
tree.show_stripes();
310
```
311

312
### Keyboard Configuration
313

314
Keyboard navigation and shortcut settings.
315

316
```javascript { .api }
317
/**
318
 * Keyboard configuration options
319
 */
320
interface KeyboardConfig {
321
  /** Enable keyboard navigation */
322
  keyboard?: boolean;
323
  /** Custom key bindings */
324
  bindings?: {[key: string]: KeyBinding};
325
}
326

327
interface KeyBinding {
328
  /** Key combination (e.g., "ctrl+c", "del") */
329
  key: string;
330
  /** Callback function */
331
  callback: function;
332
  /** Action description */
333
  label?: string;
334
}
335
```
336

337
**Usage Examples:**
338

339
```javascript
340
// Custom keyboard shortcuts
341
$("#tree").jstree({
342
  "core": {
343
    "keyboard": {
344
      "bindings": {
345
        "ctrl+c": function(e) {
346
          const selected = this.get_selected();
347
          if (selected.length) {
348
            this.copy(selected);
349
          }
350
          e.preventDefault();
351
        },
352
        "ctrl+v": function(e) {
353
          const selected = this.get_selected();
354
          if (selected.length && this.can_paste()) {
355
            this.paste(selected[0]);
356
          }
357
          e.preventDefault();
358
        },
359
        "del": function(e) {
360
          const selected = this.get_selected();
361
          if (selected.length) {
362
            this.delete_node(selected);
363
          }
364
          e.preventDefault();
365
        },
366
        "f2": function(e) {
367
          const selected = this.get_selected();
368
          if (selected.length === 1) {
369
            this.edit(selected[0]);
370
          }
371
          e.preventDefault();
372
        }
373
      }
374
    }
375
  }
376
});
377
```
378

379
### Strings Configuration
380

381
Localization and customizable text strings.
382

383
```javascript { .api }
384
/**
385
 * Localized strings configuration
386
 */
387
interface StringsConfig {
388
  /** Loading text */
389
  "Loading ..."?: string;
390
  /** New node default text */
391
  "New node"?: string;
392
  /** Multiple selection text format */
393
  "Multiple selection"?: string;
394
  /** Custom strings */
395
  [key: string]: string;
396
}
397
```
398

399
**Usage Examples:**
400

401
```javascript
402
// Localized strings
403
$("#tree").jstree({
404
  "core": {
405
    "strings": {
406
      "Loading ...": "Cargando...",
407
      "New node": "Nuevo nodo",
408
      "Multiple selection": "Selección múltiple",
409
      "Nothing selected": "Nada seleccionado"
410
    }
411
  }
412
});
413

414
// Get localized string
415
const tree = $("#tree").jstree(true);
416
const loadingText = tree.get_string("Loading ...");
417
```
418

419
### Global Configuration
420

421
Default settings that apply to all jsTree instances.
422

423
```javascript { .api }
424
/**
425
 * Global default configuration
426
 */
427
interface GlobalDefaults {
428
  /** Core defaults */
429
  core: CoreConfig;
430
  /** Plugin defaults */
431
  [plugin: string]: any;
432
}
433

434
// Access global defaults
435
$.jstree.defaults.core.animation = 150;
436
$.jstree.defaults.core.themes.stripes = true;
437

438
// Plugin defaults
439
$.jstree.defaults.checkbox = {
440
  "visible": true,
441
  "three_state": true
442
};
443
```
444

445
**Usage Examples:**
446

447
```javascript
448
// Set global defaults
449
$.jstree.defaults.core.animation = 300;
450
$.jstree.defaults.core.multiple = true;
451
$.jstree.defaults.core.themes.stripes = true;
452

453
// All subsequent trees will use these defaults
454
$("#tree1").jstree(); // Uses global defaults
455
$("#tree2").jstree(); // Also uses global defaults
456

457
// Override defaults for specific instance
458
$("#tree3").jstree({
459
  "core": {
460
    "animation": 0, // Override global default
461
    "multiple": false
462
  }
463
});
464
```
465

466
### Advanced Configuration Patterns
467

468
Complex configuration scenarios and patterns.
469

470
```javascript { .api }
471
/**
472
 * Configuration factories and builders
473
 */
474
interface ConfigurationFactory {
475
  /** Build configuration based on context */
476
  buildConfig: (context: object) => object;
477
  /** Merge configurations */
478
  mergeConfigs: (...configs: object[]) => object;
479
  /** Validate configuration */
480
  validateConfig: (config: object) => boolean;
481
}
482
```
483

484
**Usage Examples:**
485

486
```javascript
487
// Configuration factory pattern
488
function createTreeConfig(options) {
489
  const baseConfig = {
490
    "core": {
491
      "animation": 200,
492
      "check_callback": true,
493
      "themes": {"stripes": true}
494
    },
495
    "plugins": ["search", "state"]
496
  };
497
  
498
  if (options.editable) {
499
    baseConfig.plugins.push("contextmenu");
500
    baseConfig.contextmenu = {
501
      "items": editableContextMenu
502
    };
503
  }
504
  
505
  if (options.checkboxes) {
506
    baseConfig.plugins.push("checkbox");
507
    baseConfig.checkbox = {
508
      "three_state": true
509
    };
510
  }
511
  
512
  if (options.dragDrop) {
513
    baseConfig.plugins.push("dnd");
514
    baseConfig.dnd = {
515
      "check_while_dragging": true
516
    };
517
  }
518
  
519
  return $.extend(true, baseConfig, options.customConfig || {});
520
}
521

522
// Usage
523
$("#tree1").jstree(createTreeConfig({
524
  editable: true,
525
  checkboxes: true,
526
  customConfig: {
527
    "core": {"data": treeData1}
528
  }
529
}));
530

531
// Environment-specific configuration
532
const isDevelopment = process.env.NODE_ENV === "development";
533
const config = {
534
  "core": {
535
    "animation": isDevelopment ? 0 : 200, // No animation in dev
536
    "error": isDevelopment ? console.error : logError,
537
    "check_callback": isDevelopment || hasAdminRole()
538
  }
539
};
540

541
// Responsive configuration
542
function getResponsiveConfig() {
543
  const isMobile = window.innerWidth < 768;
544
  return {
545
    "core": {
546
      "themes": {
547
        "variant": isMobile ? "large" : false,
548
        "responsive": true
549
      }
550
    },
551
    "dnd": {
552
      "large_drop_target": isMobile,
553
      "touch": isMobile
554
    }
555
  };
556
}
557

558
$("#tree").jstree(
559
  $.extend(true, baseConfig, getResponsiveConfig())
560
);
561
```
562

563
### Configuration Validation
564

565
Methods for validating and debugging configuration.
566

567
```javascript { .api }
568
/**
569
 * Configuration validation utilities
570
 */
571
interface ConfigValidation {
572
  /** Validate configuration object */
573
  validate: (config: object) => ValidationResult;
574
  /** Get configuration warnings */
575
  getWarnings: (config: object) => Array<string>;
576
  /** Check plugin compatibility */
577
  checkPluginCompatibility: (plugins: Array<string>) => boolean;
578
}
579

580
interface ValidationResult {
581
  valid: boolean;
582
  errors: Array<string>;
583
  warnings: Array<string>;
584
}
585
```
586

587
**Usage Examples:**
588

589
```javascript
590
// Configuration validation
591
function validateTreeConfig(config) {
592
  const errors = [];
593
  const warnings = [];
594
  
595
  // Check required properties
596
  if (!config.core) {
597
    errors.push("Core configuration is required");
598
  }
599
  
600
  // Validate plugins
601
  if (config.plugins && config.plugins.includes("checkbox") && config.plugins.includes("conditionalselect")) {
602
    warnings.push("checkbox and conditionalselect plugins may conflict");
603
  }
604
  
605
  // Check data configuration
606
  if (config.core.data && typeof config.core.data === "object" && !config.core.data.url && !Array.isArray(config.core.data)) {
607
    errors.push("Invalid data configuration");
608
  }
609
  
610
  return {
611
    valid: errors.length === 0,
612
    errors: errors,
613
    warnings: warnings
614
  };
615
}
616

617
const config = {
618
  "core": {"data": "invalid"},
619
  "plugins": ["checkbox", "conditionalselect"]
620
};
621

622
const validation = validateTreeConfig(config);
623
if (!validation.valid) {
624
  console.error("Configuration errors:", validation.errors);
625
}
626
if (validation.warnings.length) {
627
  console.warn("Configuration warnings:", validation.warnings);
628
}
629
```
630

631
## Types
632

633
```javascript { .api }
634
// Complete configuration interface
635
interface JsTreeConfig {
636
  core?: CoreConfig;
637
  plugins?: Array<string>;
638
  [plugin: string]: any;
639
}
640

641
// Configuration context
642
interface ConfigContext {
643
  element: jQuery;
644
  instanceId: number;
645
  userRole?: string;
646
  permissions?: Array<string>;
647
  environment?: string;
648
}
649

650
// Configuration result  
651
interface ConfigResult {
652
  config: JsTreeConfig;
653
  warnings: Array<string>;
654
  metadata: object;
655
}
656
```