Position Utilities

Position utilities help you track and update positions in your editor as the document changes.

Creating a position

Use createMappablePosition to create a position instance.

// Create a position at offset 10
const position = editor.utils.createMappablePosition(10)

The createMappablePosition method returns a MappablePosition instance by default. If the Collaboration extension is active, it will return a CollaborationMappablePosition instance.

• MappablePosition: Base class for tracking positions in standard editors
• CollaborationMappablePosition: Extended class for tracking positions when collaboration is enabled.

Updating a position

Use getUpdatedPosition to update a position after a transaction. The position is updated to reflect changes in the document.

// Get the updated position after a transaction
const { position: updatedPosition, mapResult } = editor.utils.getUpdatedPosition(
  position,
  transaction,
)

// The updated position reflects the new location after the transaction
const newOffset = updatedPosition.position

The getUpdatedPosition method returns an object with the following properties:

• position (MappablePosition): The updated position.
• mapResult (MapResult | null): The result of the mapping operation, as a ProseMirror MapResult. It contains information about the operation, for example, to see if the position was deleted.

Limitations

When a collaborative transaction breaks a paragraph in two, Y.js sees it as the deletion of the second half of the paragraph, followed by the insertion of a new paragraph. Thus, if the original position is after the line break, the updated position will not be placed in the second paragraph, but at the end of the first paragraph. This is a limitation of Y.js relative positions and we're working on a solution.

API reference

MappablePosition

The base MappablePosition class tracks a position in the document.

Properties

• position (number): The current position offset.

Methods

toJSON

Serializes the position to a JSON object for storage.

const position = editor.utils.createMappablePosition(10)
const json = position.toJSON()

// Store in localStorage or send to server
localStorage.setItem('savedPosition', JSON.stringify(json))

fromJSON

Deserializes a position from a JSON object.

// Retrieve from storage
const json = JSON.parse(localStorage.getItem('savedPosition'))

// Restore the position
const position = MappablePosition.fromJSON(json)

Example: Storing a Position

import { MappablePosition } from '@tiptap/core'

// Create and serialize a position
const position = editor.utils.createMappablePosition(25)
const json = position.toJSON()

// Store it
localStorage.setItem('bookmark', JSON.stringify(json))

// Later, restore it
const savedJson = JSON.parse(localStorage.getItem('bookmark'))
const restoredPosition = MappablePosition.fromJSON(savedJson)

CollaborationMappablePosition

CollaborationMappablePosition extends MappablePosition with Y.js relative position support for collaborative editing. It's automatically used when the Collaboration extension is active.

Properties

• position (number): The current position offset.
• yRelativePosition (any): The Y.js relative position (internal, used for collaboration).

Methods

toJSON

Serializes the collaboration position to a JSON object, including Y.js relative position data.

// In a collaborative editor
const position = editor.utils.createMappablePosition(10)
const json = position.toJSON()

// json includes both position and yRelativePosition
// Store this for later restoration
localStorage.setItem('collabPosition', JSON.stringify(json))

fromJSON

Deserializes a collaboration position from a JSON object.

// Retrieve from storage
const json = JSON.parse(localStorage.getItem('collabPosition'))

// Restore the position (automatically creates CollaborationMappablePosition)
const position = CollaborationMappablePosition.fromJSON(json)

Example: Storing a Collaborative Position

import { CollaborationMappablePosition } from '@tiptap/extension-collaboration'

// Create a position in a collaborative editor
const position = editor.utils.createMappablePosition(42)

// Serialize for storage
const json = position.toJSON()
// json: { position: 42, yRelativePosition: [...] }

// Store it
localStorage.setItem('collabBookmark', JSON.stringify(json))

// Later, restore it
const savedJson = JSON.parse(localStorage.getItem('collabBookmark'))
const restoredPosition = CollaborationMappablePosition.fromJSON(savedJson)