0
# Checkbox Functionality
1

2
Tri-state checkbox functionality with support for cascading selection, parent-child relationships, and individual checkbox control. The checkbox plugin transforms the tree into a hierarchical selection interface with automatic parent-child state synchronization.
3

4
## Capabilities
5

6
### Checkbox Configuration
7

8
Configuration options for the checkbox plugin behavior.
9

10
```javascript { .api }
11
/**
12
 * Checkbox plugin configuration
13
 */
14
interface CheckboxConfig {
15
  /** Show checkboxes (default: true) */
16
  visible?: boolean;
17
  /** Enable tri-state checkboxes with undetermined state (default: true) */
18
  three_state?: boolean;
19
  /** Make the whole node clickable, not just the checkbox (default: true) */
20
  whole_node?: boolean;
21
  /** Keep selected styling on checked nodes (default: true) */
22
  keep_selected_style?: boolean;
23
  /** Cascading behavior: "up", "down", "up+down", "undetermined", or "" (default: "" but becomes "up+down+undetermined" when three_state is true) */
24
  cascade?: string;
25
  /** Apply cascading to disabled checkboxes (default: true) */
26
  cascade_to_disabled?: boolean;
27
  /** Apply cascading to hidden checkboxes (default: true) */
28
  cascade_to_hidden?: boolean;
29
  /** Bind checkbox state to selection state (default: true) */
30
  tie_selection?: boolean;
31
}
32

33
// Usage in tree initialization
34
const config = {
35
  "plugins": ["checkbox"],
36
  "checkbox": {
37
    "visible": true,
38
    "three_state": true,
39
    "whole_node": true,
40
    "keep_selected_style": false,
41
    "cascade": "up+down+undetermined",
42
    "cascade_to_disabled": true,
43
    "cascade_to_hidden": true,
44
    "tie_selection": false
45
  }
46
};
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
// Initialize tree with checkboxes
53
$("#tree").jstree({
54
  "core": {
55
    "data": ["Parent 1", "Parent 2"]
56
  },
57
  "plugins": ["checkbox"],
58
  "checkbox": {
59
    "three_state": true,
60
    "cascade": "up+down+undetermined"
61
  }
62
});
63

64
// Get instance and use checkbox methods
65
const tree = $("#tree").jstree(true);
66
```
67

68
### Checkbox State Management
69

70
Methods for checking and unchecking nodes.
71

72
```javascript { .api }
73
/**
74
 * Check a node's checkbox
75
 * @param obj - Node to check
76
 * @param e - Original event object
77
 * @returns True on success
78
 */
79
check_node(obj: string|object, e?: Event): boolean;
80

81
/**
82
 * Uncheck a node's checkbox
83
 * @param obj - Node to uncheck
84
 * @param e - Original event object
85
 * @returns True on success
86
 */
87
uncheck_node(obj: string|object, e?: Event): boolean;
88

89
/**
90
 * Check all nodes in the tree
91
 * @returns True on success
92
 */
93
check_all(): boolean;
94

95
/**
96
 * Uncheck all nodes in the tree
97
 * @returns True on success
98
 */
99
uncheck_all(): boolean;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Check specific nodes
106
tree.check_node("node_1");
107
tree.check_node(["node_2", "node_3"]);
108

109
// Uncheck specific nodes
110
tree.uncheck_node("node_1");
111

112
// Check/uncheck all
113
tree.check_all();
114
tree.uncheck_all();
115
```
116

117
### Checkbox State Checking
118

119
Methods for determining checkbox states.
120

121
```javascript { .api }
122
/**
123
 * Check if a node is checked
124
 * @param obj - Node to check
125
 * @returns True if node is checked
126
 */
127
is_checked(obj: string|object): boolean;
128

129
/**
130
 * Check if a node is in undetermined state (partially checked)
131
 * @param obj - Node to check
132
 * @returns True if node is undetermined
133
 */
134
is_undetermined(obj: string|object): boolean;
135
```
136

137
**Usage Examples:**
138

