Sign in

Yjs

Liveblocks Yjs connects a Liveblocks room to a Y.Doc, including Yjs shared types and awareness. Liveblocks persists the Yjs document and synchronizes it between clients.

For new text editors, use LiveText

LiveText is our newer choice for text-editor integrations. It stores collaborative text directly in Storage, is much more efficient, and works with different editor adapters. Read text editing to compare the two approaches.

Y.Doc

Y.Doc is the core data structure used by Yjs. It is a JSON-like object that represents the state of a collaborative document. It is used to store the content of the document, and to synchronize it between clients. In Liveblocks, get the current room’s Y.Doc with getYjsProviderForRoom.

import { useRoom } from "@liveblocks/react";import { getYjsProviderForRoom } from "@liveblocks/yjs";
function App() {  const room = useRoom();  const yProvider = getYjsProviderForRoom(room);  const yDoc = yProvider.getYDoc();
  // ...}

Shared types

Shared types in Yjs are CRDT-backed data structures (like maps, arrays, and text) stored inside a Y.Doc that automatically synchronize and merge changes across multiple clients without conflicts.

import { useRoom } from "@liveblocks/react";import { getYjsProviderForRoom } from "@liveblocks/yjs";
function App() {  const room = useRoom();  const yProvider = getYjsProviderForRoom(room);  const yDoc = yProvider.getYDoc();
  const insertText = useCallback(() => {    const yText = yDoc.getText("editor"); // Y.Text    yText.insert(0, "Hello collaborative world");  }, []);
  const changeTheme = useCallback(() => {    const yMap = yDoc.getMap("settings"); // Y.Map    yMap.set("theme", "dark");  }, []);
  // ...}

Version history

Create version snapshots of your Yjs document, and let users browse, preview, and restore them. useHistoryVersions lists a room’s versions, and useHistoryVersionYjsData returns a version as a binary Yjs update, which you can apply to a fresh Y.Doc to read its contents.

import {  useHistoryVersions,  useHistoryVersionYjsData,} from "@liveblocks/react";import * as Y from "yjs";
function VersionHistory() {  const { versions } = useHistoryVersions();
  return (    <div>      {versions.map((version) => (        <div key={version.id}>          <time>{version.createdAt}</time>          <VersionPreview versionId={version.id} />        </div>      ))}    </div>}
function VersionPreview({ versionId }) {  const { data } = useHistoryVersionYjsData(versionId);
  // Apply the version's binary update to an empty Y.Doc  const yDoc = new Y.Doc();  Y.applyUpdate(yDoc, data);
  // ...}

If you’re using our Tiptap, BlockNote, or Lexical plugins, ready-made HistoryVersionPreview components preview and restore versions for you. Learn how to set this up in our version history guide.

Get started

Choose a starting point for your Yjs-backed editor.

How-to guides

API Reference

Examples