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
```