🚀 BlockNote AI is here! Access the early preview.
BlockNote Docs/Editor Reference/YJS Utilities

YJS Utilities

The @blocknote/core/yjs export provides utilities for converting between BlockNote blocks and YJS collaborative documents. These utilities are useful when you need to work with YJS documents outside of the standard collaboration setup, such as importing existing content or working with YJS documents programmatically.

Import

import {
  blocksToYDoc,
  blocksToYXmlFragment,
  yDocToBlocks,
  yXmlFragmentToBlocks,
  _blocksToProsemirrorNode,
  _prosemirrorJSONToBlocks,
} from "@blocknote/core/yjs";

Overview

YJS utilities enable bidirectional conversion between:

  • BlockNote blocks ↔ Y.Doc (YJS document)
  • BlockNote blocks ↔ Y.XmlFragment (YJS XML fragment)
  • BlockNote blocks ↔ Prosemirror nodes (intermediate format)

These conversions are essential for:

  • Importing existing BlockNote content into a YJS document for collaboration
  • Exporting content from a YJS document back to BlockNote blocks
  • Working with YJS documents programmatically without an active editor instance

Converting Blocks to YJS Documents

blocksToYDoc

Converts BlockNote blocks into a Y.Doc. This is useful when importing existing content to a Y.Doc for the first time.

Important: This should not be used to rehydrate a Y.Doc from a database once collaboration has begun, as all history will be lost.

function blocksToYDoc<
  BSchema extends BlockSchema,
  ISchema extends InlineContentSchema,
  SSchema extends StyleSchema,
>(
  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
  blocks: PartialBlock<BSchema, ISchema, SSchema>[],
  xmlFragment?: string,
): Y.Doc;

Parameters:

  • editor - The BlockNote editor instance
  • blocks - Array of blocks to convert
  • xmlFragment - Optional XML fragment name (defaults to "prosemirror")

Returns: A new Y.Doc containing the converted blocks

Example:

import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc } from "@blocknote/core/yjs";
import * as Y from "yjs";

const editor = BlockNoteEditor.create();

const blocks = [
  {
    type: "paragraph",
    content: "Hello, world!",
  },
  {
    type: "heading",
    props: { level: 1 },
    content: "My Document",
  },
];

// Convert blocks to Y.Doc
const ydoc = blocksToYDoc(editor, blocks);

// Now you can use this Y.Doc with a YJS provider for collaboration
const provider = new WebrtcProvider("my-room", ydoc);

blocksToYXmlFragment

Converts BlockNote blocks into a Y.XmlFragment. This is useful when you want to work with a specific XML fragment within a Y.Doc.

function blocksToYXmlFragment<
  BSchema extends BlockSchema,
  ISchema extends InlineContentSchema,
  SSchema extends StyleSchema,
>(
  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
  blocks: Block<BSchema, ISchema, SSchema>[],
  xmlFragment?: Y.XmlFragment,
): Y.XmlFragment;

Parameters:

  • editor - The BlockNote editor instance
  • blocks - Array of blocks to convert
  • xmlFragment - Optional existing Y.XmlFragment to populate (creates new one if not provided)

Returns: A Y.XmlFragment containing the converted blocks

Example:

import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYXmlFragment } from "@blocknote/core/yjs";
import * as Y from "yjs";

const editor = BlockNoteEditor.create();
const doc = new Y.Doc();
const fragment = doc.getXmlFragment("my-fragment");

const blocks = [
  {
    type: "paragraph",
    content: "Content for fragment",
  },
];

// Convert blocks to the XML fragment
blocksToYXmlFragment(editor, blocks, fragment);

Converting YJS Documents to Blocks

yDocToBlocks

Converts a Y.Doc back into BlockNote blocks. This is useful for reading content from a YJS document.

function yDocToBlocks<
  BSchema extends BlockSchema,
  ISchema extends InlineContentSchema,
  SSchema extends StyleSchema,
>(
  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
  ydoc: Y.Doc,
  xmlFragment?: string,
): Block<BSchema, ISchema, SSchema>[];

Parameters:

  • editor - The BlockNote editor instance
  • ydoc - The Y.Doc to convert
  • xmlFragment - Optional XML fragment name (defaults to "prosemirror")

Returns: Array of BlockNote blocks

Example:

