0
# Main Editor
1

2
The primary AceEditor component provides comprehensive code editing functionality with syntax highlighting, themes, autocomplete, and extensive customization options. This is the core component that wraps the Ace Editor with React integration.
3

4
## Capabilities
5

6
### AceEditor Component
7

8
The main React component that renders an Ace Editor instance with full configuration and event handling support.
9

10
```typescript { .api }
11
/**
12
 * Main React-Ace editor component
13
 * Renders a fully-featured code editor with syntax highlighting, themes, and customization
14
 */
15
declare class ReactAce extends React.Component<IAceEditorProps> {}
16

17
interface IAceEditorProps {
18
  /** Unique identifier for the editor instance */
19
  name?: string;
20
  /** CSS styles for the editor container */
21
  style?: React.CSSProperties;
22
  /** Syntax highlighting mode (e.g., "javascript", "python", "java") */
23
  mode?: string | object;
24
  /** Editor theme (e.g., "github", "monokai", "twilight") */
25
  theme?: string;
26
  /** Editor height as CSS value */
27
  height?: string;
28
  /** Editor width as CSS value */
29
  width?: string;
30
  /** CSS class name for the editor container */
31
  className?: string;
32
  /** Font size for editor text */
33
  fontSize?: number | string;
34
  /** Line height for editor text */
35
  lineHeight?: number | string;
36
  /** Show line numbers in gutter */
37
  showGutter?: boolean;
38
  /** Show print margin indicator */
39
  showPrintMargin?: boolean;
40
  /** Highlight the currently active line */
41
  highlightActiveLine?: boolean;
42
  /** Auto-focus the editor on mount */
43
  focus?: boolean;
44
  /** Starting cursor position */
45
  cursorStart?: number;
46
  /** Enable line wrapping */
47
  wrapEnabled?: boolean;
48
  /** Make editor read-only */
49
  readOnly?: boolean;
50
  /** Minimum number of lines to display */
51
  minLines?: number;
52
  /** Maximum number of lines to display */
53
  maxLines?: number;
54
  /** Navigate cursor to end of file on load */
55
  navigateToFileEnd?: boolean;
56
  /** Debounce period for onChange events in milliseconds */
57
  debounceChangePeriod?: number;
58
  /** Enable basic autocompletion */
59
  enableBasicAutocompletion?: boolean | string[];
60
  /** Enable live autocompletion as you type */
61
  enableLiveAutocompletion?: boolean | string[];
62
  /** Enable mobile-friendly menu */
63
  enableMobileMenu?: boolean;
64
  /** Tab size in spaces */
65
  tabSize?: number;
66
  /** Current editor content */
67
  value?: string;
68
  /** Placeholder text when editor is empty */
69
  placeholder?: string;
70
  /** Default content when editor is first rendered */
71
  defaultValue?: string;
72
  /** Scroll margin for editor viewport */
73
  scrollMargin?: number[];
74
  /** Enable code snippets */
75
  enableSnippets?: boolean;
76
  /** Called when text selection changes */
77
  onSelectionChange?: (value: any, event?: any) => void;
78
  /** Called when cursor position changes */
79
  onCursorChange?: (value: any, event?: any) => void;
80
  /** Called on text input */
81
  onInput?: (event?: any) => void;
82
  /** Called when editor is fully loaded */
83
  onLoad?: (editor: Ace.Editor) => void;
84
  /** Called when syntax validation produces annotations */
85
  onValidate?: (annotations: Ace.Annotation[]) => void;
86
  /** Called before ace is loaded (for configuration) */
87
  onBeforeLoad?: (ace: typeof AceBuilds) => void;
88
  /** Called when editor content changes */
89
  onChange?: (value: string, event?: any) => void;
90
  /** Called when text is selected */
91
  onSelection?: (selectedText: string, event?: any) => void;
92
  /** Called when text is copied */
93
  onCopy?: (value: string) => void;
94
  /** Called when text is pasted */
95
  onPaste?: (value: string) => void;
96
  /** Called when editor gains focus */
97
  onFocus?: (event: any, editor?: Ace.Editor) => void;
98
  /** Called when editor loses focus */
99
  onBlur?: (event: any, editor?: Ace.Editor) => void;
100
  /** Called when editor is scrolled */
101
  onScroll?: (editor: IEditorProps) => void;
102
  /** Additional editor properties */
103
  editorProps?: IEditorProps;
104
  /** Ace editor configuration options */
105
  setOptions?: IAceOptions;
106
  /** Keyboard handler mode (e.g., "vim", "emacs") */
107
  keyboardHandler?: string;
108
  /** Custom editor commands */
109
  commands?: ICommand[];
110
  /** Syntax error/warning annotations */
111
  annotations?: Ace.Annotation[];
112
  /** Text highlighting markers */
113
  markers?: IMarker[];
114
}
115
```
116

