0
# Search and Filter
1

2
Fuzzy search functionality with highlighting, show-only-matches mode, and customizable search patterns. The search plugin provides powerful text-based filtering with visual feedback and multiple search strategies.
3

4
## Capabilities
5

6
### Search Configuration
7

8
Configuration options for the search plugin behavior.
9

10
```javascript { .api }
11
/**
12
 * Search plugin configuration
13
 */
14
interface SearchConfig {
15
  /** AJAX configuration for server-side search */
16
  ajax?: object|function;
17
  /** Enable fuzzy matching (default: false) */
18
  fuzzy?: boolean;
19
  /** Case sensitive search (default: false) */
20
  case_sensitive?: boolean;
21
  /** Show only matching nodes (default: false) */
22
  show_only_matches?: boolean;
23
  /** Also show children of matching nodes (default: false) */
24
  show_only_matches_children?: boolean;
25
  /** Close opened nodes when clearing search (default: true) */
26
  close_opened_onclear?: boolean;
27
  /** Search only in leaf nodes (default: false) */
28
  search_leaves_only?: boolean;
29
  /** Custom search callback function */
30
  search_callback?: function;
31
}
32

33
// Usage in tree initialization
34
const config = {
35
  "plugins": ["search"],
36
  "search": {
37
    "fuzzy": true,
38
    "case_sensitive": false,
39
    "show_only_matches": true,
40
    "show_only_matches_children": true
41
  }
42
};
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
// Initialize tree with search
49
$("#tree").jstree({
50
  "core": {
51
    "data": [
52
      "Apple", "Banana", "Cherry", 
53
      {"text": "Fruits", "children": ["Orange", "Grape"]}
54
    ]
55
  },
56
  "plugins": ["search"],
57
  "search": {
58
    "fuzzy": true,
59
    "show_only_matches": true
60
  }
61
});
62

63
// Get instance for search operations
64
const tree = $("#tree").jstree(true);
65
```
66

67
### Basic Search Operations
68

69
Core methods for performing searches.
70

71
```javascript { .api }
72
/**
73
 * Search for nodes matching a string
74
 * @param str - Search string
75
 * @param skip_async - Skip asynchronous search (default: false)
76
 * @param show_only_matches - Show only matching nodes (overrides config)
77
 * @param inside - Limit search to descendants of this node
78
 * @param append - Append to existing search results (default: false)
79
 * @param show_only_matches_children - Show children of matches (overrides config)
80
 * @returns True if search was performed
81
 */
82
search(str: string, skip_async?: boolean, show_only_matches?: boolean, inside?: string, append?: boolean, show_only_matches_children?: boolean): boolean;
83

84
/**
85
 * Clear search results and restore normal tree view
86
 * @returns True on success
87
 */
88
clear_search(): boolean;
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
// Basic search
95
tree.search("apple");
96

97
// Search with options
98
tree.search("fruit", false, true, null, false, true);
99

100
// Search within specific subtree
101
tree.search("orange", false, true, "fruits_node");
102

103
// Append to existing search
104
tree.search("grape", false, true, null, true);
105

106
// Clear search results
107
tree.clear_search();
108
```
109

110
### Advanced Search Options
111

112
Methods for customized search behavior.
113

114
```javascript { .api }
115
/**
116
 * Search with custom callback for match validation
117
 * @param str - Search string
118
 * @param callback - Function to determine if node matches
119
 * @param show_only_matches - Show only matching nodes
120
 * @returns True if search was performed
121
 */
122
search(str: string, callback: function, show_only_matches?: boolean): boolean;
123

124
/**
125
 * Custom search callback function signature
126
 * @param str - Search string
127
 * @param node - Node object to test
128
 * @returns True if node matches search criteria
129
 */
130
type SearchCallback = (str: string, node: object) => boolean;
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
// Custom search callback
137
tree.search("test", function(str, node) {
138
  // Custom matching logic
139
  const text = node.text.toLowerCase();
140
  const search = str.toLowerCase();
141
  
142
  // Match if search term appears at word boundaries
143
  return new RegExp('\\b' + search).test(text);
144
}, true);
145

146
// Search only nodes with specific attributes
147
tree.search("important", function(str, node) {
148
  return node.li_attr && 
149
         node.li_attr.class && 
150
         node.li_attr.class.includes('important') &&
151
         node.text.toLowerCase().includes(str.toLowerCase());
152
});
153
```
154

155
### AJAX Search
156

157
Configuration for server-side search functionality.
158

