0
# Configuration
1

2
Comprehensive configuration system with over 40 options for customizing editor behavior, appearance, and functionality through the JSONEditorOptions interface.
3

4
## Capabilities
5

6
### Core Editor Options
7

8
Basic editor configuration options that control fundamental behavior.
9

10
```javascript { .api }
11
interface CoreOptions {
12
  /** Editor mode: tree, view, form, code, text, or preview */
13
  mode?: "tree" | "view" | "form" | "code" | "text" | "preview";
14
  
15
  /** Array of modes available for user switching */
16
  modes?: Array<"tree" | "view" | "form" | "code" | "text" | "preview">;
17
  
18
  /** Enable search box (tree/view/form modes only) */
19
  search?: boolean;
20
  
21
  /** Enable undo/redo functionality (tree/form/preview modes only) */
22
  history?: boolean;
23
  
24
  /** Field name for the root node (tree/view/form modes only) */
25
  name?: string;
26
  
27
  /** Number of indentation spaces (code/text/preview modes only) */
28
  indentation?: number;
29
  
30
  /** Ace editor theme (code mode only) */
31
  theme?: string;
32
}
33
```
34

35
### Event Callback Options
36

37
Event handling configuration for responding to user interactions and data changes.
38

39
```javascript { .api }
40
interface EventCallbacks {
41
  /** Triggered when contents change (does not pass data) */
42
  onChange?: () => void;
43
  
44
  /** Triggered when JSON changes, passes the changed JSON (tree/view/form modes) */
45
  onChangeJSON?: (json: any) => void;
46
  
47
  /** Triggered when text changes, passes stringified JSON */
48
  onChangeText?: (jsonString: string) => void;
49
  
50
  /** Triggered when an error occurs */
51
  onError?: (error: Error) => void;
52
  
53
  /** Triggered when mode changes */
54
  onModeChange?: (newMode: string, oldMode: string) => void;
55
  
56
  /** Triggered when editor gains focus */
57
  onFocus?: (event: { type: "focus"; target: any }) => void;
58
  
59
  /** Triggered when editor loses focus */
60
  onBlur?: (event: { type: "blur"; target: any }) => void;
61
  
62
  /** Triggered on node selection change (tree mode only) */
63
  onSelectionChange?: (start?: SerializableNode, end?: SerializableNode) => void;
64
  
65
  /** Triggered on text selection change (code/text modes only) */
66
  onTextSelectionChange?: (
67
    start: { row: number; column: number },
68
    end: { row: number; column: number },
69
    text: string
70
  ) => void;
71
  
72
  /** Triggered on node events (tree/view/form modes only) */
73
  onEvent?: (node: NodeEvent, event: Event) => void;
74
}
75
```
76

77
### Validation Options
78

79
Configuration for JSON schema validation and custom validation functions.
80

81
```javascript { .api }
82
interface ValidationOptions {
83
  /** JSON schema object for validation */
84
  schema?: object;
85
  
86
  /** Referenced schemas for $ref properties */
87
  schemaRefs?: { [key: string]: object };
88
  
89
  /** 
90
   * Custom Ajv instance for validation
91
   * IMPORTANT: JSONEditor relies on specific Ajv configuration.
92
   * Providing different configuration (like jsonPointers: true instead of false)
93
   * may cause JSONEditor to break due to different error formats.
94
   */
95
  ajv?: any;
96
  
97
  /** Custom validation function */
98
  onValidate?: (json: any) => ValidationError[] | Promise<ValidationError[]>;
99
  
100
  /** Callback for validation errors */
101
  onValidationError?: (errors: ValidationError[]) => void;
102
}
103
```
104

105
### Appearance Options
106

107
Visual customization options for styling and display behavior.
108

109
```javascript { .api }
110
interface AppearanceOptions {
111
  /** Escape unicode characters as hex codes */
112
  escapeUnicode?: boolean;
113
  
114
  /** Sort object keys alphabetically */
115
  sortObjectKeys?: boolean;
116
  
117
  /** Enable color picker for color values */
118
  colorPicker?: boolean;
119
  
120
  /** Show timestamp tags for timestamp values */
121
  timestampTag?: boolean | ((node: NodeInfo) => boolean);
122
  
123
  /** Custom timestamp formatting function */
124
  timestampFormat?: (node: NodeInfo) => string | null;
125
  
126
  /** Show main menu bar */
127
  mainMenuBar?: boolean;
128
  
129
  /** Show navigation bar (tree/view/form modes) */
130
  navigationBar?: boolean;
131
  
132
  /** Show status bar (code/text/preview modes) */
133
  statusBar?: boolean;
134
  
135
  /** Show error table on validation errors */
136
  showErrorTable?: boolean | string[];
137
}
138
```
139

140
### Behavior Options
141

142
Options that control editor behavior and user interaction patterns.
143

144
```javascript { .api }
145
interface BehaviorOptions {
146
  /** Restrict dragging to same parent node */
147
  limitDragging?: boolean;
148
  
149
  /** Maximum visible children before "show more" appears */
150
  maxVisibleChilds?: number;
151
  
152
  /** Enable sorting functionality */
153
  enableSort?: boolean;
154
  
155
  /** Enable transform/filter functionality */
156
  enableTransform?: boolean;
157
  
158
  /** Enable schema-based autocomplete suggestions */
159
  allowSchemaSuggestions?: boolean;
160
}
161
```
162

163
### Customization Functions
164

165
Advanced customization through callback functions for dynamic behavior.
166

