0
# @tiptap/pm
1

2
@tiptap/pm is a comprehensive wrapper package around ProseMirror, providing a unified entry point for all ProseMirror functionality required by the Tiptap rich text editor framework. It re-exports modules from 18 different ProseMirror packages through individual sub-module exports, simplifying dependency management for rich text editor development.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/pm
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/pm`
10

11
## Core Imports
12

13
Each ProseMirror module is accessed via sub-module import:
14

15
```typescript
16
import { EditorState, Transaction } from "@tiptap/pm/state";
17
import { EditorView } from "@tiptap/pm/view";
18
import { Node, Schema } from "@tiptap/pm/model";
19
import { history, undo, redo } from "@tiptap/pm/history";
20
```
21

22
All 18 sub-modules are available:
23

24
```typescript
25
// Core document and state management
26
import * as model from "@tiptap/pm/model";
27
import * as state from "@tiptap/pm/state";
28
import * as view from "@tiptap/pm/view";
29
import * as transform from "@tiptap/pm/transform";
30

31
// Commands and editing
32
import * as commands from "@tiptap/pm/commands";
33
import * as inputrules from "@tiptap/pm/inputrules";
34
import * as keymap from "@tiptap/pm/keymap";
35

36
// Schema definitions
37
import * as schemaBasic from "@tiptap/pm/schema-basic";
38
import * as schemaList from "@tiptap/pm/schema-list";
39

40
// Extensions and features
41
import * as history from "@tiptap/pm/history";
42
import * as tables from "@tiptap/pm/tables";
43
import * as collab from "@tiptap/pm/collab";
44
import * as menu from "@tiptap/pm/menu";
45
import * as markdown from "@tiptap/pm/markdown";
46

47
// Cursor and UI enhancements
48
import * as gapcursor from "@tiptap/pm/gapcursor";
49
import * as dropcursor from "@tiptap/pm/dropcursor";
50
import * as trailingNode from "@tiptap/pm/trailing-node";
51

52
// Change tracking
53
import * as changeset from "@tiptap/pm/changeset";
54
```
55

56
## Basic Usage
57

58
```typescript
59
import { EditorState } from "@tiptap/pm/state";
60
import { EditorView } from "@tiptap/pm/view";
61
import { Schema } from "@tiptap/pm/model";
62
import { schema as basicSchema } from "@tiptap/pm/schema-basic";
63
import { history } from "@tiptap/pm/history";
64
import { keymap } from "@tiptap/pm/keymap";
65
import { baseKeymap } from "@tiptap/pm/commands";
66

67
// Create editor state
68
const state = EditorState.create({
69
  schema: basicSchema,
70
  plugins: [
71
    history(),
72
    keymap(baseKeymap),
73
  ],
74
});
75

76
// Create editor view
77
const view = new EditorView(document.querySelector("#editor"), {
78
  state,
79
  dispatchTransaction(transaction) {
80
    const newState = view.state.apply(transaction);
81
    view.updateState(newState);
82
  },
83
});
84
```
85

86
## Architecture
87

88
@tiptap/pm is organized around ProseMirror's modular architecture:
89

90
- **Core System**: Document model, state management, and view rendering
91
- **Editing Operations**: Commands, transformations, and input handling
92
- **Schema Definitions**: Pre-built node and mark types for common use cases
93
- **Extensions**: Advanced features like tables, collaboration, and history
94
- **UI Components**: Menus, cursors, and visual enhancements
95

96
Each sub-module provides a complete re-export of the corresponding ProseMirror package, maintaining full API compatibility while simplifying dependency management.
97

98
## Capabilities
99

100
### Document Model and Schema
101

102
Core document structure, node and mark definitions, and schema management for defining editor capabilities.
103

104
```typescript { .api }
105
// Key classes from @tiptap/pm/model
106
class Schema {
107
  constructor(spec: SchemaSpec);
108
  node(name: string): NodeType;
109
  mark(name: string): MarkType;
110
}
111

112
class Node {
113
  readonly type: NodeType;
114
  readonly attrs: Attrs;
115
  readonly content: Fragment;
116
  readonly marks: Mark[];
117
}
118