159
```javascript { .api }
160
/**
161
 * AJAX search configuration
162
 */
163
interface AjaxSearchConfig {
164
  /** URL for search endpoint */
165
  url?: string;
166
  /** HTTP method (default: "GET") */
167
  method?: string;
168
  /** Request data configuration */
169
  data?: object|function;
170
  /** Response data type (default: "json") */
171
  dataType?: string;
172
  /** Custom success handler */
173
  success?: function;
174
  /** Custom error handler */
175
  error?: function;
176
}
177

178
// AJAX search function configuration
179
type AjaxSearchFunction = (str: string, callback: function) => void;
180
```
181

182
**Usage Examples:**
183

184
```javascript
185
// AJAX search with URL
186
$("#tree").jstree({
187
  "plugins": ["search"],
188
  "search": {
189
    "ajax": {
190
      "url": "/api/search",
191
      "method": "POST",
192
      "data": function(str) {
193
        return { "search_term": str };
194
      },
195
      "success": function(nodes) {
196
        // Process server response
197
        return nodes;
198
      }
199
    }
200
  }
201
});
202

203
// AJAX search with custom function
204
$("#tree").jstree({
205
  "plugins": ["search"],
206
  "search": {
207
    "ajax": function(str, callback) {
208
      $.ajax({
209
        url: "/api/tree-search",
210
        method: "GET",
211
        data: { q: str },
212
        success: function(data) {
213
          // Call callback with matching node IDs
214
          callback(data.matches);
215
        }
216
      });
217
    }
218
  }
219
});
220
```
221

222
### Fuzzy Search
223

224
Configuration and usage of fuzzy matching.
225

226
```javascript { .api }
227
/**
228
 * Fuzzy search configuration
229
 */
230
interface FuzzySearchConfig {
231
  /** Enable fuzzy matching */
232
  fuzzy: boolean;
233
  /** Minimum match threshold (0-1, default: 0.6) */
234
  threshold?: number;
235
  /** Character distance for fuzzy matching */
236
  distance?: number;
237
}
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
// Enable fuzzy search
244
$("#tree").jstree({
245
  "plugins": ["search"],
246
  "search": {
247
    "fuzzy": true,
248
    "case_sensitive": false
249
  }
250
});
251

252
// Fuzzy search will match:
253
// "apl" matches "Apple"
254
// "bnan" matches "Banana" 
255
// "chry" matches "Cherry"
256
tree.search("apl"); // Finds "Apple"
257
```
258

259
### Show Only Matches Mode
260

261
Configuration for filtering tree to show only matching nodes.
262

263
```javascript { .api }
264
/**
265
 * Show only matches configuration
266
 */
267
interface ShowOnlyMatchesConfig {
268
  /** Show only nodes that match search */
269
  show_only_matches: boolean;
270
  /** Also show children of matching nodes */
271
  show_only_matches_children: boolean;
272
  /** Show parents of matching nodes for context */
273
  show_only_matches_parents?: boolean;
274
}
275
```
276

277
**Usage Examples:**
278

279
```javascript
280
// Show only matches mode
281
$("#tree").jstree({
282
  "plugins": ["search"],
283
  "search": {
284
    "show_only_matches": true,
285
    "show_only_matches_children": true
286
  }
287
});
288

289
// When searching, only matching nodes and their children are visible
290
tree.search("fruit"); // Shows only "Fruit" nodes and their children
291

292
// Clear to restore full tree
293
tree.clear_search();
294
```
295

296
### Search Events
297

298
Events triggered during search operations.
299

300
```javascript { .api }
301
// Search-specific events
302
"search.jstree": SearchEvent;
303
"clear_search.jstree": ClearSearchEvent;
304

305
interface SearchEvent {
306
  nodes: Array<string>;
307
  str: string;
308
  res: Array<object>;
309
  instance: jsTree;
310
}
311

312
interface ClearSearchEvent {
313
  instance: jsTree;
314
}
315
```
316

317
**Usage Examples:**
318

319
```javascript
320
// Listen for search events
321
$("#tree").on("search.jstree", function (e, data) {
322
  console.log("Search performed:", data.str);
323
  console.log("Matching nodes:", data.nodes);
324
  console.log("Match count:", data.nodes.length);
325
});
326

327
$("#tree").on("clear_search.jstree", function (e, data) {
328
  console.log("Search cleared");
329
});
330

331
// Example: Update UI based on search results
332
$("#tree").on("search.jstree", function (e, data) {
333
  const resultCount = data.nodes.length;
334
  $("#search-results").text(resultCount + " matches found");
335
  
336
  if (resultCount === 0) {
337
    $("#no-results").show();
338
  }
339
});
340
```
341

342
### Search Integration with Other Plugins
343

