0
# JSONEditor
1

2
JSONEditor is a comprehensive web-based JSON manipulation library that provides multiple editing modes including tree editor, code editor, text editor, and preview mode. It enables developers to build applications that can view, edit, format, validate, and transform JSON data with features like syntax highlighting, JSON schema validation, JMESPath query transformation, undo/redo functionality, search and highlighting, color picking, and the ability to handle large JSON documents up to 500 MiB.
3

4
## Package Information
5

6
- **Package Name**: jsoneditor
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jsoneditor`
10
- **License**: Apache-2.0
11
- **Version**: 10.4.1
12

13
## Core Imports
14

15
ESM:
16
```javascript
17
import JSONEditor from "jsoneditor";
18
```
19

20
TypeScript:
21
```typescript
22
import JSONEditor, { type JSONEditorOptions, type ValidationError } from "jsoneditor";
23
```
24

25
CommonJS:
26
```javascript
27
const JSONEditor = require("jsoneditor");
28
```
29

30
UMD (Browser):
31
```html
32
<script src="node_modules/jsoneditor/dist/jsoneditor.min.js"></script>
33
<link href="node_modules/jsoneditor/dist/jsoneditor.min.css" rel="stylesheet" type="text/css">
34
```
35

36
## Basic Usage
37

38
```javascript
39
import JSONEditor from "jsoneditor";
40

41
// Create a container element
42
const container = document.getElementById("jsoneditor");
43

44
// Set configuration options
45
const options = {
46
  mode: "tree",
47
  modes: ["code", "form", "text", "tree", "view", "preview"],
48
  search: true
49
};
50

51
// Initialize the editor
52
const editor = new JSONEditor(container, options);
53

54
// Set JSON data
55
const json = {
56
  "Array": [1, 2, 3],
57
  "Boolean": true,
58
  "Null": null,
59
  "Number": 123,
60
  "Object": {"a": "b", "c": "d"},
61
  "String": "Hello World"
62
};
63
editor.set(json);
64

65
// Get JSON data
66
const data = editor.get();
67
```
68

69
## Architecture
70

71
JSONEditor is built around several key components:
72

73
- **Mode System**: Pluggable editor modes (tree, text, code, preview) with different interaction patterns
74
- **Configuration Options**: Extensive customization through callback functions and behavioral settings
75
- **Event System**: Comprehensive event handling for changes, validation, focus, and user interactions
76
- **Validation Engine**: JSON schema validation powered by Ajv with custom validation support
77
- **Transform System**: JMESPath-based data transformation and filtering capabilities
78
- **Internationalization**: Built-in support for multiple languages with customizable translations
79

80
## Capabilities
81

82
### Editor Core
83

84
Main JSONEditor constructor and core data manipulation methods for creating editors and managing JSON content.
85

86
```javascript { .api }
87
class JSONEditor {
88
  constructor(container: HTMLElement, options?: JSONEditorOptions, json?: any);
89
  
90
  // Core data methods
91
  get(): any;
92
  set(json: any): void;
93
  getText(): string;
94
  setText(jsonString: string): void;
95
  update(json: any): void;
96
  updateText(jsonString: string): void;
97
}
98
```
99

100
[Editor Core](./editor-core.md)
101

102
### Configuration and Options
103

104
Comprehensive configuration system with over 40 options for customizing editor behavior, appearance, and functionality.
105

106
```javascript { .api }
107
interface JSONEditorOptions {
108
  mode?: "tree" | "view" | "form" | "code" | "text" | "preview";
109
  modes?: Array<"tree" | "view" | "form" | "code" | "text" | "preview">;
110
  search?: boolean;
111
  history?: boolean;
112
  schema?: object;
113
  onChange?: () => void;
114
  onChangeJSON?: (json: any) => void;
115
  onChangeText?: (jsonString: string) => void;
116
  onError?: (error: Error) => void;
117
}
118
```
119

120
[Configuration](./configuration.md)
121

122
### Mode Management
123

124
Mode switching functionality enabling dynamic transitions between different editor interfaces and behaviors.
125

126
```javascript { .api }
127
// Mode control methods
128
setMode(mode: string): void;
129
getMode(): string;
130

131
// Mode registration for plugins
132
static registerMode(mode: ModeDefinition): void;
133
```
134

135
[Mode Management](./mode-management.md)
136

137
### Schema Validation
138

139
JSON schema validation system with comprehensive error reporting and custom validation support.
140

141
```javascript { .api }
142
setSchema(schema: object, schemaRefs?: object): void;
143
validate(): Promise<ValidationError[]>;
144

145
interface ValidationError {
146
  type: string;
147
  path: (string | number)[];
148
  message: string;
149
}
150
```
151

152
[Schema Validation](./schema-validation.md)
153

154
### Tree Mode Operations
155

156
Interactive tree editing capabilities including node manipulation, selection, expansion, search, and visual operations.
157

158
```javascript { .api }
159
// Tree expansion/collapse
160
expandAll(): void;
161
collapseAll(): void;
162
expand(options: ExpandOptions): void;
163