117
### Usage Examples
118

119
**Basic Editor Setup:**
120

121
```typescript
122
import React, { useState } from "react";
123
import AceEditor from "react-ace";
124

125
// Import required ace modules
126
import "ace-builds/src-noconflict/mode-javascript";
127
import "ace-builds/src-noconflict/theme-github";
128

129
function CodeEditor() {
130
  const [code, setCode] = useState('function hello() {\n  console.log("Hello World!");\n}');
131

132
  return (
133
    <AceEditor
134
      mode="javascript"
135
      theme="github"
136
      onChange={setCode}
137
      value={code}
138
      name="basic-editor"
139
      width="100%"
140
      height="300px"
141
      fontSize={14}
142
      showPrintMargin={true}
143
      showGutter={true}
144
      highlightActiveLine={true}
145
    />
146
  );
147
}
148
```
149

150
**Advanced Editor with All Features:**
151

152
```typescript
153
import React, { useState, useRef } from "react";
154
import AceEditor from "react-ace";
155
import { IAceEditorProps, ICommand, IMarker } from "react-ace";
156

157
// Import various ace modules
158
import "ace-builds/src-noconflict/mode-typescript";
159
import "ace-builds/src-noconflict/theme-monokai";
160
import "ace-builds/src-noconflict/ext-language_tools";
161
import "ace-builds/src-noconflict/keybinding-vim";
162

163
function AdvancedEditor() {
164
  const [code, setCode] = useState('// TypeScript code here');
165
  const [annotations, setAnnotations] = useState([]);
166
  const editorRef = useRef(null);
167

168
  const customCommands: ICommand[] = [
169
    {
170
      name: 'saveFile',
171
      bindKey: {win: 'Ctrl-S', mac: 'Command-S'},
172
      exec: (editor) => {
173
        // Custom save logic
174
        console.log('Saving file...');
175
      }
176
    }
177
  ];
178

179
  const markers: IMarker[] = [
180
    {
181
      startRow: 0,
182
      startCol: 0,
183
      endRow: 0,
184
      endCol: 10,
185
      className: 'highlight-marker',
186
      type: 'text'
187
    }
188
  ];
189

190
  const handleLoad = (editor) => {
191
    editorRef.current = editor;
192
    editor.focus();
193
  };
194

195
  const handleValidate = (annotations) => {
196
    setAnnotations(annotations);
197
  };
198

199
  return (
200
    <AceEditor
201
      mode="typescript"
202
      theme="monokai"
203
      onChange={setCode}
204
      value={code}
205
      name="advanced-editor"
206
      onLoad={handleLoad}
207
      onValidate={handleValidate}
208
      width="100%"
209
      height="600px"
210
      fontSize={16}
211
      lineHeight={19}
212
      showPrintMargin={true}
213
      showGutter={true}
214
      highlightActiveLine={true}
215
      enableBasicAutocompletion={true}
216
      enableLiveAutocompletion={true}
217
      enableSnippets={true}
218
      keyboardHandler="vim"
219
      commands={customCommands}
220
      annotations={annotations}
221
      markers={markers}
222
      setOptions={{
223
        enableBasicAutocompletion: true,
224
        enableLiveAutocompletion: true,
225
        enableSnippets: true,
226
        showLineNumbers: true,
227
        tabSize: 2,
228
        wrap: true,
229
        fontSize: 16
230
      }}
231
      editorProps={{
232
        $blockScrolling: true
233
      }}
234
    />
235
  );
236
}
237
```
238

