0
# Tiptap Extension: Gapcursor
1

2
The `@tiptap/extension-gapcursor` package provides a gapcursor extension for Tiptap editors that enables cursor placement in positions where no content is present, such as between nodes or after tables at the end of a document. This extension wraps the ProseMirror Gapcursor plugin and integrates it seamlessly with Tiptap's extension system.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-gapcursor
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-gapcursor`
10
- **Status**: Deprecated (use @tiptap/extensions instead)
11

12
## Core Imports
13

14
```typescript
15
import { Gapcursor } from "@tiptap/extension-gapcursor";
16
```
17

18
Default import:
19

20
```typescript
21
import Gapcursor from "@tiptap/extension-gapcursor";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { Gapcursor } = require("@tiptap/extension-gapcursor");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Editor } from "@tiptap/core";
34
import { Gapcursor } from "@tiptap/extension-gapcursor";
35

36
// Add the gapcursor extension to your editor
37
const editor = new Editor({
38
  extensions: [
39
    Gapcursor,
40
    // ... other extensions
41
  ],
42
  content: '<p>Your content here</p>',
43
});
44
```
45

46
Advanced usage with configuration:
47

48
```typescript
49
import { Editor } from "@tiptap/core";
50
import { Gapcursor } from "@tiptap/extension-gapcursor";
51

52
const editor = new Editor({
53
  extensions: [
54
    Gapcursor.configure({
55
      // Configuration options if needed
56
    }),
57
    // ... other extensions
58
  ],
59
  content: '<p>Your content</p>',
60
});
61
```
62

63
## Architecture
64

65
The extension follows Tiptap's standard extension architecture:
66

67
- **Extension Class**: Extends the base Tiptap Extension class with name `'gapCursor'`
68
- **ProseMirror Integration**: Adds the ProseMirror gapcursor plugin via `addProseMirrorPlugins()` using `gapCursor()` from `prosemirror-gapcursor`
69
- **Schema Extension**: Extends node schemas with `allowGapCursor` property through `extendNodeSchema()`
70
- **Re-export Pattern**: This package is a simple wrapper that re-exports from `@tiptap/extensions`
71
- **Dependencies**: Built on top of ProseMirror's `prosemirror-gapcursor` plugin
72

73
## Capabilities
74

75
### Gapcursor Extension
76

77
The main extension class that provides gap cursor functionality for Tiptap editors.
78

79
```typescript { .api }
80
/**
81
 * Gapcursor extension that enables cursor placement where no content is present
82
 * Extends the base Tiptap Extension class with name 'gapCursor'
83
 * @see https://tiptap.dev/api/extensions/gapcursor
84
 */
85
export const Gapcursor: Extension<{}, {}>;
86

87
/**
88
 * Default export of the Gapcursor extension
89
 */
90
export default Gapcursor;
91
```
92

93
### Extension Configuration
94

95
The Gapcursor extension can be configured using the standard Tiptap extension configuration pattern.
96

97
```typescript { .api }
98
/**
99
 * Configure the Gapcursor extension with options
100
 * @param options - Configuration options (currently accepts empty object)
101
 * @returns Configured Gapcursor extension instance
102
 */
103
Gapcursor.configure(options?: {}): Extension<{}, {}>;
104

105
/**
106
 * Extend the Gapcursor extension with additional configuration
107
 * @param config - Extension configuration or function returning configuration
108
 * @returns Extended Gapcursor extension instance
109
 */
110
Gapcursor.extend<ExtendedOptions, ExtendedStorage>(
111
  config?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
112
): Extension<ExtendedOptions, ExtendedStorage>;
113
```
114

115
### Node Schema Extension
116

117
The extension adds support for the `allowGapCursor` property to node configurations.
118

119
```typescript { .api }
120
/**
121
 * Node configuration property for controlling gap cursor behavior
122
 * Added to NodeConfig interface via module augmentation
123
 */
124
interface NodeConfig<Options, Storage> {
125
  /**
126
   * A function to determine whether the gap cursor is allowed at the current position. Must return `true` or `false`.
127
   * @default null
128
   */
129
  allowGapCursor?:
130
    | boolean
131
    | null
132
    | ((this: {
133
        name: string
134
        options: Options
135
        storage: Storage
136
        parent: ParentConfig<NodeConfig<Options>>['allowGapCursor']
137
      }) => boolean | null)
138
}
139
```
140

141
## Extension Methods
142

143
### addProseMirrorPlugins
144

145
```typescript { .api }
146
/**
147
 * Adds ProseMirror plugins to the editor
148
 * @returns Array containing the ProseMirror gapcursor plugin from prosemirror-gapcursor
149
 */
150
addProseMirrorPlugins(): ProseMirrorPlugin[];
151
```
152

153
### extendNodeSchema
154

155
```typescript { .api }
156
/**
157
 * Extends node schema with gap cursor configuration
158
 * @param extension - The extension instance
159
 * @returns Schema extension object with allowGapCursor property
160
 */
161
extendNodeSchema(extension: Extension): {
162
  allowGapCursor: boolean | null;
163
};
164
```
165

166
## Types
167

168
```typescript { .api }
169
/**
170
 * Base Extension class from @tiptap/core
171
 * All Tiptap extensions extend this class
172
 */
173
declare class Extension<Options = any, Storage = any> {
174
  type: 'extension';
175
  static create<O = any, S = any>(
176
    config?: Partial<ExtensionConfig<O, S>>
177
  ): Extension<O, S>;
178
  configure(options?: Partial<Options>): Extension<Options, Storage>;
179
  extend<ExtendedOptions, ExtendedStorage>(
180
    config?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
181
  ): Extension<ExtendedOptions, ExtendedStorage>;
182
}
183

184
/**
185
 * Extension configuration interface
186
 */
187
interface ExtensionConfig<Options = any, Storage = any> {
188
  name?: string;
189
  priority?: number;
190
  defaultOptions?: Options;
191
  addStorage?: () => Storage;
192
  addProseMirrorPlugins?: () => ProseMirrorPlugin[];
193
  extendNodeSchema?: (extension: Extension) => Record<string, any>;
194
}
195

196
/**
197
 * Parent configuration context for nested extension configurations
198
 */
199
interface ParentConfig<T> {
200
  allowGapCursor?: T;
201
}
202

203
/**
204
 * ProseMirror Plugin interface
205
 */
206
interface ProseMirrorPlugin {
207
  // Plugin implementation details
208
}
209
```
210

211
## Error Handling
212

213
The Gapcursor extension generally operates transparently and does not throw specific errors. Error handling typically occurs at the editor level. Common issues:
214

215
- **Import Errors**: Ensure `@tiptap/extension-gapcursor` is installed and imported correctly
216
- **Configuration Errors**: Verify extension configuration syntax matches Tiptap standards
217
- **Plugin Conflicts**: Some ProseMirror plugins may conflict; check for plugin compatibility
218

219
## Migration Notes
220

221
This package is deprecated in favor of using `@tiptap/extensions` directly:
222

223
```typescript
224
// Deprecated approach (re-exports from @tiptap/extensions)
225
import { Gapcursor } from "@tiptap/extension-gapcursor";
226

227
// Recommended approach (direct import from consolidated package)
228
import { Gapcursor } from "@tiptap/extensions";
229

230
// You can also import from specific subpath
231
import { Gapcursor } from "@tiptap/extensions/gap-cursor";
232
```
233

234
Both approaches provide identical functionality, but the consolidated package reduces dependency overhead. The deprecated package is simply a wrapper that re-exports the same `Gapcursor` extension from `@tiptap/extensions`.