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)