139
```javascript
140
// Check individual node states
141
if (tree.is_checked("node_1")) {
142
  console.log("Node 1 is checked");
143
}
144

145
if (tree.is_undetermined("parent_node")) {
146
  console.log("Parent node is partially checked");
147
}
148
```
149

150
### Checkbox Retrieval
151

152
Methods for getting checked nodes and their relationships.
153

154
```javascript { .api }
155
/**
156
 * Get all checked nodes
157
 * @param full - Return full node objects instead of IDs
158
 * @returns Array of checked node IDs or objects
159
 */
160
get_checked(full?: boolean): Array<string|object>;
161

162
/**
163
 * Get top-level checked nodes (checked nodes with no checked ancestors)
164
 * @param full - Return full node objects instead of IDs
165
 * @returns Array of top-level checked node IDs or objects
166
 */
167
get_top_checked(full?: boolean): Array<string|object>;
168

169
/**
170
 * Get bottom-level checked nodes (checked nodes with no checked descendants)
171
 * @param full - Return full node objects instead of IDs
172
 * @returns Array of bottom-level checked node IDs or objects
173
 */
174
get_bottom_checked(full?: boolean): Array<string|object>;
175

176
/**
177
 * Get all checked descendants of a node
178
 * @param id - Parent node ID
179
 * @returns Array of checked descendant node IDs
180
 */
181
get_checked_descendants(id: string): Array<string>;
182
```
183

184
**Usage Examples:**
185

186
```javascript
187
// Get checked nodes in different ways
188
const checkedIds = tree.get_checked();
189
const checkedNodes = tree.get_checked(true);
190

191
// Get hierarchical selections
192
const topChecked = tree.get_top_checked();
193
const bottomChecked = tree.get_bottom_checked();
194

195
// Get descendants of specific node
196
const descendants = tree.get_checked_descendants("parent_1");
197

198
console.log("Checked IDs:", checkedIds);
199
console.log("Top-level checked:", topChecked);
200
```
201

202
### Checkbox Control
203

204
Methods for controlling checkbox visibility and interaction.
205

206
```javascript { .api }
207
/**
208
 * Disable checkbox for a specific node
209
 * @param obj - Node to disable checkbox for
210
 * @returns True on success
211
 */
212
disable_checkbox(obj: string|object): boolean;
213

214
/**
215
 * Enable checkbox for a specific node
216
 * @param obj - Node to enable checkbox for
217
 * @returns True on success
218
 */
219
enable_checkbox(obj: string|object): boolean;
220

221
/**
222
 * Show all checkboxes in the tree
223
 * @returns True on success
224
 */
225
show_checkboxes(): boolean;
226

227
/**
228
 * Hide all checkboxes in the tree
229
 * @returns True on success
230
 */
231
hide_checkboxes(): boolean;
232

233
/**
234
 * Toggle checkbox visibility
235
 * @returns True on success
236
 */
237
toggle_checkboxes(): boolean;
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
// Control individual node checkboxes
244
tree.disable_checkbox("readonly_node");
245
tree.enable_checkbox("editable_node");
246

247
// Control global checkbox visibility
248
tree.hide_checkboxes(); // Hide all checkboxes
249
tree.show_checkboxes(); // Show all checkboxes
250
tree.toggle_checkboxes(); // Toggle visibility
251
```
252

253
## Checkbox Events
254

255
The checkbox plugin adds specific events for checkbox interactions.
256

257
```javascript { .api }
258
// Checkbox-specific events
259
"check_node.jstree": CheckboxEvent;
260
"uncheck_node.jstree": CheckboxEvent;
261

262
interface CheckboxEvent {
263
  node: object;
264
  selected: Array<string>;
265
  event: Event;
266
  instance: jsTree;
267
}
268
```
269

270
**Usage Examples:**
271

