Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 },
  },
});
Use modules.collaboration = { ydoc, provider } when the editor should start in collaboration mode. If you want to open the document locally first and create a shared room later, use superdoc.upgradeToCollaboration() instead.
​
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: 'john@example.com',
  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:
PropertyTypeDescription
clientIdnumberUnique session ID
namestringUser’s display name
emailstringUser’s email
colorstringAssigned cursor color (hex)

​
onLocked

Fired when the document is locked or unlocked. 
onLocked: ({ isLocked, lockedBy }) => {
  if (isLocked) {
    console.log("Document locked by:", lockedBy?.name);
  }
}
PropertyTypeDescription
isLockedbooleanWhether the document is locked
lockedByObjectUser 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();
  }
});