0
# Command System
1

2
Comprehensive command system for handling user interactions, keyboard events, and programmatic editor operations. Lexical's command system provides a powerful event-driven architecture that allows for extensible and predictable editor behavior.
3

4
## Capabilities
5

6
### Command Creation and Types
7

8
Core utilities for creating and working with typed commands.
9

10
```typescript { .api }
11
/**
12
 * Create a typed command
13
 * @param type - Optional command type identifier
14
 * @returns Typed command instance
15
 */
16
function createCommand<T = void>(type?: string): LexicalCommand<T>;
17

18
/**
19
 * Type representing a Lexical command
20
 */
21
interface LexicalCommand<T = void> {
22
  type?: string;
23
}
24

25
/**
26
 * Extract payload type from command
27
 */
28
type CommandPayloadType<TCommand extends LexicalCommand<unknown>> = 
29
  TCommand extends LexicalCommand<infer TPayload> ? TPayload : never;
30

31
/**
32
 * Command listener function type
33
 */
34
type CommandListener<P> = (payload: P, editor: LexicalEditor) => boolean;
35

36
/**
37
 * Command listener priority levels
38
 */
39
type CommandListenerPriority = 0 | 1 | 2 | 3 | 4;
40
```
41

42
### Text Input Commands
43

44
Commands for handling text input and modification.
45

46
```typescript { .api }
47
/** Command for controlled text insertion */
48
const CONTROLLED_TEXT_INSERTION_COMMAND: LexicalCommand<string | InputEvent>;
49

50
/** Command for inserting line breaks */
51
const INSERT_LINE_BREAK_COMMAND: LexicalCommand<boolean>;
52

53
/** Command for inserting paragraphs */
54
const INSERT_PARAGRAPH_COMMAND: LexicalCommand<void>;
55

56
/** Command for inserting tabs */
57
const INSERT_TAB_COMMAND: LexicalCommand<void>;
58

59
/** Command for removing text */
60
const REMOVE_TEXT_COMMAND: LexicalCommand<InputEvent | null>;
61

62
/** Command for deleting characters */
63
const DELETE_CHARACTER_COMMAND: LexicalCommand<boolean>;
64

65
/** Command for deleting words */
66
const DELETE_WORD_COMMAND: LexicalCommand<boolean>;
67

68
/** Command for deleting lines */
69
const DELETE_LINE_COMMAND: LexicalCommand<boolean>;
70
```
71

72
### Text Formatting Commands
73

74
Commands for applying text formatting and styles.
75

76
```typescript { .api }
77
/** Command for formatting text */
78
const FORMAT_TEXT_COMMAND: LexicalCommand<TextFormatType>;
79

80
/** Command for formatting elements */
81
const FORMAT_ELEMENT_COMMAND: LexicalCommand<ElementFormatType>;
82

83
/** Command for indenting content */
84
const INDENT_CONTENT_COMMAND: LexicalCommand<void>;
85

86
/** Command for outdenting content */
87
const OUTDENT_CONTENT_COMMAND: LexicalCommand<void>;
88

89
type TextFormatType = 'bold' | 'italic' | 'strikethrough' | 'underline' | 'code' | 'subscript' | 'superscript' | 'highlight';
90
type ElementFormatType = 'left' | 'center' | 'right' | 'justify' | 'start' | 'end';
91
```
92

93
### Keyboard Event Commands
94

95
Commands corresponding to keyboard interactions.
96

