Configuration

All configuration options and events for real-time collaboration.

If you need to combine collaboration with headless SDK automation, see SDK collaboration sessions.

Configuration

You manage the Yjs provider — works with SuperDoc Yjs, Liveblocks, Hocuspocus, etc.

import * as Y from "yjs";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";

const ydoc = new Y.Doc();
const provider = new LiveblocksYjsProvider(room, ydoc);

new SuperDoc({
  selector: "#editor",
  modules: {
    collaboration: { ydoc, provider },
  },
});

modules.collaboration.ydoc · Y.Doc · required

Your Yjs document instance

modules.collaboration.provider · Object · required

Any Yjs-compatible provider

User configuration

user · Object · required

Current user information for presence/awareness

user: {
  name: 'John Smith',
  email: '[e-mail]',
  image: 'https://example.com/avatar.jpg'  // Optional
}

colors · string[]

Color palette for user cursors and selections. Users are automatically assigned colors from this palette.

colors: ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FFEAA7"];

Media upload

Handle image uploads in collaborative documents:

new SuperDoc({
  handleImageUpload: (file) => {
    return new Promise((resolve, reject) => {
      const reader = new FileReader();

      reader.onload = (event) => {
        const dataUrl = event.target.result;
        const mediaPath = `word/media/${file.name}`;

        // Store in Yjs for sync
        if (superdoc.ydoc) {
          const mediaMap = superdoc.ydoc.getMap("media");
          mediaMap.set(mediaPath, dataUrl);
        }

        resolve(dataUrl);
      };

      reader.onerror = reject;
      reader.readAsDataURL(file);
    });
  },
});

Events

onCollaborationReady

Fired when collaboration sync is complete.

onCollaborationReady: ({ editor }) => {
  console.log("Collaboration ready");
}

onAwarenessUpdate

Fired when users join, leave, or update their presence.

onAwarenessUpdate: ({ states, added, removed, superdoc }) => {
  console.log("Active users:", states);

  added.forEach((clientId) => {
    const user = states.find((s) => s.clientId === clientId);
    console.log("User joined:", user?.name);
  });

  removed.forEach((clientId) => {
    console.log("User left:", clientId);
  });
}

states array item properties:

Property	Type	Description
clientId	number	Unique session ID
name	string	User’s display name
email	string	User’s email
color	string	Assigned cursor color (hex)

onLocked

Fired when the document is locked or unlocked.

onLocked: ({ isLocked, lockedBy }) => {
  if (isLocked) {
    console.log("Document locked by:", lockedBy?.name);
  }
}

Property	Type	Description
isLocked	boolean	Whether the document is locked
lockedBy	Object	User who locked the document

Provider events

Listen to provider events directly for connection status:

provider.on("sync", (synced) => {
  if (synced) console.log("Document synced");
});

// For Hocuspocus/URL-based providers
provider.on("status", ({ status }) => {
  // 'connecting' | 'connected' | 'disconnected'
  updateConnectionIndicator(status);
});

provider.on("authenticationFailed", ({ reason }) => {
  if (reason === "token-expired") {
    refreshToken();
  }
});