@liveblocks/prosemirror

@liveblocks/prosemirror provides ProseMirror plugins that sync editor documents with Liveblocks Storage and display remote carets and selections. Text nodes are stored as LiveText, preserving text formatting and concurrent edits.

If you are using Tiptap, use @liveblocks/react-tiptap with collaborationMode: "liveblocks" instead. It builds on this package and provides a Tiptap extension and React components.

Setup

Install Liveblocks and the ProseMirror packages used by your editor:

npm install @liveblocks/client @liveblocks/react @liveblocks/prosemirror prosemirror-model prosemirror-state prosemirror-view

Each Liveblocks package should use the same version.

Add the collaboration plugin to sync the document and the caret plugin to show other users’ selections. The collaboration plugin creates its Storage document when it first loads, so initialStorage can remain empty.

"use client";
import { useEffect, useRef } from "react";import {  createLiveblocksCollaborationCaretPlugin,  createLiveblocksCollaborationPlugin,} from "@liveblocks/prosemirror";import "@liveblocks/prosemirror/styles.css";import { useRoom } from "@liveblocks/react/suspense";import { EditorState } from "prosemirror-state";import type { Schema } from "prosemirror-model";import { EditorView } from "prosemirror-view";
const INITIAL_CONTENT = {  type: "doc",  content: [    {      type: "paragraph",      content: [{ type: "text", text: "Hello world" }],    },  ],};
export function Editor({ schema }: { schema: Schema }) {  const room = useRoom();  const containerRef = useRef<HTMLDivElement>(null);
  useEffect(() => {    if (containerRef.current === null) return;
    const info = room.getSelf()?.info;    const user = {      name: typeof info?.name === "string" ? info.name : undefined,      color: typeof info?.color === "string" ? info.color : undefined,    };    const caretStorage = { users: [] };
    const state = EditorState.create({      schema,      plugins: [        createLiveblocksCollaborationPlugin({          room,          field: "document",          initialContent: INITIAL_CONTENT,          fallbackDocument: () => INITIAL_CONTENT,        }),        createLiveblocksCollaborationCaretPlugin(          { room, field: "document", user },          caretStorage        ),      ],    });
    const view = new EditorView(containerRef.current, { state });    return () => view.destroy();  }, [room, schema]);
  return <div ref={containerRef} className="editor" />;}

The field value identifies the editor document. Documents are stored under root._tiptap_docs, keyed by field, so use a different value for each editor in the same room.

Import the package stylesheet to display remote carets and selections:

import "@liveblocks/prosemirror/styles.css";

createLiveblocksCollaborationPlugin

Creates a ProseMirror plugin that keeps an editor document in sync with Liveblocks Storage. Local transactions update the Storage document, while remote Storage changes are applied to the editor. Text leaves are represented by LiveText.

import { createLiveblocksCollaborationPlugin } from "@liveblocks/prosemirror";
const collaborationPlugin = createLiveblocksCollaborationPlugin({  room,  field: "document",  initialContent: {    type: "doc",    content: [{ type: "paragraph" }],  },});

The plugin groups local edits into the room’s undo and redo history. Connect your editor’s undo and redo controls to room.history.undo() and room.history.redo().

createLiveblocksCollaborationCaretPlugin

Creates a ProseMirror plugin that broadcasts the local selection through Presence and renders other users’ carets and selection highlights.

import {  createLiveblocksCollaborationCaretPlugin,  type CollaborationCaretStorage,} from "@liveblocks/prosemirror";
const storage: CollaborationCaretStorage = { users: [] };const caretPlugin = createLiveblocksCollaborationCaretPlugin(  {    room,    field: "document",    user: { name: "Ada", color: "#D583F0" },  },  storage);

The plugin renders elements with the .collaboration-carets__caret, .collaboration-carets__label, and .collaboration-carets__selection class names. The user’s color is applied with inline styles.

Caret utilities

Use presencePatch when building a wrapper around the caret plugin or updating its user data outside the plugin. It creates the Presence update expected by other @liveblocks/prosemirror clients.

import { getCursorUser, presencePatch } from "@liveblocks/prosemirror";
const user = getCursorUser(room.getSelf()?.info) ?? {};
room.updatePresence(  presencePatch({    field: "document",    anchor: editorState.selection.anchor,    head: editorState.selection.head,    user,  }));

LIVEBLOCKS_CARET_PRESENCE_KEY contains the Presence key used by the caret plugin. In most applications, the plugin manages this Presence value directly.

Plugin state

LIVEBLOCKS_COLLABORATION_PLUGIN_KEY

The key for reading the collaboration plugin state. isReady becomes true after Storage has loaded and the editor has received its initial document.

import { LIVEBLOCKS_COLLABORATION_PLUGIN_KEY } from "@liveblocks/prosemirror";
const { isReady } = LIVEBLOCKS_COLLABORATION_PLUGIN_KEY.getState(  editorState) ?? { isReady: false };

LIVEBLOCKS_CARET_PLUGIN_KEY

The key for reading the collaboration caret plugin state.

import { LIVEBLOCKS_CARET_PLUGIN_KEY } from "@liveblocks/prosemirror";
const state = LIVEBLOCKS_CARET_PLUGIN_KEY.getState(editorState);const remoteCursors = state?.cursors ?? [];

Types

ProseMirrorJsonNode

The JSON representation accepted by the collaboration and conversion APIs.

CursorUser

The user information shown with a remote caret.

RemoteCursor

The cursor data exposed by LIVEBLOCKS_CARET_PLUGIN_KEY.

Document conversion

The collaboration plugin automatically converts between ProseMirror JSON and a Liveblocks Storage tree. Use these helpers only when you need to inspect or construct that Storage representation directly.

createLiveblocksProsemirrorNode

Converts a ProseMirror JSON node into a LiveObject tree. Child nodes are stored in LiveList instances and text leaves are stored in LiveText.

import { createLiveblocksProsemirrorNode } from "@liveblocks/prosemirror";
const document = createLiveblocksProsemirrorNode({  type: "doc",  content: [    {      type: "paragraph",      content: [{ type: "text", text: "Hello world" }],    },  ],});

liveblocksProsemirrorNodeToJson

Converts a LiveblocksProsemirrorNode Storage tree back to one ProseMirror JSON node.

import { liveblocksProsemirrorNodeToJson } from "@liveblocks/prosemirror";
const json = liveblocksProsemirrorNodeToJson(document, () => ({  type: "doc",  content: [{ type: "paragraph" }],}));

liveblocksProsemirrorNodeToJsonNodes

Converts a LiveblocksProsemirrorNode to an array of ProseMirror JSON nodes. Formatted LiveText segments can produce multiple adjacent text nodes.

import { liveblocksProsemirrorNodeToJsonNodes } from "@liveblocks/prosemirror";
const nodes = liveblocksProsemirrorNodeToJsonNodes(document);

Storage node helpers

Use these helpers to read values from a LiveblocksProsemirrorNode.

import {  getLiveblocksNodeContent,  getLiveblocksNodeId,  getLiveblocksNodeText,} from "@liveblocks/prosemirror";
const id = getLiveblocksNodeId(node);const children = getLiveblocksNodeContent(node);const text = getLiveblocksNodeText(node);