0
# React-Ace
1

2
React-Ace is a comprehensive React component library that provides seamless integration with the Ace Editor (a high-performance code editor). It offers multiple editor components including the main AceEditor component, a Split Editor for side-by-side editing, and a Diff Editor for comparing code differences. The library supports extensive customization through themes, syntax highlighting modes, and editor options, while maintaining TypeScript support for type safety.
3

4
## Package Information
5

6
- **Package Name**: react-ace
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-ace ace-builds`
10

11
## Core Imports
12

13
```typescript
14
import AceEditor from "react-ace";
15
import { diff, split } from "react-ace";
16
```
17

18
For specific imports:
19

20
```typescript
21
import { 
22
  diff, 
23
  split,
24
  IAceEditorProps,
25
  IDiffEditorProps,
26
  IDiffEditorState,
27
  ISplitEditorProps,
28
  IAceOptions,
29
  IAnnotation,
30
  ICommand,
31
  ICommandBindKey,
32
  ICommandManager,
33
  IEditorProps,
34
  IMarker,
35
  getAceInstance,
36
  debounce,
37
  editorOptions,
38
  editorEvents,
39
  EditorOption,
40
  EditorEvent
41
} from "react-ace";
42
```
43

44
CommonJS:
45

46
```javascript
47
const AceEditor = require("react-ace").default;
48
const { 
49
  diff, 
50
  split, 
51
  getAceInstance, 
52
  debounce, 
53
  editorOptions, 
54
  editorEvents 
55
} = require("react-ace");
56
```
57

58
## Basic Usage
59

60
```typescript
61
import React from "react";
62
import AceEditor, { getAceInstance, debounce } from "react-ace";
63

64
// Import required ace-builds modules
65
import "ace-builds/src-noconflict/mode-javascript";
66
import "ace-builds/src-noconflict/theme-github";
67
import "ace-builds/src-noconflict/ext-language_tools";
68

69
function MyEditor() {
70
  const [code, setCode] = React.useState('console.log("Hello World");');
71

72
  // Use debounce utility for performance optimization
73
  const debouncedChange = React.useCallback(
74
    debounce((value: string) => {
75
      setCode(value);
76
      // Perform expensive operations like API calls here
77
    }, 500),
78
    []
79
  );
80

81
  // Access ACE instance for advanced configuration
82
  const handleLoad = (editor: any) => {
83
    const ace = getAceInstance();
84
    // Configure ACE editor with advanced options
85
    console.log("ACE instance loaded:", ace);
86
  };
87

88
  return (
89
    <AceEditor
90
      mode="javascript"
91
      theme="github"
92
      onChange={debouncedChange}
93
      onLoad={handleLoad}
94
      name="my-editor"
95
      value={code}
96
      width="100%"
97
      height="400px"
98
      fontSize={14}
99
      showPrintMargin={true}
100
      showGutter={true}
101
      highlightActiveLine={true}
102
      setOptions={{
103
        enableBasicAutocompletion: true,
104
        enableLiveAutocompletion: true,
105
        enableSnippets: true,
106
        showLineNumbers: true,
107
        tabSize: 2,
108
      }}
109
    />
110
  );
111
}
112
```
113

114
## Architecture
115

116
React-Ace is built around three main components:
117

118
- **AceEditor Component**: The primary code editor component with full Ace Editor integration
119
- **Split Editor**: Provides side-by-side editing capabilities with synchronized or independent panes
120
- **Diff Editor**: Specialized component for comparing and highlighting differences between two text sources
121
- **Type System**: Comprehensive TypeScript interfaces for all configuration options and event handlers
122
- **Ace Integration**: Direct integration with ace-builds package for core editor functionality
123

124
## Capabilities
125

126
### Main Code Editor
127

128
The primary AceEditor component provides comprehensive code editing functionality with syntax highlighting, themes, autocomplete, and extensive customization options.
129

130
```typescript { .api }
131
declare class ReactAce extends React.Component<IAceEditorProps> {}
132