97
```typescript { .api }
98
/** Arrow key commands */
99
const KEY_ARROW_DOWN_COMMAND: LexicalCommand<KeyboardEvent>;
100
const KEY_ARROW_LEFT_COMMAND: LexicalCommand<KeyboardEvent>;
101
const KEY_ARROW_RIGHT_COMMAND: LexicalCommand<KeyboardEvent>;
102
const KEY_ARROW_UP_COMMAND: LexicalCommand<KeyboardEvent>;
103

104
/** Special key commands */
105
const KEY_BACKSPACE_COMMAND: LexicalCommand<KeyboardEvent>;
106
const KEY_DELETE_COMMAND: LexicalCommand<KeyboardEvent>;
107
const KEY_ENTER_COMMAND: LexicalCommand<KeyboardEvent>;
108
const KEY_ESCAPE_COMMAND: LexicalCommand<KeyboardEvent>;
109
const KEY_SPACE_COMMAND: LexicalCommand<KeyboardEvent>;
110
const KEY_TAB_COMMAND: LexicalCommand<KeyboardEvent>;
111

112
/** Generic key event commands */
113
const KEY_DOWN_COMMAND: LexicalCommand<KeyboardEvent>;
114
const KEY_MODIFIER_COMMAND: LexicalCommand<KeyboardEvent>;
115
```
116

117
### Mouse and Touch Commands
118

119
Commands for handling mouse and touch interactions.
120

121
```typescript { .api }
122
/** Command for click events */
123
const CLICK_COMMAND: LexicalCommand<MouseEvent>;
124

125
/** Command for focus events */
126
const FOCUS_COMMAND: LexicalCommand<FocusEvent>;
127

128
/** Command for blur events */
129
const BLUR_COMMAND: LexicalCommand<FocusEvent>;
130

131
/** Drag and drop commands */
132
const DRAGSTART_COMMAND: LexicalCommand<DragEvent>;
133
const DRAGOVER_COMMAND: LexicalCommand<DragEvent>;
134
const DRAGEND_COMMAND: LexicalCommand<DragEvent>;
135
const DROP_COMMAND: LexicalCommand<DragEvent>;
136
```
137

138
### Clipboard Commands
139

140
Commands for clipboard operations.
141

142
```typescript { .api }
143
/** Command for copy operations */
144
const COPY_COMMAND: LexicalCommand<ClipboardEvent | KeyboardEvent>;
145

146
/** Command for cut operations */
147
const CUT_COMMAND: LexicalCommand<ClipboardEvent | KeyboardEvent>;
148

149
/** Command for paste operations */
150
const PASTE_COMMAND: LexicalCommand<ClipboardEvent>;
151

152
/** Type for paste command payloads */
153
type PasteCommandType = ClipboardEvent | InputEvent | KeyboardEvent;
154

155
/** Command for inserting clipboard nodes into selection */
156
const SELECTION_INSERT_CLIPBOARD_NODES_COMMAND: LexicalCommand<{
157
  nodes: Array<LexicalNode>;
158
  selection: BaseSelection;
159
}>;
160
```
161

162
### History Commands
163

164
Commands for undo/redo functionality.
165

166
```typescript { .api }
167
/** Command for undo operations */
168
const UNDO_COMMAND: LexicalCommand<void>;
169

170
/** Command for redo operations */
171
const REDO_COMMAND: LexicalCommand<void>;
172

173
/** Command to check if undo is available */
174
const CAN_UNDO_COMMAND: LexicalCommand<boolean>;
175

176
/** Command to check if redo is available */
177
const CAN_REDO_COMMAND: LexicalCommand<boolean>;
178

179
/** Command to clear editor history */
180
const CLEAR_HISTORY_COMMAND: LexicalCommand<void>;
181
```
182

183
### Selection Commands
184

185
Commands for selection management and changes.
186

187
```typescript { .api }
188
/** Command fired when selection changes */
189
const SELECTION_CHANGE_COMMAND: LexicalCommand<void>;
190

191
/** Command for selecting all content */
192
const SELECT_ALL_COMMAND: LexicalCommand<KeyboardEvent>;
193

194
/** Movement modifiers for selection commands */
195
const MOVE_TO_END: string;
196
const MOVE_TO_START: string;
197
```
198

199
### Editor State Commands
200

201
Commands for managing overall editor state.
202

