0
# Editor Management
1

2
Core editor functionality for creating, configuring, and managing Lexical editor instances. The editor serves as the central hub for all text editing operations and state management.
3

4
## Capabilities
5

6
### Editor Creation
7

8
Creates a new Lexical editor instance with optional configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Lexical editor instance
13
 * @param config - Optional configuration for the editor
14
 * @returns A new LexicalEditor instance
15
 */
16
function createEditor(config?: CreateEditorArgs): LexicalEditor;
17

18
interface CreateEditorArgs {
19
  /** Unique namespace for the editor instance */
20
  namespace?: string;
21
  /** Theme configuration for styling editor content */
22
  theme?: EditorThemeClasses;
23
  /** Error handler for editor errors */
24
  onError?: (error: Error) => void;
25
  /** Array of node types and replacements to register */
26
  nodes?: ReadonlyArray<Klass<LexicalNode> | LexicalNodeReplacement>;
27
  /** Initial editor state */
28
  editorState?: EditorState;
29
  /** HTML import/export configuration */
30
  html?: HTMLConfig;
31
  /** Whether the editor is initially editable */
32
  editable?: boolean;
33
}
34

35
interface EditorThemeClasses {
36
  /** CSS class for paragraph elements */
37
  paragraph?: string;
38
  /** CSS classes for text formatting */
39
  text?: {
40
    bold?: string;
41
    italic?: string;
42
    underline?: string;
43
    strikethrough?: string;
44
    underlineStrikethrough?: string;
45
    code?: string;
46
    highlight?: string;
47
    subscript?: string;
48
    superscript?: string;
49
  };
50
  /** CSS classes for other node types */
51
  [key: string]: string | Record<string, string> | undefined;
52
}
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
import { createEditor } from "lexical";
59

60
// Basic editor
61
const editor = createEditor();
62

63
// Editor with configuration
64
const editor = createEditor({
65
  namespace: 'MyEditor',
66
  theme: {
67
    paragraph: 'my-paragraph',
68
    text: {
69
      bold: 'my-bold',
70
      italic: 'my-italic',
71
    }
72
  },
73
  onError: (error) => {
74
    console.error('Editor error:', error);
75
  },
76
  editable: true,
77
});
78
```
79

80
### Editor Interface
81

82
The main editor interface providing methods for DOM binding, state management, and updates.
83

84
```typescript { .api }
85
interface LexicalEditor {
86
  /** Associate editor with a DOM element */
87
  setRootElement(rootElement: null | HTMLElement): void;
88
  /** Get the current immutable editor state */
89
  getEditorState(): EditorState;
90
  /** Set a new editor state */
91
  setEditorState(editorState: EditorState, options?: EditorSetOptions): void;
92
  /** Perform an update to the editor state */
93
  update(updateFn: () => void, options?: EditorUpdateOptions): void;
94
  /** Read from the current editor state */
95
  read<T>(readFn: () => T): T;
96
  /** Focus the editor */
97
  focus(callbackFn?: () => void): void;
98
  /** Blur the editor */
99
  blur(): void;
100
  /** Check if editor is editable */
101
  isEditable(): boolean;
102
  /** Set editor editable state */
103
  setEditable(editable: boolean): void;
104
  /** Parse a serialized editor state */
105
  parseEditorState(maybeStringifiedEditorState: string): EditorState;
106
  /** Register a command listener */
107
  registerCommand<P>(
108
    command: LexicalCommand<P>,
109
    listener: CommandListener<P>,
110
    priority: CommandListenerPriority
111
  ): () => void;
112
  /** Dispatch a command */
113
  dispatchCommand<P>(command: LexicalCommand<P>, payload: P): boolean;
114
  /** Register an update listener */
115
  registerUpdateListener(listener: UpdateListener): () => void;
116
  /** Register a root listener */
117
  registerRootListener(listener: RootListener): () => void;
118
  /** Register an editable listener */
119
  registerEditableListener(listener: EditableListener): () => void;
120
  /** Register a mutation listener */
121
  registerMutationListener(
122
    klass: Klass<LexicalNode>,
123
    listener: MutationListener
124
  ): () => void;
125
  /** Register a node transform */
126
  registerNodeTransform<T extends LexicalNode>(
127
    klass: Klass<T>,
128
    listener: Transform<T>
129
  ): () => void;
130
}
131