272
```javascript
273
// Listen for checkbox events
274
$("#tree").on("check_node.jstree", function (e, data) {
275
  console.log("Node checked:", data.node.text);
276
  console.log("All checked nodes:", data.selected);
277
});
278

279
$("#tree").on("uncheck_node.jstree", function (e, data) {
280
  console.log("Node unchecked:", data.node.text);
281
  console.log("Remaining checked nodes:", data.selected);
282
});
283
```
284

285
## Cascade Modes
286

287
The checkbox plugin supports different cascading behaviors:
288

289
```javascript { .api }
290
/**
291
 * Cascade mode options:
292
 * - "up": Checking a child affects parent state
293
 * - "down": Checking a parent affects children state  
294
 * - "up+down": Both directions (default)
295
 * - "undetermined": Show partial/undetermined states
296
 * - "up+down+undetermined": Full tri-state behavior
297
 * - "": No cascading
298
 */
299
type CascadeMode = "up" | "down" | "up+down" | "undetermined" | "up+down+undetermined" | "";
300
```
301

302
**Usage Examples:**
303

304
```javascript
305
// Different cascade configurations
306
$("#tree1").jstree({
307
  "plugins": ["checkbox"],
308
  "checkbox": {
309
    "cascade": "down" // Only cascade downward
310
  }
311
});
312

313
$("#tree2").jstree({
314
  "plugins": ["checkbox"],
315
  "checkbox": {
316
    "cascade": "up+down+undetermined" // Full tri-state
317
  }
318
});
319

320
$("#tree3").jstree({
321
  "plugins": ["checkbox"],
322
  "checkbox": {
323
    "cascade": "" // No cascading
324
  }
325
});
326
```
327

328
## Integration with Selection
329

330
When `tie_selection` is enabled, checkbox state is synchronized with node selection:
331

332
```javascript { .api }
333
/**
334
 * Configuration for checkbox-selection integration
335
 */
336
interface CheckboxSelectionIntegration {
337
  /** Synchronize checkbox and selection states */
338
  tie_selection: boolean;
339
  /** Keep visual selection styling on checked nodes */
340
  keep_selected_style: boolean;
341
}
342
```
343

344
**Usage Examples:**
345

346
```javascript
347
// Checkbox state tied to selection
348
$("#tree").jstree({
349
  "plugins": ["checkbox"],
350
  "checkbox": {
351
    "tie_selection": true,
352
    "keep_selected_style": false
353
  }
354
});
355

356
// When checkbox is checked, node becomes selected
357
// When node is selected, checkbox becomes checked
358
const tree = $("#tree").jstree(true);
359
tree.check_node("node_1"); // Also selects the node
360
tree.select_node("node_2"); // Also checks the checkbox
361
```
362

363
## Accessibility
364

365
The checkbox plugin includes accessibility features:
366

367
```javascript { .api }
368
/**
369
 * Accessibility features automatically included:
370
 * - ARIA attributes for checkbox states
371
 * - Keyboard navigation support
372
 * - Screen reader compatibility
373
 * - Focus management
374
 */
375
```
376

377
**Usage Examples:**
378

379
```javascript
380
// Checkboxes automatically include:
381
// - aria-checked="true|false|mixed"
382
// - role="checkbox" 
383
// - Keyboard support (Space to toggle)
384
// - Focus indicators
385

386
// Enable keyboard navigation
387
$("#tree").jstree({
388
  "plugins": ["checkbox"],
389
  "core": {
390
    "keyboard": {
391
      "checkbox": true // Enable checkbox keyboard shortcuts
392
    }
393
  }
394
});
395
```
396

397
## Types
398

399
```javascript { .api }
400
// Checkbox node state extensions
401
interface CheckboxNode extends TreeNode {
402
  state: {
403
    checked: boolean;
404
    undetermined: boolean;
405
    checkbox_disabled: boolean;
406
    [key: string]: any;
407
  };
408
}
409

410
// Plugin-specific configuration
411
interface CheckboxSettings {
412
  visible: boolean;
413
  three_state: boolean;
414
  whole_node: boolean;
415
  keep_selected_style: boolean;
416
  cascade: string;
417
  tie_selection: boolean;
418
}
419
```