0
# Selection System
1

2
Advanced selection management with Range and Node selections, providing precise control over user selection and programmatic selection manipulation. Lexical's selection system is designed to handle complex text editing scenarios while maintaining immutable state principles.
3

4
## Capabilities
5

6
### Base Selection
7

8
Abstract base class for all selection types in Lexical.
9

10
```typescript { .api }
11
/**
12
 * Abstract base class for selections
13
 */
14
abstract class BaseSelection {
15
  /** Clone this selection */
16
  abstract clone(): BaseSelection;
17
  /** Extract selected content */
18
  abstract extract(): Array<LexicalNode>;
19
  /** Insert nodes at selection */
20
  abstract insertNodes(nodes: Array<LexicalNode>): void;
21
  /** Insert text at selection */
22
  abstract insertText(text: string): void;
23
  /** Check if selection is collapsed */
24
  abstract isCollapsed(): boolean;
25
  /** Get nodes contained in selection */
26
  abstract getNodes(): Array<LexicalNode>;
27
  /** Get text content of selection */
28
  abstract getTextContent(): string;
29
}
30
```
31

32
### Range Selection
33

34
Selection representing a text range with anchor and focus points.
35

36
```typescript { .api }
37
/**
38
 * Selection for text ranges with anchor and focus points
39
 */
40
class RangeSelection extends BaseSelection {
41
  /** Anchor point of the selection */
42
  anchor: Point;
43
  /** Focus point of the selection */
44
  focus: Point;
45
  /** Format applied to selection */
46
  format: number;
47
  /** Style applied to selection */
48
  style: string;
49

50
  /** Clone this range selection */
51
  clone(): RangeSelection;
52
  /** Get text content of selection */
53
  getTextContent(): string;
54
  /** Insert text at selection */
55
  insertText(text: string): void;
56
  /** Insert nodes at selection */
57
  insertNodes(nodes: Array<LexicalNode>): void;
58
  /** Insert paragraph at selection */
59
  insertParagraph(): void;
60
  /** Insert line break at selection */
61
  insertLineBreak(selectStart?: boolean): void;
62
  /** Remove selected content */
63
  removeText(): void;
64
  /** Format selected text */
65
  formatText(formatType: TextFormatType): void;
66
  /** Check if selection is backward (focus before anchor) */
67
  isBackward(): boolean;
68
  /** Check if selection is collapsed */
69
  isCollapsed(): boolean;
70
  /** Modify selection range */
71
  modify(alter: 'move' | 'extend', direction: 'backward' | 'forward', granularity: 'character' | 'word' | 'lineboundary'): void;
72
  /** Delete character in direction */
73
  deleteCharacter(isBackward: boolean): void;
74
  /** Delete word in direction */
75
  deleteWord(isBackward: boolean): void;
76
  /** Delete line in direction */
77
  deleteLine(isBackward: boolean): void;
78
  /** Get selected nodes */
79
  getNodes(): Array<LexicalNode>;
80
  /** Extract selected content */
81
  extract(): Array<LexicalNode>;
82
  /** Apply style to selection */
83
  applyStyle(style: string): void;
84
  /** Check if selection has format */
85
  hasFormat(type: TextFormatType): boolean;
86
  /** Toggle format on selection */
87
  toggleFormat(type: TextFormatType): void;
88
}
89

90
/**
91
 * Create a new RangeSelection
92
 * @param anchorKey - Key of anchor node
93
 * @param anchorOffset - Offset in anchor node
94
 * @param focusKey - Key of focus node
95
 * @param focusOffset - Offset in focus node
96
 * @param format - Text format bitmask
97
 * @param style - Text style string
98
 * @returns New RangeSelection instance
99
 */
100
function $createRangeSelection(): RangeSelection;
101

102
/**
103
 * Create RangeSelection from DOM selection
104
 * @param domSelection - DOM Selection object
105
 * @param editor - Lexical editor instance
106
 * @param anchorDOM - Anchor DOM node
107
 * @param anchorOffset - Anchor offset
108
 * @param focusDOM - Focus DOM node
109
 * @param focusOffset - Focus offset
110
 * @returns New RangeSelection instance
111
 */
112
function $createRangeSelectionFromDom(
113
  domSelection: Selection,
114
  editor: LexicalEditor,
115
  anchorDOM: Node,
116
  anchorOffset: number,
117
  focusDOM: Node,
118
  focusOffset: number
119
): RangeSelection | null;
120

121
/**
122
 * Check if selection is a RangeSelection
123
 * @param selection - Selection to check
124
 * @returns True if selection is RangeSelection
125
 */
126
function $isRangeSelection(selection: BaseSelection | null | undefined): selection is RangeSelection;
127
```
128