239
**Read-Only Display:**
240

241
```typescript
242
import React from "react";
243
import AceEditor from "react-ace";
244

245
import "ace-builds/src-noconflict/mode-json";
246
import "ace-builds/src-noconflict/theme-github";
247

248
function ReadOnlyDisplay({ jsonData }) {
249
  return (
250
    <AceEditor
251
      mode="json"
252
      theme="github"
253
      value={JSON.stringify(jsonData, null, 2)}
254
      name="readonly-display"
255
      readOnly={true}
256
      width="100%"
257
      height="400px"
258
      showGutter={false}
259
      highlightActiveLine={false}
260
      setOptions={{
261
        showLineNumbers: false,
262
        showFoldWidgets: false
263
      }}
264
    />
265
  );
266
}
267
```
268

269
### Editor Configuration
270

271
The editor accepts extensive configuration through the `setOptions` prop and individual props:
272

273
```typescript { .api }
274
interface IAceOptions {
275
  /** Text selection style */
276
  selectionStyle?: "line" | "text";
277
  /** Highlight the currently active line */
278
  highlightActiveLine?: boolean;
279
  /** Highlight selected word occurrences */
280
  highlightSelectedWord?: boolean;
281
  /** Make editor read-only */
282
  readOnly?: boolean;
283
  /** Cursor appearance style */
284
  cursorStyle?: "ace" | "slim" | "smooth" | "wide";
285
  /** How to merge undo operations */
286
  mergeUndoDeltas?: false | true | "always";
287
  /** Enable automatic bracket matching */
288
  behavioursEnabled?: boolean;
289
  /** Enable wrap behaviors */
290
  wrapBehavioursEnabled?: boolean;
291
  /** Auto-scroll editor into view when inside scrollable page */
292
  autoScrollEditorIntoView?: boolean;
293
  /** Always show horizontal scrollbar */
294
  hScrollBarAlwaysVisible?: boolean;
295
  /** Always show vertical scrollbar */
296
  vScrollBarAlwaysVisible?: boolean;
297
  /** Highlight gutter line */
298
  highlightGutterLine?: boolean;
299
  /** Animate scrolling */
300
  animatedScroll?: boolean;
301
  /** Show invisible characters */
302
  showInvisibles?: string | boolean;
303
  /** Show print margin line */
304
  showPrintMargin?: boolean;
305
  /** Print margin column position */
306
  printMarginColumn?: number;
307
  /** Print margin setting */
308
  printMargin?: boolean | number;
309
  /** Fade fold widgets when not hovered */
310
  fadeFoldWidgets?: boolean;
311
  /** Show code folding widgets */
312
  showFoldWidgets?: boolean;
313
  /** Show line numbers */
314
  showLineNumbers?: boolean;
315
  /** Show editor gutter */
316
  showGutter?: boolean;
317
  /** Display indent guides */
318
  displayIndentGuides?: boolean;
319
  /** Font size (number or CSS string) */
320
  fontSize?: number | string;
321
  /** Font family CSS property */
322
  fontFamily?: string;
323
  /** Maximum lines to display */
324
  maxLines?: number;
325
  /** Minimum lines to display */
326
  minLines?: number;
327
  /** Allow scrolling past end of document */
328
  scrollPastEnd?: boolean;
329
  /** Use fixed width for gutter */
330
  fixedWidthGutter?: boolean;
331
  /** Theme path (e.g., "ace/theme/monokai") */
332
  theme?: string;
333
  /** Scroll speed multiplier */
334
  scrollSpeed?: number;
335
  /** Drag start delay in milliseconds */
336
  dragDelay?: number;
337
  /** Enable drag and drop */
338
  dragEnabled?: boolean;
339
  /** Focus timeout */
340
  focusTimout?: number;
341
  /** Tooltips follow mouse cursor */
342
  tooltipFollowsMouse?: boolean;
343
  /** First line number */
344
  firstLineNumber?: number;
345
  /** Overwrite mode */
346
  overwrite?: boolean;
347
  /** New line mode */
348
  newLineMode?: "auto" | "unix" | "windows";
349
  /** Use web worker for syntax checking */
350
  useWorker?: boolean;
351
  /** Use soft tabs (spaces) */
352
  useSoftTabs?: boolean;
353
  /** Tab size in spaces */
354
  tabSize?: number;
355
  /** Enable line wrapping */
356
  wrap?: boolean;
357
  /** Code folding style */
358
  foldStyle?: "markbegin" | "markbeginend" | "manual";
359
  /** Language mode path (e.g., "ace/mode/javascript") */
360
  mode?: string;
361
  /** Enable multi-selection */
362
  enableMultiselect?: boolean;
363
  /** Enable Emmet abbreviations */
364
  enableEmmet?: boolean;
365
  /** Enable basic autocompletion */
366
  enableBasicAutocompletion?: boolean;
367
  /** Enable live autocompletion */
368
  enableLiveAutocompletion?: boolean;
369
  /** Enable code snippets */
370
  enableSnippets?: boolean;
371
  /** Enable spell checking */
372
  spellcheck?: boolean;
373
  /** Use elastic tabstops */
374
  useElasticTabstops?: boolean;
375
}
376
```
377