132
interface EditorSetOptions {
133
  /** Tag to identify the update */
134
  tag?: string;
135
}
136

137
interface EditorUpdateOptions {
138
  /** Tag to identify the update */
139
  tag?: string;
140
  /** Called when the update is applied to the DOM */
141
  onUpdate?: () => void;
142
  /** Skip collaboration for this update */
143
  skipTransforms?: boolean;
144
  /** Disable DOM updates */
145
  discrete?: boolean;
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { createEditor, $getRoot, $createParagraphNode, $createTextNode } from "lexical";
153

154
const editor = createEditor();
155
const contentEditable = document.getElementById('editor');
156

157
// Associate with DOM
158
editor.setRootElement(contentEditable);
159

160
// Perform an update
161
editor.update(() => {
162
  const root = $getRoot();
163
  const paragraph = $createParagraphNode();
164
  const text = $createTextNode('Hello, world!');
165
  
166
  paragraph.append(text);
167
  root.append(paragraph);
168
});
169

170
// Read from editor state
171
const textContent = editor.read(() => {
172
  const root = $getRoot();
173
  return root.getTextContent();
174
});
175

176
// Listen for updates
177
const removeUpdateListener = editor.registerUpdateListener(({editorState}) => {
178
  console.log('Editor updated');
179
  editorState.read(() => {
180
    // Process the new state
181
  });
182
});
183

184
// Focus the editor
185
editor.focus();
186

187
// Make editor read-only
188
editor.setEditable(false);
189
```
190

191
### Command Priority Constants
192

193
Priority levels for command listeners determining execution order.
194

195
```typescript { .api }
196
/** Editor priority - core editor functionality (lowest priority) */
197
const COMMAND_PRIORITY_EDITOR: 0;
198
/** Low priority - basic plugin functionality */
199
const COMMAND_PRIORITY_LOW: 1;
200
/** Normal priority - default for most listeners */
201
const COMMAND_PRIORITY_NORMAL: 2;
202
/** High priority - for important plugins */
203
const COMMAND_PRIORITY_HIGH: 3;
204
/** Critical priority - highest execution priority */
205
const COMMAND_PRIORITY_CRITICAL: 4;
206

207
type CommandListenerPriority = 0 | 1 | 2 | 3 | 4;
208
```
209

210
### Listener Types
211

212
Type definitions for various editor event listeners.
213

214
```typescript { .api }
215
/**
216
 * Listener for editor updates
217
 * @param payload - Update information including new editor state
218
 */
219
type UpdateListener = (payload: {
220
  editorState: EditorState;
221
  prevEditorState: EditorState;
222
  tags: Set<string>;
223
}) => void;
224

225
/**
226
 * Listener for root element changes
227
 * @param rootElement - New root element (null if removed)
228
 * @param prevRootElement - Previous root element
229
 */
230
type RootListener = (
231
  rootElement: null | HTMLElement,
232
  prevRootElement: null | HTMLElement
233
) => void;
234

235
/**
236
 * Listener for editable state changes
237
 * @param editable - New editable state
238
 */
239
type EditableListener = (editable: boolean) => void;
240

241
/**
242
 * Listener for node mutations
243
 * @param mutations - Map of node keys to mutation types
244
 * @param payload - Update payload with editor states
245
 */
246
type MutationListener = (
247
  mutations: Map<NodeKey, NodeMutation>,
248
  payload: {
249
    prevEditorState: EditorState;
250
    updateTags: Set<string>;
251
  }
252
) => void;
253

254
type NodeMutation = 'created' | 'updated' | 'destroyed';
255

256
/**
257
 * Transform function for node changes
258
 * @param node - The node being transformed
259
 */
260
type Transform<T extends LexicalNode> = (node: T) => void;
261
```