133
interface IAceEditorProps {
134
  mode?: string | object;
135
  theme?: string;
136
  value?: string;
137
  defaultValue?: string;
138
  height?: string;
139
  width?: string;
140
  className?: string;
141
  fontSize?: number | string;
142
  lineHeight?: number | string;
143
  showGutter?: boolean;
144
  showPrintMargin?: boolean;
145
  highlightActiveLine?: boolean;
146
  focus?: boolean;
147
  cursorStart?: number;
148
  wrapEnabled?: boolean;
149
  readOnly?: boolean;
150
  minLines?: number;
151
  maxLines?: number;
152
  navigateToFileEnd?: boolean;
153
  debounceChangePeriod?: number;
154
  enableBasicAutocompletion?: boolean | string[];
155
  enableLiveAutocompletion?: boolean | string[];
156
  enableMobileMenu?: boolean;
157
  tabSize?: number;
158
  placeholder?: string;
159
  scrollMargin?: number[];
160
  enableSnippets?: boolean;
161
  onSelectionChange?: (value: any, event?: any) => void;
162
  onCursorChange?: (value: any, event?: any) => void;
163
  onInput?: (event?: any) => void;
164
  onLoad?: (editor: Ace.Editor) => void;
165
  onValidate?: (annotations: Ace.Annotation[]) => void;
166
  onBeforeLoad?: (ace: any) => void;
167
  onChange?: (value: string, event?: any) => void;
168
  onSelection?: (selectedText: string, event?: any) => void;
169
  onCopy?: (value: string) => void;
170
  onPaste?: (value: string) => void;
171
  onFocus?: (event: any, editor?: Ace.Editor) => void;
172
  onBlur?: (event: any, editor?: Ace.Editor) => void;
173
  onScroll?: (editor: IEditorProps) => void;
174
  editorProps?: IEditorProps;
175
  setOptions?: IAceOptions;
176
  keyboardHandler?: string;
177
  commands?: ICommand[];
178
  annotations?: Ace.Annotation[];
179
  markers?: IMarker[];
180
}
181
```
182

183
[Main Editor](./ace-editor.md)
184

185
### Split Screen Editor
186

187
Split screen editor component for side-by-side editing with multiple panes that can be synchronized or operate independently.
188

189
```typescript { .api }
190
declare class SplitComponent extends React.Component<ISplitEditorProps> {}
191

192
interface ISplitEditorProps {
193
  splits: number;
194
  orientation?: string;
195
  value?: string[];
196
  defaultValue?: string[];
197
  mode?: string;
198
  theme?: string;
199
  height?: string;
200
  width?: string;
201
  className?: string;
202
  fontSize?: number | string;
203
  showGutter?: boolean;
204
  showPrintMargin?: boolean;
205
  highlightActiveLine?: boolean;
206
  focus?: boolean;
207
  cursorStart?: number;
208
  wrapEnabled?: boolean;
209
  readOnly?: boolean;
210
  minLines?: number;
211
  maxLines?: number;
212
  onChange?: (value: string[], event?: any) => void;
213
  onLoad?: (editor: IEditorProps) => void;
214
  annotations?: IAnnotation[][];
215
  markers?: IMarker[][];
216
}
217
```
218

219
[Split Editor](./split-editor.md)
220

221
### Diff Editor
222

223
Diff editor component for comparing two pieces of text with visual highlighting of differences.
224

225
```typescript { .api }
226
declare class DiffComponent extends React.Component<IDiffEditorProps, IDiffEditorState> {}
227

228
interface IDiffEditorProps {
229
  value?: string[];
230
  height?: string;
231
  width?: string;
232
  className?: string;
233
  fontSize?: number;
234
  mode?: string;
235
  theme?: string;
236
  orientation?: string;
237
  splits?: number;
238
  readOnly?: boolean;
239
  showGutter?: boolean;
240
  showPrintMargin?: boolean;
241
  highlightActiveLine?: boolean;
242
  onChange?: (value: string[], event?: any) => void;
243
  onLoad?: (editor: IEditorProps) => void;
244
}
245

246
interface IDiffEditorState {
247
  value: string[];
248
}
249
```
250

251
[Diff Editor](./diff-editor.md)
252

253
### Utility Functions
254

255
Utility functions for working with ACE editor instances and performance optimization.
256

257
```typescript { .api }
258
/**
259
 * Gets the ACE instance with SSR (Server-Side Rendering) support
260
 * @returns ACE builds object for dynamic import and configuration
261
 */
262
function getAceInstance(): any;
263

264
/**
265
 * Utility function for debouncing function calls
266
 * @param fn - Function to debounce
267
 * @param delay - Delay in milliseconds
268
 * @returns Debounced function
269
 */
270
function debounce(fn: (...args: any[]) => void, delay: number): (...args: any[]) => void;
271
```
272

273
### Editor Configuration Constants
274

275
Pre-defined constants for editor options and events.
276

277
```typescript { .api }
278
/** Array of all supported ACE editor options */
279
const editorOptions: EditorOption[];
280

281
/** Array of all supported ACE editor events */
282
const editorEvents: EditorEvent[];
283

284
/** Union type of all supported editor options */
285
type EditorOption = "selectionStyle" | "highlightActiveLine" | "highlightSelectedWord" | 
286
  "readOnly" | "cursorStyle" | "mergeUndoDeltas" | "behavioursEnabled" | 
287
  "wrapBehavioursEnabled" | "autoScrollEditorIntoView" | "hScrollBarAlwaysVisible" |
288
  "vScrollBarAlwaysVisible" | "highlightGutterLine" | "animatedScroll" | 
289
  "showInvisibles" | "showPrintMargin" | "printMarginColumn" | "printMargin" |
