---
title: "Position Utilities"
description: "Track and update positions in your editor using MappablePosition and CollaborationMappablePosition. Learn how to serialize and deserialize positions."
canonical_url: "https://tiptap.dev/docs/editor/api/utilities/position"
---

# Position Utilities

Track and update positions in your editor using MappablePosition and CollaborationMappablePosition. Learn how to serialize and deserialize positions.

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.

```js
// 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](https://tiptap.dev/docs/editor/extensions/functionality/collaboration.md) 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.

```js
// 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](https://prosemirror.net/docs/ref/#transform.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](https://docs.yjs.dev/) 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](https://docs.yjs.dev/api/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.

```js
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.

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

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

### Example: Storing a Position

```js
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](https://docs.yjs.dev/api/relative-positions) (internal, used for collaboration).

#### Methods

##### `toJSON`

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

```js
// 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.

```js
// 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

```js
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)
```