129
### Node Selection
130

131
Selection representing selected nodes (not text ranges).
132

133
```typescript { .api }
134
/**
135
 * Selection for entire nodes
136
 */
137
class NodeSelection extends BaseSelection {
138
  /** Set of selected node keys */
139
  _nodes: Set<NodeKey>;
140

141
  /** Clone this node selection */
142
  clone(): NodeSelection;
143
  /** Get selected nodes */
144
  getNodes(): Array<LexicalNode>;
145
  /** Get text content of selected nodes */
146
  getTextContent(): string;
147
  /** Insert text (replaces selected nodes) */
148
  insertText(text: string): void;
149
  /** Insert nodes (replaces selected nodes) */
150
  insertNodes(nodes: Array<LexicalNode>): void;
151
  /** Check if selection is collapsed (empty) */
152
  isCollapsed(): boolean;
153
  /** Extract selected nodes */
154
  extract(): Array<LexicalNode>;
155
  /** Add node to selection */
156
  add(key: NodeKey): void;
157
  /** Remove node from selection */
158
  delete(key: NodeKey): void;
159
  /** Clear all selected nodes */
160
  clear(): void;
161
  /** Check if node is selected */
162
  has(key: NodeKey): boolean;
163
}
164

165
/**
166
 * Create a new NodeSelection
167
 * @returns New NodeSelection instance
168
 */
169
function $createNodeSelection(): NodeSelection;
170

171
/**
172
 * Check if selection is a NodeSelection
173
 * @param selection - Selection to check
174
 * @returns True if selection is NodeSelection
175
 */
176
function $isNodeSelection(selection: BaseSelection | null | undefined): selection is NodeSelection;
177
```
178

179
### Point System
180

181
Point objects represent specific positions within the editor.
182

183
```typescript { .api }
184
/**
185
 * Represents a point in selection
186
 */
187
class Point {
188
  /** Key of the node containing this point */
189
  key: NodeKey;
190
  /** Offset within the node */
191
  offset: number;
192
  /** Type of point */
193
  type: 'text' | 'element';
194

195
  /** Clone this point */
196
  clone(): Point;
197
  /** Check if points are equal */
198
  is(point: Point): boolean;
199
  /** Check if this point is before another */
200
  isBefore(point: Point): boolean;
201
  /** Get the node containing this point */
202
  getNode(): LexicalNode;
203
  /** Set point to new position */
204
  set(key: NodeKey, offset: number, type: 'text' | 'element'): void;
205
}
206

207
/**
208
 * Create a new Point
209
 * @param key - Node key
210
 * @param offset - Offset within node
211
 * @param type - Point type
212
 * @returns New Point instance
213
 */
214
function $createPoint(key: NodeKey, offset: number, type: 'text' | 'element'): Point;
215

216
// Point type interfaces
217
interface TextPointType {
218
  key: NodeKey;
219
  offset: number;
220
  type: 'text';
221
}
222

223
interface ElementPointType {
224
  key: NodeKey;
225
  offset: number;
226
  type: 'element';
227
}
228

229
type PointType = Point;
230
```
231

232
### Selection Utilities
233

234
Functions for working with selections and retrieving selection information.
235