290
  "fadeFoldWidgets" | "showFoldWidgets" | "showLineNumbers" | "showGutter" |
291
  "displayIndentGuides" | "fontSize" | "fontFamily" | "maxLines" | "minLines" |
292
  "scrollPastEnd" | "fixedWidthGutter" | "theme" | "scrollSpeed" | "dragDelay" |
293
  "dragEnabled" | "focusTimout" | "tooltipFollowsMouse" | "firstLineNumber" |
294
  "overwrite" | "newLineMode" | "useWorker" | "useSoftTabs" | "tabSize" |
295
  "wrap" | "foldStyle" | "mode" | "enableMultiselect" | "enableEmmet" |
296
  "enableBasicAutocompletion" | "enableLiveAutocompletion" | "enableSnippets" |
297
  "spellcheck" | "useElasticTabstops";
298

299
/** Union type of all supported editor events */
300
type EditorEvent = "onChange" | "onSelectionChange" | "onCursorChange" | "onInput" |
301
  "onLoad" | "onValidate" | "onBeforeLoad" | "onSelection" | "onCopy" | 
302
  "onPaste" | "onFocus" | "onBlur" | "onScroll";
303
```
304

305
## Core Types
306

307
*Note: The following interfaces reference types from the ace-builds package dependency.*
308

309
```typescript { .api }
310
interface IAceOptions {
311
  selectionStyle?: "line" | "text";
312
  highlightActiveLine?: boolean;
313
  highlightSelectedWord?: boolean;
314
  readOnly?: boolean;
315
  cursorStyle?: "ace" | "slim" | "smooth" | "wide";
316
  mergeUndoDeltas?: false | true | "always";
317
  behavioursEnabled?: boolean;
318
  wrapBehavioursEnabled?: boolean;
319
  autoScrollEditorIntoView?: boolean;
320
  hScrollBarAlwaysVisible?: boolean;
321
  vScrollBarAlwaysVisible?: boolean;
322
  highlightGutterLine?: boolean;
323
  animatedScroll?: boolean;
324
  showInvisibles?: string | boolean;
325
  showPrintMargin?: boolean;
326
  printMarginColumn?: number;
327
  printMargin?: boolean | number;
328
  fadeFoldWidgets?: boolean;
329
  showFoldWidgets?: boolean;
330
  showLineNumbers?: boolean;
331
  showGutter?: boolean;
332
  displayIndentGuides?: boolean;
333
  fontSize?: number | string;
334
  fontFamily?: string;
335
  maxLines?: number;
336
  minLines?: number;
337
  scrollPastEnd?: boolean;
338
  fixedWidthGutter?: boolean;
339
  theme?: string;
340
  scrollSpeed?: number;
341
  dragDelay?: number;
342
  dragEnabled?: boolean;
343
  focusTimout?: number;
344
  tooltipFollowsMouse?: boolean;
345
  firstLineNumber?: number;
346
  overwrite?: boolean;
347
  newLineMode?: "auto" | "unix" | "windows";
348
  useWorker?: boolean;
349
  useSoftTabs?: boolean;
350
  tabSize?: number;
351
  wrap?: boolean;
352
  foldStyle?: "markbegin" | "markbeginend" | "manual";
353
  mode?: string;
354
  enableMultiselect?: boolean;
355
  enableEmmet?: boolean;
356
  enableBasicAutocompletion?: boolean;
357
  enableLiveAutocompletion?: boolean;
358
  enableSnippets?: boolean;
359
  spellcheck?: boolean;
360
  useElasticTabstops?: boolean;
361
}
362

363
interface IAnnotation {
364
  row: number;
365
  column: number;
366
  text: string;
367
  type: "error" | "info" | "warning";
368
}
369

370
interface IMarker {
371
  startRow: number;
372
  startCol: number;
373
  endRow: number;
374
  endCol: number;
375
  className: string;
376
  type: "fullLine" | "screenLine" | "text" | Ace.MarkerRenderer;
377
  inFront?: boolean;
378
}
379

380
interface ICommand {
381
  name: string;
382
  bindKey: ICommandBindKey;
383
  exec: string | ((editor: Ace.Editor, args?: any) => any);
384
  readOnly?: boolean;
385
}
386

387
interface ICommandBindKey {
388
  win: string;
389
  mac: string;
390
}
391

392
interface ICommandManager {
393
  byName: any;
394
  commands: any;
395
  platform: string;
396
  addCommands(commands: any[]): void;
397
  addCommand(command: any): void;
398
  exec(name: string, editor: any, args: any): void;
399
  bindKey?(bindKey: any, command: any): void;
400
}
401

402
interface IEditorProps {
403
  [index: string]: any;
404
  $blockScrolling?: number | boolean;
405
  $blockSelectEnabled?: boolean;
406
  $enableBlockSelect?: boolean;
407
  $enableMultiselect?: boolean;
408
}
409
```