0
# @tiptap/extension-history
1

2
The @tiptap/extension-history package provides undo and redo functionality for Tiptap rich text editors. This deprecated extension offers a simple interface for implementing keyboard shortcuts and programmatic commands for editor history management.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-history
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-history`
10
- **Status**: Deprecated (located in packages-deprecated)
11

12
## Core Imports
13

14
```typescript
15
import { History } from '@tiptap/extension-history';
16
import type { HistoryOptions } from '@tiptap/extension-history';
17
```
18

19
For default export:
20

21
```typescript
22
import History from '@tiptap/extension-history';
23
```
24

25
CommonJS:
26

27
```javascript
28
const { History } = require('@tiptap/extension-history');
29
const History = require('@tiptap/extension-history').default;
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { Editor } from '@tiptap/core';
36
import { History } from '@tiptap/extension-history';
37

38
// Create editor with history extension
39
const editor = new Editor({
40
  extensions: [
41
    History.configure({
42
      depth: 100,
43
      newGroupDelay: 500,
44
    }),
45
  ],
46
});
47

48
// Use undo/redo commands
49
editor.commands.undo();
50
editor.commands.redo();
51

52
// Check if undo/redo is available
53
const canUndo = editor.can().undo();
54
const canRedo = editor.can().redo();
55
```
56

57
## Capabilities
58

59
### Extension Configuration
60

61
Configure the history extension with options for depth and grouping delay.
62

63
```typescript { .api }
64
/**
65
 * History extension with undo/redo functionality
66
 * @param options - Configuration options for the history extension
67
 */
68
const History: Extension<HistoryOptions>;
69

70
interface HistoryOptions {
71
  /**
72
   * The amount of history events that are collected before the oldest events are discarded.
73
   * @default 100
74
   */
75
  depth: number;
76

77
  /**
78
   * The delay (in milliseconds) between changes after which a new group should be started.
79
   * @default 500
80
   */
81
  newGroupDelay: number;
82
}
83
```
84

85
**Usage Example:**
86

87
```typescript
88
import { Editor } from '@tiptap/core';
89
import { History } from '@tiptap/extension-history';
90

91
const editor = new Editor({
92
  extensions: [
93
    History.configure({
94
      depth: 50,        // Keep only 50 history events
95
      newGroupDelay: 1000, // Group changes within 1 second
96
    }),
97
  ],
98
});
99
```
100

101
### Undo Command
102

103
Undo the most recent changes in the editor.
104

105
```typescript { .api }
106
/**
107
 * Undo recent changes
108
 * @returns boolean - true if undo was successful, false if no changes to undo
109
 */
110
undo(): boolean;
111
```
112

113
**Usage Example:**
114

115
```typescript
116
// Programmatic undo
117
if (editor.can().undo()) {
118
  editor.commands.undo();
119
}
120

121
// Check if undo is available
122
const canUndo = editor.can().undo();
123
```
124

125
### Redo Command
126

127
Reapply previously undone changes in the editor.
128

129
```typescript { .api }
130
/**
131
 * Reapply reverted changes
132
 * @returns boolean - true if redo was successful, false if no changes to redo
133
 */
134
redo(): boolean;
135
```
136

137
**Usage Example:**
138

139
```typescript
140
// Programmatic redo
141
if (editor.can().redo()) {
142
  editor.commands.redo();
143
}
144

145
// Check if redo is available
146
const canRedo = editor.can().redo();
147
```
148

149
### Keyboard Shortcuts
150

151
The extension automatically registers the following keyboard shortcuts:
152

153
```typescript { .api }
154
interface KeyboardShortcuts {
155
  'Mod-z': () => boolean;        // Undo (Ctrl+Z on Windows/Linux, Cmd+Z on Mac)
156
  'Shift-Mod-z': () => boolean;  // Redo (Ctrl+Shift+Z)
157
  'Mod-y': () => boolean;        // Redo (Ctrl+Y on Windows/Linux, Cmd+Y on Mac)
158
  'Mod-я': () => boolean;        // Undo (Russian keyboard layout)
159
  'Shift-Mod-я': () => boolean;  // Redo (Russian keyboard layout)
160
}
161
```
162

163
**Note:** The shortcuts are automatically active when the extension is installed - no additional configuration required.
164

165
## Types
166

167
```typescript { .api }
168
/**
169
 * Main extension class providing undo/redo functionality
170
 */
171
class Extension<HistoryOptions> {
172
  /**
173
   * Configure the extension with custom options
174
   * @param options - Partial configuration options
175
   */
176
  configure(options?: Partial<HistoryOptions>): Extension<HistoryOptions>;
177

178
  /**
179
   * Extension name identifier
180
   */
181
  name: 'undoRedo';
182
}
183

184
/**
185
 * Type alias for backward compatibility
186
 */
187
type HistoryOptions = UndoRedoOptions;
188

189
/**
190
 * Configuration interface for the history extension
191
 */
192
interface UndoRedoOptions {
193
  depth: number;
194
  newGroupDelay: number;
195
}
196
```
197

198
## Important Notes
199

200
### Compatibility Constraints
201

202
**⚠️ Not compatible with @tiptap/extension-collaboration**
203

204
This extension cannot be used together with the collaboration extension, as they have conflicting history implementations:
205

206
```typescript
207
// ❌ Don't do this - will cause conflicts
208
import { Collaboration } from '@tiptap/extension-collaboration';
209
import { History } from '@tiptap/extension-history';
210

211
const editor = new Editor({
212
  extensions: [
213
    History,        // ❌ Remove this when using collaboration
214
    Collaboration.configure({
215
      document: ydoc,
216
    }),
217
  ],
218
});
219

220
// ✅ Use collaboration without history extension
221
const editor = new Editor({
222
  extensions: [
223
    // History is built into collaboration
224
    Collaboration.configure({
225
      document: ydoc,
226
    }),
227
  ],
228
});
229
```
230

231
### Deprecation Status
232

233
This package is deprecated and located in the `packages-deprecated` directory. For new projects, consider using:
234

235
- `@tiptap/extensions` UndoRedo directly
236
- Built-in collaboration history when using `@tiptap/extension-collaboration`
237

238
**Migration Example:**
239

240
```typescript
241
// Old (deprecated)
242
import { History } from '@tiptap/extension-history';
243

244
// New (recommended)
245
import { UndoRedo } from '@tiptap/extensions';
246

247
const editor = new Editor({
248
  extensions: [
249
    UndoRedo.configure({
250
      depth: 100,
251
      newGroupDelay: 500,
252
    }),
253
  ],
254
});
255
```
256

257
## Complete API Surface
258

259
**Exports:**
260
- `History` - Main extension class (alias for UndoRedo)
261
- `HistoryOptions` - Configuration interface (alias for UndoRedoOptions)
262
- Default export: `UndoRedo` extension class
263

264
**Commands added to editor:**
265
- `undo()` - Undo recent changes
266
- `redo()` - Reapply reverted changes
267

268
**Keyboard shortcuts:**
269
- `Mod-z`, `Shift-Mod-z`, `Mod-y` (with Russian keyboard support)
270

271
**Configuration options:**
272
- `depth` - Number of history events to keep (default: 100)
273
- `newGroupDelay` - Delay for grouping changes (default: 500ms)