or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-tiptap--extension-gapcursor

Gapcursor extension for Tiptap that enables cursor placement in positions where no content is present, such as between nodes or after tables

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tiptap/extension-gapcursor@3.4.x

To install, run

npx @tessl/cli install tessl/npm-tiptap--extension-gapcursor@3.4.0

index.mddocs/

Tiptap Extension: Gapcursor

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.

Package Information

  • Package Name: @tiptap/extension-gapcursor
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @tiptap/extension-gapcursor
  • Status: Deprecated (use @tiptap/extensions instead)

Core Imports

import { Gapcursor } from "@tiptap/extension-gapcursor";

Default import:

import Gapcursor from "@tiptap/extension-gapcursor";

For CommonJS:

const { Gapcursor } = require("@tiptap/extension-gapcursor");

Basic Usage

import { Editor } from "@tiptap/core";
import { Gapcursor } from "@tiptap/extension-gapcursor";

// Add the gapcursor extension to your editor
const editor = new Editor({
  extensions: [
    Gapcursor,
    // ... other extensions
  ],
  content: '<p>Your content here</p>',
});

Advanced usage with configuration:

import { Editor } from "@tiptap/core";
import { Gapcursor } from "@tiptap/extension-gapcursor";

const editor = new Editor({
  extensions: [
    Gapcursor.configure({
      // Configuration options if needed
    }),
    // ... other extensions
  ],
  content: '<p>Your content</p>',
});

Architecture

The extension follows Tiptap's standard extension architecture:

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

Capabilities

Gapcursor Extension

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

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

/**
 * Default export of the Gapcursor extension
 */
export default Gapcursor;

Extension Configuration

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

/**
 * Configure the Gapcursor extension with options
 * @param options - Configuration options (currently accepts empty object)
 * @returns Configured Gapcursor extension instance
 */
Gapcursor.configure(options?: {}): Extension<{}, {}>;

/**
 * Extend the Gapcursor extension with additional configuration
 * @param config - Extension configuration or function returning configuration
 * @returns Extended Gapcursor extension instance
 */
Gapcursor.extend<ExtendedOptions, ExtendedStorage>(
  config?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
): Extension<ExtendedOptions, ExtendedStorage>;

Node Schema Extension

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

/**
 * Node configuration property for controlling gap cursor behavior
 * Added to NodeConfig interface via module augmentation
 */
interface NodeConfig<Options, Storage> {
  /**
   * A function to determine whether the gap cursor is allowed at the current position. Must return `true` or `false`.
   * @default null
   */
  allowGapCursor?:
    | boolean
    | null
    | ((this: {
        name: string
        options: Options
        storage: Storage
        parent: ParentConfig<NodeConfig<Options>>['allowGapCursor']
      }) => boolean | null)
}

Extension Methods

addProseMirrorPlugins

/**
 * Adds ProseMirror plugins to the editor
 * @returns Array containing the ProseMirror gapcursor plugin from prosemirror-gapcursor
 */
addProseMirrorPlugins(): ProseMirrorPlugin[];

extendNodeSchema

/**
 * Extends node schema with gap cursor configuration
 * @param extension - The extension instance
 * @returns Schema extension object with allowGapCursor property
 */
extendNodeSchema(extension: Extension): {
  allowGapCursor: boolean | null;
};

Types

/**
 * Base Extension class from @tiptap/core
 * All Tiptap extensions extend this class
 */
declare class Extension<Options = any, Storage = any> {
  type: 'extension';
  static create<O = any, S = any>(
    config?: Partial<ExtensionConfig<O, S>>
  ): Extension<O, S>;
  configure(options?: Partial<Options>): Extension<Options, Storage>;
  extend<ExtendedOptions, ExtendedStorage>(
    config?: Partial<ExtensionConfig<ExtendedOptions, ExtendedStorage>>
  ): Extension<ExtendedOptions, ExtendedStorage>;
}

/**
 * Extension configuration interface
 */
interface ExtensionConfig<Options = any, Storage = any> {
  name?: string;
  priority?: number;
  defaultOptions?: Options;
  addStorage?: () => Storage;
  addProseMirrorPlugins?: () => ProseMirrorPlugin[];
  extendNodeSchema?: (extension: Extension) => Record<string, any>;
}

/**
 * Parent configuration context for nested extension configurations
 */
interface ParentConfig<T> {
  allowGapCursor?: T;
}

/**
 * ProseMirror Plugin interface
 */
interface ProseMirrorPlugin {
  // Plugin implementation details
}

Error Handling

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

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

Migration Notes

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

// Deprecated approach (re-exports from @tiptap/extensions)
import { Gapcursor } from "@tiptap/extension-gapcursor";

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

// You can also import from specific subpath
import { Gapcursor } from "@tiptap/extensions/gap-cursor";

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.