203
```typescript { .api }
204
/** Command to clear all editor content */
205
const CLEAR_EDITOR_COMMAND: LexicalCommand<void>;
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { 
212
  createCommand, 
213
  FORMAT_TEXT_COMMAND, 
214
  INSERT_PARAGRAPH_COMMAND,
215
  UNDO_COMMAND,
216
  SELECTION_CHANGE_COMMAND,
217
  COMMAND_PRIORITY_HIGH 
218
} from "lexical";
219

220
// Create custom command
221
const CUSTOM_COMMAND = createCommand<{ data: string }>('CUSTOM_COMMAND');
222

223
// Register command listener
224
const removeListener = editor.registerCommand(
225
  FORMAT_TEXT_COMMAND,
226
  (formatType) => {
227
    console.log('Formatting text:', formatType);
228
    return false; // Allow other listeners to handle
229
  },
230
  COMMAND_PRIORITY_HIGH
231
);
232

233
// Register selection change listener
234
editor.registerCommand(
235
  SELECTION_CHANGE_COMMAND,
236
  () => {
237
    const selection = $getSelection();
238
    console.log('Selection changed:', selection);
239
    return false;
240
  },
241
  COMMAND_PRIORITY_LOW
242
);
243

244
// Dispatch commands
245
editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'bold');
246
editor.dispatchCommand(INSERT_PARAGRAPH_COMMAND, undefined);
247
editor.dispatchCommand(UNDO_COMMAND, undefined);
248

249
// Dispatch custom command
250
editor.dispatchCommand(CUSTOM_COMMAND, { data: 'example' });
251

252
// Remove listener when done
253
removeListener();
254
```
255

256
### Command Listener Management
257

258
Methods for registering and managing command listeners on the editor.
259

260
```typescript { .api }
261
interface LexicalEditor {
262
  /**
263
   * Register a command listener
264
   * @param command - Command to listen for
265
   * @param listener - Function to handle command
266
   * @param priority - Execution priority (higher numbers execute first)
267
   * @returns Function to remove the listener
268
   */
269
  registerCommand<P>(
270
    command: LexicalCommand<P>,
271
    listener: CommandListener<P>,
272
    priority: CommandListenerPriority
273
  ): () => void;
274

275
  /**
276
   * Dispatch a command to all listeners
277
   * @param command - Command to dispatch
278
   * @param payload - Command payload
279
   * @returns True if any listener handled the command
280
   */
281
  dispatchCommand<P>(command: LexicalCommand<P>, payload: P): boolean;
282
}
283
```
284

285
### Advanced Command Patterns
286

287
Common patterns for working with commands in Lexical applications.
288

289
```typescript
290
// Priority-based command handling
291
editor.registerCommand(
292
  KEY_ENTER_COMMAND,
293
  (event) => {
294
    if (someSpecialCondition) {
295
      // Handle the command and prevent other handlers
296
      doSpecialAction();
297
      return true;
298
    }
299
    // Let other handlers process the command
300
    return false;
301
  },
302
  COMMAND_PRIORITY_HIGH
303
);
304

305
// Conditional command listening
306
editor.registerCommand(
307
  PASTE_COMMAND,
308
  (event) => {
309
    const selection = $getSelection();
310
    if ($isRangeSelection(selection)) {
311
      // Handle paste in range selection
312
      handlePaste(event, selection);
313
      return true;
314
    }
315
    return false;
316
  },
317
  COMMAND_PRIORITY_NORMAL
318
);
319

320
// Custom command with complex payload
321
const CUSTOM_FORMAT_COMMAND = createCommand<{
322
  format: TextFormatType;
323
  range?: { start: number; end: number };
324
  style?: string;
325
}>('CUSTOM_FORMAT');
326

327
editor.registerCommand(
328
  CUSTOM_FORMAT_COMMAND,
329
  ({ format, range, style }) => {
330
    // Apply custom formatting logic
331
    return true;
332
  },
333
  COMMAND_PRIORITY_NORMAL
334
);
335
```
336

337
The command system is the backbone of Lexical's event handling, providing a clean and extensible way to respond to user interactions and implement editor functionality. Commands can be intercepted, modified, or completely overridden by registering listeners with appropriate priorities.