import { BlockNoteEditor } from "@blocknote/core";
import { yDocToBlocks } from "@blocknote/core/yjs";
import * as Y from "yjs";

const editor = BlockNoteEditor.create();
const ydoc = new Y.Doc();

// ... Y.Doc is populated through collaboration or other means ...

// Convert Y.Doc back to blocks
const blocks = yDocToBlocks(editor, ydoc);

console.log(blocks); // Array of BlockNote blocks

yXmlFragmentToBlocks

Converts a Y.XmlFragment back into BlockNote blocks.

function yXmlFragmentToBlocks<
  BSchema extends BlockSchema,
  ISchema extends InlineContentSchema,
  SSchema extends StyleSchema,
>(
  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
  xmlFragment: Y.XmlFragment,
): Block<BSchema, ISchema, SSchema>[];

Parameters:

  • editor - The BlockNote editor instance
  • xmlFragment - The Y.XmlFragment to convert

Returns: Array of BlockNote blocks

Example:

import { BlockNoteEditor } from "@blocknote/core";
import { yXmlFragmentToBlocks } from "@blocknote/core/yjs";
import * as Y from "yjs";

const editor = BlockNoteEditor.create();
const doc = new Y.Doc();
const fragment = doc.getXmlFragment("my-fragment");

// ... Fragment is populated through collaboration or other means ...

// Convert fragment back to blocks
const blocks = yXmlFragmentToBlocks(editor, fragment);

Prosemirror Conversions

_blocksToProsemirrorNode

Converts BlockNote blocks to a Prosemirror node. This is an intermediate conversion step used internally.

function _blocksToProsemirrorNode<
  BSchema extends BlockSchema,
  ISchema extends InlineContentSchema,
  SSchema extends StyleSchema,
>(
  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
  blocks: PartialBlock<BSchema, ISchema, SSchema>[],
): Node;

Parameters:

  • editor - The BlockNote editor instance
  • blocks - Array of blocks to convert

Returns: Prosemirror root node

_prosemirrorJSONToBlocks

Converts Prosemirror JSON to BlockNote blocks.

function _prosemirrorJSONToBlocks<
  BSchema extends BlockSchema,
  ISchema extends InlineContentSchema,
  SSchema extends StyleSchema,
>(
  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
  json: any,
): Block<BSchema, ISchema, SSchema>[];

Parameters:

  • editor - The BlockNote editor instance
  • json - Prosemirror JSON object

Returns: Array of BlockNote blocks

Complete Example: Importing Existing Content

Here's a complete example showing how to import existing BlockNote content into a YJS document for collaboration:

import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc, yDocToBlocks } from "@blocknote/core/yjs";
import { WebrtcProvider } from "y-webrtc";
import * as Y from "yjs";

// Create editor
const editor = BlockNoteEditor.create();

// Existing content you want to import
const existingBlocks = [
  {
    type: "heading",
    props: { level: 1 },
    content: "Welcome to Collaboration",
  },
  {
    type: "paragraph",
    content: "This content will be synced across all users.",
  },
];

// Convert blocks to Y.Doc
const ydoc = blocksToYDoc(editor, existingBlocks);

// Set up collaboration provider
const provider = new WebrtcProvider("my-room", ydoc);

// Create editor with collaboration
const collaborativeEditor = BlockNoteEditor.create({
  collaboration: {
    provider,
    fragment: ydoc.getXmlFragment("prosemirror"),
    user: {
      name: "User 1",
      color: "#ff0000",
    },
  },
});

// Later, you can read the content back
const currentBlocks = yDocToBlocks(editor, ydoc);
console.log("Current document:", currentBlocks);

Round-trip Conversion

All conversion functions support round-trip conversion, meaning you can convert blocks → YJS → blocks and get back the same content:

import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc, yDocToBlocks } from "@blocknote/core/yjs";

const editor = BlockNoteEditor.create();

const originalBlocks = [
  {
    type: "paragraph",
    content: "Test content",
  },
];

// Convert to Y.Doc and back
const ydoc = blocksToYDoc(editor, originalBlocks);
const convertedBlocks = yDocToBlocks(editor, ydoc);

// originalBlocks and convertedBlocks are equivalent
console.log(originalBlocks); // Same structure as convertedBlocks

Cursor & Selections

Handle cursor positions and text selections in the editor

Events

BlockNote emits events when certain actions occur in the editor