0
# Tiptap Extensions
1
2
Tiptap Extensions is a collection of essential utility extensions for the Tiptap rich text editor. This package provides 8 specialized extensions that enhance editor functionality with features like character counting, drag-and-drop visual feedback, placeholder text, focus management, gap navigation, selection styling, document structure management, and undo/redo capabilities.
3
4
## Package Information
5
6
- **Package Name**: @tiptap/extensions
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extensions`
10
11
## Core Imports
12
13
All extensions can be imported from the main package:
14
15
```typescript
16
import { CharacterCount, Focus, Placeholder, UndoRedo } from "@tiptap/extensions";
17
```
18
19
Individual extension imports are also supported:
20
21
```typescript
22
import { CharacterCount } from "@tiptap/extensions/character-count";
23
import { Focus } from "@tiptap/extensions/focus";
24
import { Placeholder } from "@tiptap/extensions/placeholder";
25
import { UndoRedo } from "@tiptap/extensions/undo-redo";
26
```
27
28
For CommonJS:
29
30
```javascript
31
const { CharacterCount, Focus, Placeholder } = require("@tiptap/extensions");
32
```
33
34
## Basic Usage
35
36
```typescript
37
import { Editor } from "@tiptap/core";
38
import { CharacterCount, Focus, Placeholder } from "@tiptap/extensions";
39
40
const editor = new Editor({
41
extensions: [
42
CharacterCount.configure({
43
limit: 280,
44
}),
45
Focus.configure({
46
className: 'has-focus',
47
mode: 'all',
48
}),
49
Placeholder.configure({
50
placeholder: 'Start typing...',
51
showOnlyWhenEditable: true,
52
}),
53
],
54
content: '<p>Hello World!</p>',
55
});
56
57
// Access character count
58
const characterCount = editor.storage.characterCount.characters();
59
console.log(`Characters: ${characterCount}`);
60
```
61
62
## Architecture
63
64
All extensions follow the Tiptap Extension pattern using `Extension.create()`. Each extension:
65
66
- **Options Interface**: Configurable options with sensible defaults
67
- **Storage Interface**: Runtime methods and state (where applicable)
68
- **ProseMirror Integration**: Seamless integration with ProseMirror plugins
69
- **Type Safety**: Full TypeScript support with proper type definitions
70
- **Module Augmentation**: Extensions that modify global types do so via module declarations
71
72
## Capabilities
73
74
### Text and Document Analysis
75
76
Extensions for measuring and analyzing document content.
77
78
```typescript { .api }
79
interface CharacterCountOptions {
80
limit: number | null | undefined;
81
mode: 'textSize' | 'nodeSize';
82
textCounter: (text: string) => number;
83
wordCounter: (text: string) => number;
84
}
85
86
interface CharacterCountStorage {
87
characters: (options?: { node?: ProsemirrorNode; mode?: 'textSize' | 'nodeSize' }) => number;
88
words: (options?: { node?: ProsemirrorNode }) => number;
89
}
90
```
91
92
[Text Analysis](./text-analysis.md)
93
94
### Visual Enhancement
95
96
Extensions that provide visual feedback and styling for the editor interface.
97
98
```typescript { .api }
99
interface FocusOptions {
100
className: string;
101
mode: 'all' | 'deepest' | 'shallowest';
102
}
103
104
interface DropcursorOptions {
105
color?: string | false;
106
width: number | undefined;
107
class: string | undefined;
108
}
109
110
interface PlaceholderOptions {
111
emptyEditorClass: string;
112
emptyNodeClass: string;
113
placeholder: string | ((props: PlaceholderProps) => string);
114
showOnlyWhenEditable: boolean;
115
showOnlyCurrent: boolean;
116
includeChildren: boolean;
117
}
118
```
119
120
[Visual Enhancement](./visual-enhancement.md)
121
122
### Navigation and Interaction
123
124
Extensions that enhance cursor movement and user interaction patterns.
125
126
```typescript { .api }
127
declare module '@tiptap/core' {
128
interface NodeConfig<Options, Storage> {
129
allowGapCursor?: boolean | null | ((this: {
130
name: string;
131
options: Options;
132
storage: Storage;
133
parent: ParentConfig<NodeConfig<Options>>['allowGapCursor'];
134
}) => boolean | null);
135
}
136
}
137
138
type SelectionOptions = {
139
className: string;
140
}
141
```
142
143
[Navigation and Interaction](./navigation-interaction.md)
144
145
### Document Structure Management
146
147
Extensions for managing document structure and content flow.
148
149
```typescript { .api }
150
interface TrailingNodeOptions {
151
node: string;
152
notAfter?: string | string[];
153
}
154
155
interface UndoRedoOptions {
156
depth: number;
157
newGroupDelay: number;
158
}
159
160
declare module '@tiptap/core' {
161
interface Commands<ReturnType> {
162
undoRedo: {
163
undo: () => ReturnType;
164
redo: () => ReturnType;
165
};
166
}
167
}
168
```
169
170
[Document Structure](./document-structure.md)