378
### Event Handling
379

380
All editor events provide detailed information about the change:
381

382
```typescript { .api }
383
/** Called when editor content changes */
384
onChange?: (value: string, event?: {
385
  start: { row: number; column: number };
386
  end: { row: number; column: number };
387
  action: "insert" | "remove";
388
  lines: string[];
389
}) => void;
390

391
/** Called when text selection changes */
392
onSelectionChange?: (selection: {
393
  start: { row: number; column: number };
394
  end: { row: number; column: number };
395
}, event?: any) => void;
396

397
/** Called when cursor position changes */
398
onCursorChange?: (selection: {
399
  start: { row: number; column: number };
400
  end: { row: number; column: number };
401
}, event?: any) => void;
402
```
403

404
### Custom Commands
405

406
Add custom keyboard shortcuts and commands:
407

408
```typescript { .api }
409
interface ICommand {
410
  /** Unique command name */
411
  name: string;
412
  /** Key binding configuration */
413
  bindKey: ICommandBindKey;
414
  /** Command execution function or string */
415
  exec: string | ((editor: Ace.Editor, args?: any) => any);
416
  /** Whether command works in read-only mode */
417
  readOnly?: boolean;
418
}
419

420
interface ICommandBindKey {
421
  /** Windows/Linux key combination */
422
  win: string;
423
  /** macOS key combination */
424
  mac: string;
425
}
426
```
427

428
### Annotations and Markers
429

430
Display syntax errors, warnings, and highlight text regions:
431

432
```typescript { .api }
433
interface IAnnotation {
434
  /** Line number (0-based) */
435
  row: number;
436
  /** Column number (0-based) */
437
  column: number;
438
  /** Annotation message text */
439
  text: string;
440
  /** Annotation severity level */
441
  type: "error" | "info" | "warning";
442
}
443

444
interface IMarker {
445
  /** Start line (0-based) */
446
  startRow: number;
447
  /** Start column (0-based) */
448
  startCol: number;
449
  /** End line (0-based) */
450
  endRow: number;
451
  /** End column (0-based) */
452
  endCol: number;
453
  /** CSS class for styling */
454
  className: string;
455
  /** Marker type */
456
  type: "fullLine" | "screenLine" | "text" | Ace.MarkerRenderer;
457
  /** Render marker in front of text */
458
  inFront?: boolean;
459
}
460
```