119
class Fragment {
120
  static from(nodes: Node[] | Node | Fragment): Fragment;
121
  append(other: Fragment): Fragment;
122
  cut(from: number, to?: number): Fragment;
123
}
124
```
125

126
[Document Model and Schema](./model-and-schema.md)
127

128
### Editor State Management
129

130
Complete editor state management including selections, transactions, and plugin system.
131

132
```typescript { .api }
133
// Key classes from @tiptap/pm/state
134
class EditorState {
135
  static create(config: EditorStateConfig): EditorState;
136
  readonly doc: Node;
137
  readonly selection: Selection;
138
  readonly tr: Transaction;
139
  apply(tr: Transaction): EditorState;
140
}
141

142
class Transaction {
143
  readonly doc: Node;
144
  insertText(text: string, from?: number, to?: number): Transaction;
145
  delete(from: number, to: number): Transaction;
146
  replaceWith(from: number, to: number, content: Fragment): Transaction;
147
}
148
```
149

150
[Editor State Management](./state-management.md)
151

152
### View and Rendering
153

154
DOM rendering, user interaction handling, and visual decorations.
155

156
```typescript { .api }
157
// Key classes from @tiptap/pm/view
158
class EditorView {
159
  constructor(place: Element, props: EditorProps);
160
  readonly state: EditorState;
161
  updateState(state: EditorState): void;
162
  dispatch(tr: Transaction): void;
163
  destroy(): void;
164
}
165

166
class Decoration {
167
  static widget(pos: number, dom: Element): Decoration;
168
  static inline(from: number, to: number, attrs: object): Decoration;
169
  static node(from: number, to: number, attrs: object): Decoration;
170
}
171
```
172

173
[View and Rendering](./view-and-rendering.md)
174

175
### Commands and Editing
176

177
Text manipulation commands, selection handling, and common editing operations.
178

179
```typescript { .api }
180
// Key functions from @tiptap/pm/commands
181
type Command = (state: EditorState, dispatch?: (tr: Transaction) => void) => boolean;
182

183
function deleteSelection(state: EditorState, dispatch?: (tr: Transaction) => void): boolean;
184
function joinBackward(state: EditorState, dispatch?: (tr: Transaction) => void): boolean;
185
function selectAll(state: EditorState, dispatch?: (tr: Transaction) => void): boolean;
186
function toggleMark(markType: MarkType): Command;
187
function wrapIn(nodeType: NodeType, attrs?: Attrs): Command;
188
```
189

190
[Commands and Editing](./commands-and-editing.md)
191

192
### Input Rules and Keymaps
193

194
Automatic text transformations and keyboard shortcut handling.
195

196
```typescript { .api }
197
// Key classes and functions from @tiptap/pm/inputrules and @tiptap/pm/keymap
198
class InputRule {
199
  constructor(pattern: RegExp, handler: string | InputRuleHandler);
200
}
201

202
function inputRules(config: { rules: InputRule[] }): Plugin;
203
function keymap(bindings: { [key: string]: Command }): Plugin;
204
```
205

206
[Input Rules and Keymaps](./input-and-keymaps.md)
207

208
### Schema Definitions
209

210
Pre-built schemas for common document structures and list handling.
211

212
```typescript { .api }
213
// Constants from @tiptap/pm/schema-basic and @tiptap/pm/schema-list
214
const schema: Schema; // Basic schema with common nodes and marks
215
const nodes: { [name: string]: NodeSpec };
216
const marks: { [name: string]: MarkSpec };
217

218
// List-related functions
219
function addListNodes(nodes: { [name: string]: NodeSpec }, itemContent: string): { [name: string]: NodeSpec };
220
function wrapInList(listType: NodeType, attrs?: Attrs): Command;
221
```
222

223
[Schema Definitions](./schema-definitions.md)
224

225
### History and Undo/Redo
226

227
Undo/redo functionality with configurable history tracking.
228

229
```typescript { .api }
230
// Key functions from @tiptap/pm/history
231
function history(config?: HistoryOptions): Plugin;
232
function undo(state: EditorState, dispatch?: (tr: Transaction) => void): boolean;
233
function redo(state: EditorState, dispatch?: (tr: Transaction) => void): boolean;
234
function undoDepth(state: EditorState): number;
235
function redoDepth(state: EditorState): number;
236
```
237

238
[History and Undo/Redo](./history.md)
239

240
### Tables
241

242
Advanced table editing with cell selection, column resizing, and table manipulation.
243

244
```typescript { .api }
245
// Key classes and functions from @tiptap/pm/tables
246
class CellSelection extends Selection {
247
  static create(doc: Node, from: number, to?: number): CellSelection;
248
}
249

