0
# History Plugin
1

2
The `withHistory` plugin is the core function that transforms a standard Slate editor into a history-enabled editor, adding comprehensive undo/redo functionality through operation tracking and intelligent batch management.
3

4
## Capabilities
5

6
### withHistory Plugin
7

8
Creates a history-enabled editor by adding undo/redo functionality to any Slate editor.
9

10
```typescript { .api }
11
/**
12
 * Transforms a Slate editor into a history-enabled editor with undo/redo capabilities
13
 * @param editor - Any Slate editor instance
14
 * @returns Editor with HistoryEditor interface and history functionality
15
 */
16
function withHistory<T extends Editor>(editor: T): T & HistoryEditor;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { createEditor } from "slate";
23
import { withHistory } from "slate-history";
24

25
// Basic usage
26
const editor = withHistory(createEditor());
27

28
// With React
29
import { withReact } from "slate-react";
30
const reactEditor = withReact(withHistory(createEditor()));
31

32
// The editor now has history functionality
33
editor.undo(); // Undo last operation batch
34
editor.redo(); // Redo last undone batch
35

36
// Access history state
37
console.log(editor.history.undos.length); // Number of undo operations
38
console.log(editor.history.redos.length); // Number of redo operations
39
```
40

41
### Plugin Behavior
42

43
The `withHistory` plugin enhances the editor with the following behavior:
44

45
**Operation Tracking:**
46
- Intercepts all operations applied to the editor
47
- Groups related operations into batches for logical undo/redo units
48
- Maintains separate undo and redo stacks
49

50
**Intelligent Batching:**
51
- Automatically merges consecutive text insertions at the same location
52
- Automatically merges consecutive text deletions at the same location
53
- Preserves selection state before each operation batch
54

55
**History Management:**
56
- Maintains maximum of 100 operation batches in undo stack
57
- Clears redo stack when new operations are applied
58
- Handles operation saving and merging based on editor state flags
59

60
**Added Methods:**
61
- `undo()`: Reverts the last batch of operations
62
- `redo()`: Reapplies the last undone batch of operations
63
- `writeHistory()`: Manually adds operation batches to history stacks
64

65
**Added Properties:**
66
- `history`: Contains the undo and redo operation stacks
67

68
## Operation Merging Logic
69

70
The plugin includes intelligent operation merging to create logical undo/redo units:
71

72
**Text Insertion Merging:**
73
- Consecutive `insert_text` operations at the same path and offset are merged
74
- Creates smooth undo behavior for continuous typing
75

76
**Text Deletion Merging:**
77
- Consecutive `remove_text` operations at adjacent positions are merged
78
- Supports both forward deletion and backspace deletion patterns
79

80
**Non-mergeable Operations:**
81
- `set_selection` operations are never saved to history
82
- Other operation types create separate batches
83

84
## Integration Notes
85

86
**Plugin Order:**
87
- When using with `withReact`, apply `withHistory` first: `withReact(withHistory(editor))`
88
- This ensures history operations work correctly with React-specific editor behavior
89

90
**Performance:**
91
- History stack is automatically limited to 100 batches to prevent memory issues
92
- Operation batching reduces memory usage compared to storing every individual operation
93

94
**State Preservation:**
95
- Selection state is preserved and restored during undo/redo operations
96
- Editor normalization is temporarily disabled during history operations to prevent conflicts