236
```typescript { .api }
237
/**
238
 * Get the current editor selection
239
 * @returns Current selection or null if none
240
 */
241
function $getSelection(): BaseSelection | null;
242

243
/**
244
 * Set the editor selection
245
 * @param selection - Selection to set
246
 */
247
function $setSelection(selection: BaseSelection | null): void;
248

249
/**
250
 * Get previous selection state
251
 * @returns Previous selection or null
252
 */
253
function $getPreviousSelection(): BaseSelection | null;
254

255
/**
256
 * Get text content from selection or node
257
 * @returns Text content string
258
 */
259
function $getTextContent(): string;
260

261
/**
262
 * Insert nodes at current selection
263
 * @param nodes - Nodes to insert
264
 */
265
function $insertNodes(nodes: Array<LexicalNode>): void;
266

267
/**
268
 * Check if node is a block element
269
 * @param node - Node to check
270
 * @returns True if node is block element
271
 */
272
function $isBlockElementNode(node: ElementNode): boolean;
273

274
/**
275
 * Get character offsets for selection
276
 * @param selection - Selection to analyze
277
 * @returns Object with anchor and focus character offsets
278
 */
279
function $getCharacterOffsets(selection: RangeSelection): {
280
  anchor: number;
281
  focus: number;
282
};
283
```
284

285
**Usage Examples:**
286

287
```typescript
288
import { 
289
  $getSelection, 
290
  $setSelection,
291
  $createRangeSelection,
292
  $createNodeSelection,
293
  $isRangeSelection,
294
  $isNodeSelection 
295
} from "lexical";
296

297
// Get current selection
298
const selection = $getSelection();
299

300
if ($isRangeSelection(selection)) {
301
  // Work with range selection
302
  const text = selection.getTextContent();
303
  selection.insertText('New text');
304
  selection.formatText('bold');
305
  
306
  // Check selection properties
307
  if (selection.isCollapsed()) {
308
    console.log('Selection is collapsed (cursor)');
309
  }
310
  
311
  if (selection.isBackward()) {
312
    console.log('Selection is backward');
313
  }
314
  
315
  // Modify selection
316
  selection.modify('extend', 'forward', 'word');
317
}
318

319
if ($isNodeSelection(selection)) {
320
  // Work with node selection
321
  const nodes = selection.getNodes();
322
  selection.insertText('Replace selected nodes');
323
  
324
  // Manipulate selected nodes
325
  selection.add('some-node-key');
326
  selection.delete('other-node-key');
327
  selection.clear();
328
}
329

330
// Create new selections
331
const rangeSelection = $createRangeSelection();
332
const nodeSelection = $createNodeSelection();
333

334
// Set new selection
335
$setSelection(rangeSelection);
336

337
// Create point
338
const point = $createPoint('node-key', 5, 'text');
339

340
// Work with selection utilities
341
const textContent = $getTextContent();
342
const characterOffsets = $getCharacterOffsets(selection);
343
```
344

345
### Selection State Management
346

347
Additional utilities for managing selection state and behavior.
348

349
```typescript { .api }
350
/**
351
 * Normalize selection to valid state
352
 * @param selection - Selection to normalize
353
 * @returns Normalized selection
354
 */
355
function $normalizeSelection__EXPERIMENTAL(selection: BaseSelection): BaseSelection;
356

357
/**
358
 * Check if selection is captured in decorator input
359
 * @param selection - Selection to check
360
 * @returns True if in decorator input
361
 */
362
function isSelectionCapturedInDecoratorInput(selection: BaseSelection): boolean;
363

364
/**
365
 * Check if selection is within editor
366
 * @param editor - Editor instance
367
 * @param selection - Selection to check
368
 * @returns True if selection is within editor
369
 */
370
function isSelectionWithinEditor(editor: LexicalEditor, selection: BaseSelection): boolean;
371
```
372

373
The selection system provides comprehensive tools for handling both simple text selections and complex multi-node selections. It integrates seamlessly with the command system and supports all standard text editing operations while maintaining the immutable state model that Lexical is built upon.