250
function tableNodes(options: TableNodesOptions): { [name: string]: NodeSpec };
251
function tableEditing(): Plugin;
252
function columnResizing(options?: ColumnResizingOptions): Plugin;
253
```
254

255
[Tables](./tables.md)
256

257
### Collaboration
258

259
Real-time collaborative editing with conflict resolution.
260

261
```typescript { .api }
262
// Key functions from @tiptap/pm/collab
263
function collab(config?: CollabConfig): Plugin;
264
function sendableSteps(state: EditorState): { version: number; steps: Step[]; clientID: number } | null;
265
function receiveTransaction(state: EditorState, steps: Step[], clientIDs: number[]): Transaction;
266
function getVersion(state: EditorState): number;
267
```
268

269
[Collaboration](./collaboration.md)
270

271
### Markdown Support
272

273
Markdown parsing and serialization for document interchange.
274

275
```typescript { .api }
276
// Key classes from @tiptap/pm/markdown
277
class MarkdownParser {
278
  constructor(schema: Schema, tokenizer: any, tokens: { [token: string]: ParseSpec });
279
  parse(text: string): Node;
280
}
281

282
class MarkdownSerializer {
283
  constructor(nodes: { [name: string]: any }, marks: { [name: string]: MarkSerializerSpec });
284
  serialize(content: Node): string;
285
}
286
```
287

288
[Markdown Support](./markdown.md)
289

290
### Menus and UI
291

292
Visual menu components and user interface elements.
293

294
```typescript { .api }
295
// Key classes and functions from @tiptap/pm/menu
296
class MenuItem {
297
  constructor(spec: MenuItemSpec);
298
}
299

300
function menuBar(options: { content: MenuElement[][] }): Plugin;
301
function renderGrouped(view: EditorView, content: MenuElement[][]): DocumentFragment;
302
```
303

304
[Menus and UI](./menus-and-ui.md)
305

306
### Document Transformations
307

308
Low-level document transformation and position mapping.
309

310
```typescript { .api }
311
// Key classes from @tiptap/pm/transform
312
class Transform {
313
  readonly doc: Node;
314
  readonly steps: Step[];
315
  step(step: Step): Transform;
316
  insertText(pos: number, text: string): Transform;
317
  delete(from: number, to: number): Transform;
318
}
319

320
class Step {
321
  apply(doc: Node): StepResult;
322
  getMap(): StepMap;
323
}
324
```
325

326
[Document Transformations](./transformations.md)
327

328
### Cursors and Visual Enhancements
329

330
Gap cursor, drop cursor, and trailing node functionality for improved user experience.
331

332
```typescript { .api }
333
// Key functions from cursor and enhancement modules
334
function gapCursor(): Plugin;
335
function dropCursor(options?: DropCursorOptions): Plugin;
336
function trailingNode(options: TrailingNodeOptions): Plugin;
337
```
338

339
[Cursors and Visual Enhancements](./cursors-and-enhancements.md)
340

341
## Types
342

343
```typescript { .api }
344
// Core types used across the API
345
interface SchemaSpec {
346
  nodes: { [name: string]: NodeSpec };
347
  marks?: { [name: string]: MarkSpec };
348
  topNode?: string;
349
}
350

351
interface NodeSpec {
352
  content?: string;
353
  marks?: string;
354
  group?: string;
355
  inline?: boolean;
356
  atom?: boolean;
357
  attrs?: { [name: string]: AttributeSpec };
358
  parseDOM?: ParseRule[];
359
  toDOM?: (node: Node) => DOMOutputSpec;
360
}
361

362
interface MarkSpec {
363
  attrs?: { [name: string]: AttributeSpec };
364
  inclusive?: boolean;
365
  excludes?: string;
366
  group?: string;
367
  parseDOM?: ParseRule[];
368
  toDOM?: (mark: Mark, inline: boolean) => DOMOutputSpec;
369
}
370

371
interface EditorStateConfig {
372
  schema?: Schema;
373
  doc?: Node;
374
  selection?: Selection;
375
  plugins?: Plugin[];
376
}
377

378
interface EditorProps {
379
  state: EditorState;
380
  dispatchTransaction?: (tr: Transaction) => void;
381
  nodeViews?: { [name: string]: NodeViewConstructor };
382
  decorations?: (state: EditorState) => DecorationSet;
383
  attributes?: (state: EditorState) => { [key: string]: string };
384
}
385

386
type Command = (state: EditorState, dispatch?: (tr: Transaction) => void, view?: EditorView) => boolean;
387

388
type DOMOutputSpec = string | Element | [string, ...any[]];
389
type Attrs = { [key: string]: any };
390
```