167
```javascript { .api }
168
interface CustomizationOptions {
169
  /** Control editability of individual nodes (tree/text/code modes) */
170
  onEditable?: (node: NodeInfo) => boolean | { field: boolean; value: boolean };
171
  
172
  /** Add custom CSS classes to nodes */
173
  onClassName?: (node: NodeInfo) => string | undefined;
174
  
175
  /** Customize object/array node names */
176
  onNodeName?: (node: NodeNameInfo) => string | undefined;
177
  
178
  /** Customize context menus */
179
  onCreateMenu?: (items: MenuItem[], node: MenuContext) => MenuItem[];
180
  
181
  /** Triggered on node expand/collapse */
182
  onExpand?: (info: { path: PathArray; isExpand: boolean; recursive: boolean }) => void;
183
  
184
  /** Custom color picker implementation */
185
  onColorPicker?: (
186
    parent: HTMLElement,
187
    color: string,
188
    onChange: (newColor: string) => void
189
  ) => void;
190
}
191
```
192

193
### Advanced Options
194

195
Advanced configuration for specialized use cases and integrations.
196

197
```javascript { .api }
198
interface AdvancedOptions {
199
  /** 
200
   * Custom Ace editor instance for code mode
201
   * Required plugins: mode-json, worker-json, ext-searchbox, ext-language_tools
202
   * In minimalist builds, plugins must be loaded separately
203
   */
204
  ace?: any;
205
  
206
  /** Template objects for context menu */
207
  templates?: Template[];
208
  
209
  /** Autocomplete configuration */
210
  autocomplete?: AutocompleteConfig;
211
  
212
  /** Container element for modal dialogs */
213
  modalAnchor?: HTMLElement;
214
  
215
  /** Container element for popup elements */
216
  popupAnchor?: HTMLElement;
217
  
218
  /** Language code for internationalization */
219
  language?: string;
220
  
221
  /** Custom translations */
222
  languages?: { [language: string]: { [key: string]: string } };
223
  
224
  /** Custom query creation function */
225
  createQuery?: (json: any, queryOptions: QueryOptions) => string;
226
  
227
  /** Custom query execution function */
228
  executeQuery?: (json: any, query: string) => any;
229
  
230
  /** Query language description */
231
  queryDescription?: string;
232
}
233
```
234

235
### Complete Options Interface
236

237
The full JSONEditorOptions interface combining all configuration categories.
238

239
```javascript { .api }
240
interface JSONEditorOptions
241
  extends CoreOptions,
242
    EventCallbacks,
243
    ValidationOptions,
244
    AppearanceOptions,
245
    BehaviorOptions,
246
    CustomizationOptions,
247
    AdvancedOptions {}
248
```
249

250
## Usage Examples
251

252
### Basic Configuration
253

254
```javascript
255
const options = {
256
  mode: "tree",
257
  modes: ["tree", "code", "text"],
258
  search: true,
259
  history: true,
260
  indentation: 2
261
};
262

263
const editor = new JSONEditor(container, options);
264
```
265

266
### Event Handling Configuration
267

268
```javascript
269
const options = {
270
  mode: "tree",
271
  onChange: () => {
272
    console.log("Content changed");
273
  },
274
  onChangeJSON: (json) => {
275
    console.log("New JSON:", json);
276
  },
277
  onError: (error) => {
278
    console.error("Editor error:", error);
279
  },
280
  onSelectionChange: (start, end) => {
281
    console.log("Selection changed:", start, end);
282
  }
283
};
284
```
285

286
### Validation Configuration
287

288
```javascript
289
const schema = {
290
  type: "object",
291
  properties: {
292
    name: { type: "string" },
293
    age: { type: "number", minimum: 0 }
294
  },
295
  required: ["name"]
296
};
297

298
const options = {
299
  mode: "tree",
300
  schema: schema,
301
  onValidationError: (errors) => {
302
    errors.forEach(error => {
303
      console.log(`Validation error: ${error.message}`);
304
    });
305
  }
306
};
307
```
308

309
### Advanced Customization
310

311
```javascript
312
const options = {
313
  mode: "tree",
314
  onClassName: ({ path, field, value }) => {
315
    if (field === "email") return "email-field";
316
    if (typeof value === "number" && value < 0) return "negative-number";
317
  },
318
  onNodeName: ({ type, size }) => {
319
    return type === "array" ? `[${size} items]` : `{${size} props}`;
320
  },
321
  templates: [
322
    {
323
      text: "Person",
324
      title: "Insert Person Template",
325
      field: "person",
326
      value: { name: "", age: 0, email: "" }
327
    }
328
  ]
329
};
330
```
331

332
## Supporting Types
333

334
```javascript { .api }
335
interface NodeInfo {
336
  field: string;
337
  value: any;
338
  path: PathArray;
339
}
340

341
interface NodeNameInfo {
342
  path: PathArray;
343
  type: "object" | "array";
344
  size: number;
345
  value: any;
346
}
347

348
interface NodeEvent {
349
  field?: string;
350
  path: PathArray;
351
  value?: any;
352
}
353

354
interface MenuItem {
355
  text: string;
356
  title?: string;
357
  className?: string;
358
  click?: () => void;
359
  submenu?: MenuItem[];
360
}
361

362
interface MenuContext {
363
  type: "single" | "multiple" | "append";
364
  path: PathArray;
365
  paths: PathArray[];
366
}
367

368
interface Template {
369
  text: string;
370
  title?: string;
371
  className?: string;
372
  field?: string;
373
  value: any;
374
}
375

376
interface AutocompleteConfig {
377
  filter?: "start" | "contain" | ((token: string, match: string | { text: string; value: any }) => boolean);
378
  trigger?: "keydown" | "focus";
379
  confirmKeys?: number[];
380
  caseSensitive?: boolean;
381
  getOptions?: (
382
    text: string,
383
    path: PathArray,
384
    input: "field" | "value",
385
    editor: JSONEditor
386
  ) => string[] | { text: string; value: any }[] | { startFrom: number; options: any[] } | Promise<any>;
387
}
388
```