164
// Selection management
165
setSelection(start?: PathArray, end?: PathArray): void;
166
getSelection(): { start: SerializableNode; end: SerializableNode };
167
getNodesByRange(start: PathArray, end: PathArray): SerializableNode[];
168

169
// Search functionality
170
search(text: string): SearchResult[];
171
```
172

173
[Tree Operations](./tree-operations.md)
174

175
### Text and Code Editing
176

177
Text-based editing features for code and plain text modes with selection management, cursor positioning, and JSON formatting.
178

179
```javascript { .api }
180
// Text selection methods
181
getTextSelection(): TextSelection;
182
setTextSelection(startPos: Position, endPos: Position): void;
183

184
// JSON formatting methods
185
format(): void;
186
compact(): void;
187
repair(): void;
188
resize(force?: boolean): void;
189

190
interface TextSelection {
191
  start: { row: number; column: number };
192
  end: { row: number; column: number };
193
  text: string;
194
}
195
```
196

197
[Text Operations](./text-operations.md)
198

199
### Transform and Query Operations
200

201
JMESPath-based data transformation and filtering capabilities with custom query language support.
202

203
```javascript { .api }
204
interface QueryOptions {
205
  filter?: {
206
    field: string | "@";
207
    relation: "==" | "!=" | "<" | "<=" | ">" | ">=";
208
    value: string;
209
  };
210
  sort?: {
211
    field: string | "@";
212
    direction: "asc" | "desc";
213
  };
214
  projection?: {
215
    fields: string[];
216
  };
217
}
218
```
219

220
[Transform Operations](./transform-operations.md)
221

222
### Preview Mode for Large Documents
223

224
High-performance read-only mode for handling large JSON documents up to 500 MiB with minimal memory usage.
225

226
```javascript { .api }
227
// Large document handling
228
executeWithBusyMessage(fn: () => any, message: string): Promise<any>;
229

230
// Inherited formatting methods optimized for large data
231
format(): void;
232
compact(): void;
233
repair(): void;
234
```
235

236
[Preview Mode](./preview-mode.md)
237

238
### Static Methods and Properties
239

240
Access to static functionality and bundled libraries for mode registration and utility operations.
241

242
```javascript { .api }
243
class JSONEditor {
244
  // Mode registration system
245
  static registerMode(mode: ModeDefinition | ModeDefinition[]): void;
246
  static modes: { [modeName: string]: ModeDefinition };
247
  
248
  // Library access
249
  static ace: any; // Bundled Ace editor
250
  static Ajv: any; // Bundled Ajv validation library
251
  static VanillaPicker: any; // Bundled VanillaPicker color picker
252
  
253
  // Utility functions (undocumented/internal)
254
  static showTransformModal: (json: any, queryDescription: string, createQuery: Function, executeQuery: Function, onTransform: Function) => void;
255
  static showSortModal: (json: any, onSort: Function) => void;
256
  static getInnerText: (element: HTMLElement) => string;
257
  
258
  // Configuration
259
  static VALID_OPTIONS: string[]; // Array of all valid configuration option names
260
  static default: typeof JSONEditor; // Default export for TypeScript ES6
261
}
262
```
263

264
## Types
265

266
```javascript { .api }
267
type PathArray = (string | number)[];
268

269
interface SerializableNode {
270
  value: any;
271
  path: PathArray;
272
}
273

274
interface Position {
275
  row: number;
276
  column: number;
277
}
278

279
interface ExpandOptions {
280
  path: PathArray;
281
  isExpand: boolean;
282
  recursive?: boolean;
283
  withPath?: boolean;
284
}
285

286
interface ModeDefinition {
287
  /** Unique name for the mode */
288
  mode: string;
289
  
290
  /** Mixin object containing mode implementation */
291
  mixin: ModeMixin;
292
  
293
  /** Data type the mode operates on */
294
  data: "text" | "json";
295
  
296
  /** Optional load function called after mode initialization */
297
  load?: () => void;
298
}
299

300
interface ModeMixin {
301
  /** Required: Create the mode interface */
302
  create: (container: HTMLElement, options: JSONEditorOptions) => void;
303
  
304
  /** Get current data (return type depends on mode.data) */
305
  get?: () => any;
306
  
307
  /** Set data (parameter type depends on mode.data) */
308
  set?: (data: any) => void;
309
  
310
  /** Get data as text string */
311
  getText?: () => string;
312
  
313
  /** Set data from text string */
314
  setText?: (text: string) => void;
315
  
316
  /** Destroy the mode and clean up resources */
317
  destroy?: () => void;
318
  
319
  /** Additional mode-specific methods */
320
  [methodName: string]: any;
321
}
322
```