344
Combining search with other plugins for enhanced functionality.
345

346
```javascript { .api }
347
/**
348
 * Search integration patterns
349
 */
350
interface SearchIntegration {
351
  /** Highlight matching text in nodes */
352
  highlight?: boolean;
353
  /** Maintain selection during search */
354
  preserve_selection?: boolean;
355
  /** Auto-expand parents of matches */
356
  auto_expand?: boolean;
357
}
358
```
359

360
**Usage Examples:**
361

362
```javascript
363
// Search with checkbox plugin
364
$("#tree").jstree({
365
  "plugins": ["search", "checkbox"],
366
  "search": {
367
    "show_only_matches": true
368
  }
369
});
370

371
// Search maintains checkbox states
372
tree.search("apple");
373
// Checked nodes remain checked even when filtered
374

375
// Search with state plugin  
376
$("#tree").jstree({
377
  "plugins": ["search", "state"],
378
  "search": {
379
    "close_opened_onclear": false
380
  }
381
});
382

383
// Search preserves open/closed state when cleared
384
```
385

386
### Search Utilities
387

388
Utility methods for search-related operations.
389

390
```javascript { .api }
391
/**
392
 * Get current search string
393
 * @returns Current search term or empty string
394
 */
395
get_search_string(): string;
396

397
/**
398
 * Check if search is currently active
399
 * @returns True if search is active
400
 */
401
is_search_active(): boolean;
402

403
/**
404
 * Get nodes that match current search
405
 * @returns Array of matching node IDs
406
 */
407
get_search_matches(): Array<string>;
408
```
409

410
**Usage Examples:**
411

412
```javascript
413
// Check search state
414
if (tree.is_search_active()) {
415
  const searchTerm = tree.get_search_string();
416
  const matches = tree.get_search_matches();
417
  console.log(`Searching for "${searchTerm}" - ${matches.length} matches`);
418
}
419

420
// Custom search UI
421
$("#search-input").on("input", function() {
422
  const term = $(this).val();
423
  if (term.length > 2) {
424
    tree.search(term);
425
  } else if (term.length === 0) {
426
    tree.clear_search();
427
  }
428
});
429

430
// Search status display
431
$("#tree").on("search.jstree", function(e, data) {
432
  $("#search-status").text(
433
    `Found ${data.nodes.length} matches for "${data.str}"`
434
  );
435
});
436
```
437

438
### Performance Considerations
439

440
Best practices for search performance with large trees.
441

442
```javascript { .api }
443
/**
444
 * Performance optimization options
445
 */
446
interface SearchPerformanceConfig {
447
  /** Debounce search input (milliseconds) */
448
  search_timeout?: number;
449
  /** Minimum characters before search triggers */
450
  min_chars?: number;
451
  /** Use web workers for large datasets */
452
  use_worker?: boolean;
453
  /** Cache search results */
454
  cache_results?: boolean;
455
}
456
```
457

458
**Usage Examples:**
459

460
```javascript
461
// Optimized search for large trees
462
let searchTimeout;
463
$("#search-input").on("input", function() {
464
  const term = $(this).val();
465
  
466
  clearTimeout(searchTimeout);
467
  searchTimeout = setTimeout(function() {
468
    if (term.length >= 3) {
469
      tree.search(term);
470
    } else if (term.length === 0) {
471
      tree.clear_search();
472
    }
473
  }, 300); // 300ms debounce
474
});
475

476
// Large dataset configuration
477
$("#tree").jstree({
478
  "plugins": ["search"],
479
  "search": {
480
    "ajax": "/api/search", // Server-side search for large datasets
481
    "show_only_matches": true, // Reduce DOM updates
482
    "search_leaves_only": true // Limit search scope
483
  }
484
});
485
```
486

487
## Types
488

489
```javascript { .api }
490
// Search-specific node extensions
491
interface SearchableNode extends TreeNode {
492
  search?: {
493
    matched: boolean;
494
    highlight_ranges?: Array<{start: number, end: number}>;
495
  };
496
}
497

498
// Search plugin settings
499
interface SearchSettings {
500
  ajax: object|function|false;
501
  fuzzy: boolean;
502
  case_sensitive: boolean;
503
  show_only_matches: boolean;
504
  show_only_matches_children: boolean;
505
  close_opened_onclear: boolean;
506
  search_leaves_only: boolean;
507
  search_callback: function|false;
508
}
509

510
// Search result data
511
interface SearchResult {
512
  nodes: Array<string>;
513
  matches: Array<object>;
514
  search_term: string;
515
  fuzzy_matches?: Array<object>;
516
}
517
```