Lexical Editor

The @veltdev/lexical-crdt-react and @veltdev/lexical-crdt libraries enable real-time collaborative editing on Lexical Editors. The collaboration editing engine is built on top of Yjs, the official @lexical/yjs binding, and Velt SDK.

Prerequisites

Node.js (v14 or higher)
A Velt account with an API key (sign up)
React (v18 or higher) when using the React wrapper
Optional: TypeScript for type safety

Setup

Step 1: Install Dependencies

Install the required packages:

React / Next.js
Other Frameworks

npm install @veltdev/lexical-crdt-react @veltdev/lexical-crdt @veltdev/react lexical @lexical/react @lexical/rich-text @lexical/yjs yjs y-protocols

npm install @veltdev/lexical-crdt @veltdev/client lexical @lexical/rich-text @lexical/yjs yjs

Install any additional @lexical/* node packages required by your schema. Keep one copy of lexical, every @lexical/* package, and yjs in the final application bundle.

Step 2: Setup Velt

Initialize Velt, authenticate a user, and set a stable document context before collaboration starts. Follow the Velt Setup Docs for the production token endpoint used by authProvider.

React / Next.js
Other Frameworks

import { useEffect, useState } from 'react';
import {
  VeltProvider,
  useCurrentUser,
  useSetDocuments,
} from '@veltdev/react';

const DOCUMENT_ID = 'my-lexical-editor';
const USER = {
  userId: 'user-1',
  name: 'John Doe',
  email: 'john@example.com',
  organizationId: 'org-1',
};

const authProvider = {
  user: USER,
  retryConfig: { retryCount: 3, retryDelay: 1000 },
  generateToken: async () => {
    const response = await fetch('/api/velt/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(USER),
    });
    const { token } = await response.json();
    return token;
  },
};

function CollaborationScope() {
  const user = useCurrentUser();
  const { setDocuments } = useSetDocuments();
  const [documentReady, setDocumentReady] = useState(false);

  useEffect(() => {
    if (!user) {
      setDocumentReady(false);
      return;
    }
    setDocuments([{
      id: DOCUMENT_ID,
      metadata: { documentName: 'Shared Lexical Document' },
    }]);
    setDocumentReady(true);
  }, [user, setDocuments]);

  return user && documentReady
    ? <LexicalEditor documentId={DOCUMENT_ID} />
    : <p>Preparing collaboration...</p>;
}

<VeltProvider apiKey="YOUR_API_KEY" authProvider={authProvider}>
  <CollaborationScope />
</VeltProvider>

Create one Velt client, set the shared document, authenticate the user, and wait for Velt before creating Lexical:

import { initVelt } from '@veltdev/client';

const DOCUMENT_ID = 'my-lexical-editor';
const client = await initVelt('YOUR_API_KEY');

client.setDocument(DOCUMENT_ID, {
  documentName: 'Shared Lexical Document',
});

await client.identify({
  userId: 'user-1',
  name: 'John Doe',
  email: 'john@example.com',
  organizationId: 'org-1',
});

const initSubscription = client.getVeltInitState().subscribe((isReady) => {
  if (isReady) void initializeLexical(client);
});

Step 3: Initialize Collaborative Editor

Set the Lexical composer’s editorState to null because collaboration owns the document state.
Add the collaboration hook or plugin inside <LexicalComposer> so it can read the editor from LexicalComposerContext.
Pass an editorId to uniquely identify each editor instance you have in your app.

React Component
React Hook
Other Frameworks

Use LexicalCollaborationPlugin when you only need lifecycle wiring and do not need to render reactive collaboration state:

import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
import { LexicalCollaborationPlugin } from '@veltdev/lexical-crdt-react';

const initialConfig = {
  namespace: 'my-collab-editor',
  editorState: null,
  onError: console.error,
};

function LexicalEditor() {
  return (
    <LexicalComposer initialConfig={initialConfig}>
      <LexicalCollaborationPlugin editorId="my-lexical-editor" />
      <RichTextPlugin
        contentEditable={<ContentEditable className="lexical-editor" />}
        placeholder={<div>Start typing...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}

Use useLexicalComposerCollaboration() inside the composer when you need reactive collaboration state.

import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
import { HeadingNode, QuoteNode } from '@lexical/rich-text';
import { useLexicalComposerCollaboration } from '@veltdev/lexical-crdt-react';

const theme = {
  collaboration: {
    cursor: 'lexical-collaboration-cursor',
    cursorName: 'lexical-collaboration-cursor-name',
    selection: 'lexical-collaboration-selection',
    selectionBg: 'lexical-collaboration-selection-bg',
  },
};

const initialConfig = {
  namespace: 'my-collab-editor',
  nodes: [HeadingNode, QuoteNode],
  theme,
  editorState: null,
  onError: console.error,
};

function CollaborationBridge({ documentId }: { documentId: string }) {
  const { isLoading, isSynced, status, error } = useLexicalComposerCollaboration({
    editorId: documentId,
    cursorData: {
      name: 'Michael',
      awarenessData: { userId: 'michael' },
    },
  });

  if (error) return <div>Error: {error.message}</div>;
  return <div>Status: {isLoading ? 'loading' : status} {isSynced ? '(synced)' : ''}</div>;
}

function LexicalEditor({ documentId }: { documentId: string }) {
  return (
    <LexicalComposer initialConfig={initialConfig}>
      <CollaborationBridge documentId={documentId} />
      <RichTextPlugin
        contentEditable={<ContentEditable className="lexical-editor" />}
        placeholder={<div>Start typing...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}

Set editorState: null in the Lexical composer. Providing a separate composer state can conflict with the shared CRDT document.

Create and configure Lexical first, attach its root element, and only then pass the editor to createCollaboration():

import { createEditor } from 'lexical';
import {
  HeadingNode,
  QuoteNode,
  registerRichText,
} from '@lexical/rich-text';
import {
  createCollaboration,
  type CollaborationManager,
} from '@veltdev/lexical-crdt';

let editor: ReturnType<typeof createEditor> | null = null;
let manager: CollaborationManager | null = null;
let unregisterRichText: (() => void) | null = null;
let offStatus: (() => void) | null = null;
let offSynced: (() => void) | null = null;

async function initializeLexical(client) {
  if (manager) return;

  editor = createEditor({
    namespace: 'my-collab-editor',
    nodes: [HeadingNode, QuoteNode],
    onError: console.error,
  });

  editor.setRootElement(document.querySelector('#editor'));
  unregisterRichText = registerRichText(editor);

  manager = await createCollaboration({
    editorId: DOCUMENT_ID,
    editor,
    veltClient: client,
    cursorData: { name: 'John Doe', color: '#7c3aed' },
    onError: (error) => console.error('Collaboration error:', error),
  });

  offStatus = manager.onStatusChange((status) => console.log('Status:', status));
  offSynced = manager.onSynced((synced) => console.log('Synced:', synced));
}

function destroyLexical() {
  offStatus?.();
  offSynced?.();
  manager?.destroy();
  unregisterRichText?.();
  editor?.setRootElement(null);
  manager = null;
  editor = null;
}

Do not register Lexical’s history plugin. The collaboration manager exposes the binding’s Y.UndoManager through manager.getUndoManager() so local undo/redo remains collaboration-aware.

Step 4: Use an Explicit Editor Instance in React (Optional)

If you create and hold a LexicalEditor instance outside LexicalComposer, use useCollaboration() and pass the instance explicitly:

import { useCollaboration } from '@veltdev/lexical-crdt-react';

const { primitives, isLoading, isSynced, status, error, manager } = useCollaboration({
  editorId: 'my-lexical-editor',
  editor: myLexicalEditor,
});

Step 5: Status Monitoring (Optional)

React / Next.js
Other Frameworks

Both hooks return reactive status, isSynced, and error state:

const { isLoading, isSynced, status, error, manager } =
  useLexicalComposerCollaboration({
    editorId: 'my-lexical-editor',
  });

if (error) return <div>Error: {error.message}</div>;
if (isLoading) return <div>Connecting...</div>;

// In your JSX
<div>Status: {status} | Synced: {isSynced ? 'Yes' : 'No'}</div>

For event-style subscriptions, use the manager:

useEffect(() => {
  if (!manager) return;

  const offStatus = manager.onStatusChange((nextStatus) => {
    console.log('Status:', nextStatus);
  });
  const offSynced = manager.onSynced((synced) => {
    console.log('Synced:', synced);
  });

  return () => {
    offStatus();
    offSynced();
  };
}, [manager]);

Read the current values or subscribe to changes on the manager. Save and call both unsubscribe functions during cleanup:

console.log(manager.initialized, manager.status, manager.synced);

const offStatus = manager.onStatusChange((status) => {
  console.log('Status:', status);
});

const offSynced = manager.onSynced((synced) => {
  console.log('Synced:', synced);
});

// During teardown
offStatus();
offSynced();

Step 6: Version Management (Optional)

Save and restore named snapshots through the manager. Restored versions are applied to every connected user in real time.

if (!manager) return;

const versionId = await manager.saveVersion('Before major edit');
const versions = await manager.getVersions();
await manager.restoreVersion(versionId);

When your application already has the complete Version object, use the lower-level state application API instead of restoreVersion():

const selectedVersion = versions.find((version) => version.versionId === versionId);
if (selectedVersion) {
  await manager.setStateFromVersion(selectedVersion);
}

Step 7: Force Reset Initial Content (Optional)

By default, initialContent is applied exactly once when the shared document is brand new. Use a stringified serialized Lexical editor state. React wrappers may also accept the wrapper’s documented plain-text convenience form.

React / Next.js
Other Frameworks

useLexicalComposerCollaboration({
  editorId: 'my-lexical-editor',
  initialContent,
  forceResetInitialContent: true,
});

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  editor,
  veltClient: client,
  initialContent: JSON.stringify({
    root: {
      children: [{
        children: [{
          detail: 0,
          format: 0,
          mode: 'normal',
          style: '',
          text: 'Start writing…',
          type: 'text',
          version: 1,
        }],
        direction: null,
        format: '',
        indent: 0,
        type: 'paragraph',
        version: 1,
      }],
      direction: null,
      format: '',
      indent: 0,
      type: 'root',
      version: 1,
    },
  }),
  forceResetInitialContent: false,
});

Use forceResetInitialContent only for deliberate reset workflows. It clears the current shared document and replaces it with initialContent for every connected user.

Step 8: Style Collaboration Cursors

Remote carets, labels, and text selections render through Lexical’s collaboration cursor layer. Pass user identity through cursorData, then style the Lexical collaboration theme classes:

React / Next.js
Other Frameworks

useLexicalComposerCollaboration({
  editorId: 'my-lexical-editor',
  cursorData: {
    name: user.name,
    color: '#7c3aed',
    awarenessData: { userId: user.userId },
  },
});

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  editor,
  veltClient: client,
  cursorData: {
    name: 'John Doe',
    color: '#7c3aed',
    awarenessData: { role: 'editor' },
  },
});

[data-lexical-cursors='true'] {
  pointer-events: none;
}

.lexical-collaboration-selection {
  mix-blend-mode: multiply;
  z-index: 4;
}

.lexical-collaboration-selection-bg {
  background-color: rgba(250, 204, 21, 0.4);
  border-radius: 2px;
}

.lexical-collaboration-cursor {
  background-color: var(--lexical-cursor-color, #7c3aed);
  width: 2px;
  z-index: 10;
}

.lexical-collaboration-cursor-name {
  position: absolute;
  top: -1.4rem;
  left: -1px;
  padding: 0.15rem 0.35rem;
  color: #fff;
  background-color: var(--lexical-cursor-color, #7c3aed);
  border-radius: 3px;
  font-size: 0.7rem;
  white-space: nowrap;
}

Step 9: CRDT Event Subscription (Optional)

Listen for real-time CRDT data events using getCrdtElement().on() from the Velt client.

React / Next.js
Other Frameworks

import { useEffect } from 'react';
import { useVeltClient } from '@veltdev/react';

const { client } = useVeltClient();

useEffect(() => {
  if (!client) return;

  const subscription = client.getCrdtElement().on('updateData').subscribe((event) => {
    if (event) console.log('CRDT update:', event);
  });

  return () => subscription?.unsubscribe?.();
}, [client]);

const crdtSubscription = client
  .getCrdtElement()
  .on('updateData')
  .subscribe((event) => {
    if (event) console.log('CRDT update:', event);
  });

// During teardown
crdtSubscription.unsubscribe();

Step 10: Custom Encryption (Optional)

Encrypt CRDT data before it is stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type Uint8Array | number[].

React / Next.js
Other Frameworks

const encryptionProvider = {
  encrypt: async ({ data }) => data.map((n) => n.toString()).join('__'),
  decrypt: async ({ data }) => data.split('__').map((s) => parseInt(s, 10)),
};

<VeltProvider
  apiKey="YOUR_API_KEY"
  authProvider={authProvider}
  encryptionProvider={encryptionProvider}
>
  ...
</VeltProvider>

Call setEncryptionProvider() before creating the collaboration manager:

client.setEncryptionProvider({
  encrypt: async ({ data }) => data.map((n) => n.toString()).join('__'),
  decrypt: async ({ data }) => data.split('__').map((s) => parseInt(s, 10)),
});

Step 11: Error Handling (Optional)

Pass an onError callback to handle initialization or runtime errors. The reactive error state is also available for rendering.

React / Next.js
Other Frameworks

const collab = useLexicalComposerCollaboration({
  editorId: 'my-lexical-editor',
  onError: (error) => console.error('Collaboration error:', error),
});

if (collab.error) {
  return <div>Error: {collab.error.message}</div>;
}

const manager = await createCollaboration({
  editorId: DOCUMENT_ID,
  editor,
  veltClient: client,
  onError: (error) => console.error('Lexical collaboration error:', error),
});

The package reports unexpected failures through onError; manager getters and version methods return null-safe or empty fallback values instead of throwing.

Step 12: Access Yjs Internals (Advanced)

The hooks return lower-level Lexical, Yjs, and Velt handles through primitives:

React / Next.js
Other Frameworks

const { primitives, manager } = useLexicalComposerCollaboration({
  editorId: 'my-lexical-editor',
});

const editor = primitives?.editor;
const binding = primitives?.binding;
const doc = primitives?.doc;
const xmlText = primitives?.xmlText;
const provider = primitives?.provider;
const lexicalProvider = primitives?.lexicalProvider;
const awareness = primitives?.awareness;
const undoManager = primitives?.undoManager;
const store = primitives?.store;

// The same handles are available from the manager.
manager?.getEditor();
manager?.getBinding();
manager?.getDoc();
manager?.getXmlText();
manager?.getProvider();
manager?.getLexicalProvider();
manager?.getAwareness();
manager?.getUndoManager();
manager?.getStore();

const editor = manager.getEditor();
const binding = manager.getBinding();
const doc = manager.getDoc();
const xmlText = manager.getXmlText();
const provider = manager.getProvider();
const lexicalProvider = manager.getLexicalProvider();
const awareness = manager.getAwareness();
const undoManager = manager.getUndoManager();
const store = manager.getStore();

Let the manager own binding setup, provider attachment, awareness, and Yjs history. Do not wire @lexical/yjs manually alongside it.

Step 13: Cleanup

React / Next.js
Other Frameworks

The hooks destroy the manager automatically when the component unmounts or when the editorId, editor, or Velt client changes. Pass enabled: false to tear down collaboration early while keeping the component mounted.

const collab = useLexicalComposerCollaboration({
  editorId: 'my-lexical-editor',
  enabled: collaborationEnabled,
});

Unsubscribe callbacks and destroy collaboration before discarding the Lexical editor:

crdtSubscription.unsubscribe();
offStatus();
offSynced();
initSubscription.unsubscribe();

manager.destroy();
unregisterRichText();
editor.setRootElement(null);

manager.destroy() removes the cursor overlay, provider/store resources, binding, undo manager, and listeners. It is safe to call more than once.

Notes

Unique editorId: Use a unique editorId per editor instance.
Composer state: Set editorState: null because collaboration owns the shared Lexical state.
Composer hook: Use useLexicalComposerCollaboration() inside <LexicalComposer>.
Explicit editor: Use useCollaboration() only when you already hold a LexicalEditor instance.
Plugin form: Use LexicalCollaborationPlugin when you do not need reactive status, error, or manager values.
Cursor identity: Pass cursorData so remote carets and selections can display user information.
Lifecycle: The hooks wait for the Lexical root element, Velt initialization, and an authenticated user before creating the manager.
Other Frameworks lifecycle: Create and attach Lexical first, then create one manager; destroy the manager before discarding the editor.
Collaborative history: Do not register Lexical’s normal history plugin. Use the binding’s Yjs-backed undo manager from manager.getUndoManager().
Debounced writes: The Store default is debounceMs: 0, so backend writes are immediate when the option is omitted. Lexical’s separate snapshot-flush scheduler falls back to 250 ms after applying seeded or prefetched snapshot state.
Dependency deduplication: Keep one copy of lexical, each @lexical/* package, and yjs in the application bundle.
Production authentication: Do not expose privileged server tokens in browser code; use Velt’s recommended server-backed authentication flow.

Testing and Debugging

To test collaboration:

Log in as two unique users in two separate browser profiles and open the same Velt document and Lexical editorId in both.
Edit text, formatting, headings, or lists in one window and verify the changes and remote cursor appear in the other.
Make concurrent edits and verify they merge at the character level.
Reload both windows and verify the shared document persists.

Common issues:

Editor not loading: Confirm the Velt client is initialized, the user is authenticated, and the collaboration bridge renders inside <LexicalComposer>.
Initial content conflicts: Set the composer’s editorState to null.
Cursors not appearing: Pass cursorData and include the Lexical collaboration theme classes in your editor theme and CSS.
Changes not syncing: Confirm both users have the same Velt document context and editorId.
Manual reconnect: Use manager.getProvider()?.connect() to reconnect or manager.getProvider()?.disconnect() to test an offline transition.

Enable browser console warnings to see detailed debugging information. You can also use the VeltCrdtStoreMap debugging interface to inspect and monitor your CRDT stores in real time.

Complete Example

React / Next.js
Other Frameworks

A complete collaborative Lexical editor with user login, status display, cursor identity, and version management.App.tsx

Complete App.tsx

import { useEffect, useMemo, useState } from 'react';
import {
  VeltProvider,
  useCurrentUser,
  useSetDocuments,
} from '@veltdev/react';
import { CollaborativeEditor, DOCUMENT_ID } from './Editor';

const USER = {
  userId: 'michael',
  name: 'Michael Scott',
  email: 'michael.scott@dundermifflin.com',
  organizationId: 'my-org-id',
  color: '#7c3aed',
};

function AppContent() {
  const veltUser = useCurrentUser();
  const { setDocuments } = useSetDocuments();
  const [documentReady, setDocumentReady] = useState(false);

  useEffect(() => {
    if (!veltUser) {
      setDocumentReady(false);
      return;
    }
    setDocuments([{
      id: DOCUMENT_ID,
      metadata: { documentName: 'Lexical CRDT React Demo' },
    }]);
    setDocumentReady(true);
  }, [veltUser, setDocuments]);

  return (
    <div>
      {veltUser && documentReady ? (
        <CollaborativeEditor key={veltUser.userId} />
      ) : (
        <p>Preparing collaboration...</p>
      )}
    </div>
  );
}

export default function App() {
  const authProvider = useMemo(() => ({
    user: USER,
    retryConfig: { retryCount: 3, retryDelay: 1000 },
    generateToken: async () => {
      const response = await fetch('/api/velt/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(USER),
      });
      const { token } = await response.json();
      return token;
    },
  }), []);

  return (
    <VeltProvider apiKey="YOUR_API_KEY" authProvider={authProvider}>
      <AppContent />
    </VeltProvider>
  );
}

Editor.tsx

Complete Editor.tsx

import { useState } from 'react';
import { useCurrentUser } from '@veltdev/react';
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
import { HeadingNode, QuoteNode } from '@lexical/rich-text';
import { useLexicalComposerCollaboration } from '@veltdev/lexical-crdt-react';

export const DOCUMENT_ID = 'lexical-crdt-react-demo-doc-1';

const theme = {
  collaboration: {
    cursor: 'lexical-collaboration-cursor',
    cursorName: 'lexical-collaboration-cursor-name',
    selection: 'lexical-collaboration-selection',
    selectionBg: 'lexical-collaboration-selection-bg',
  },
};

function CollaborationBridge() {
  const veltUser = useCurrentUser();
  const [versionName, setVersionName] = useState('');

  const {
    isLoading,
    isSynced,
    status,
    error,
    manager,
  } = useLexicalComposerCollaboration({
    editorId: DOCUMENT_ID,
    cursorData: veltUser
      ? {
          name: veltUser.name,
          color: '#7c3aed',
          awarenessData: { userId: veltUser.userId },
        }
      : undefined,
    onError: (err) => console.error('Collaboration error:', err),
  });

  const saveVersion = async (event: React.FormEvent) => {
    event.preventDefault();
    if (!manager || !versionName.trim()) return;
    await manager.saveVersion(versionName.trim());
    setVersionName('');
  };

  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <div>Status: {isLoading ? 'loading' : status} {isSynced ? '(synced)' : ''}</div>
      <form onSubmit={saveVersion}>
        <input
          value={versionName}
          onChange={(event) => setVersionName(event.target.value)}
          placeholder="Version name..."
        />
        <button type="submit" disabled={!manager}>Save Version</button>
      </form>
    </div>
  );
}

export function CollaborativeEditor() {
  return (
    <LexicalComposer
      initialConfig={{
        namespace: 'lexical-collab-demo',
        nodes: [HeadingNode, QuoteNode],
        theme,
        editorState: null,
        onError: console.error,
      }}
    >
      <CollaborationBridge />
      <RichTextPlugin
        contentEditable={<ContentEditable className="lexical-editor" />}
        placeholder={<div>Start typing...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}

This vanilla TypeScript example creates Lexical before the manager, uses collaborative undo/redo, monitors status, subscribes to CRDT events, and tears down every listener explicitly.

<div id="status">Connecting...</div>
<div id="editor" class="lexical-editor" contenteditable="true"></div>
<button id="undo">Undo</button>
<button id="redo">Redo</button>
<button id="save-version">Save version</button>

Complete main.ts

import { createEditor, type LexicalEditor } from 'lexical';
import {
  HeadingNode,
  QuoteNode,
  registerRichText,
} from '@lexical/rich-text';
import { initVelt } from '@veltdev/client';
import {
  createCollaboration,
  type CollaborationManager,
} from '@veltdev/lexical-crdt';

const API_KEY = 'YOUR_API_KEY';
const DOCUMENT_ID = 'lexical-crdt-demo-doc-1';

let editor: LexicalEditor | null = null;
let manager: CollaborationManager | null = null;
let unregisterRichText: (() => void) | null = null;
let offStatus: (() => void) | null = null;
let offSynced: (() => void) | null = null;
let initSubscription: { unsubscribe(): void } | null = null;
let crdtSubscription: { unsubscribe(): void } | null = null;

const undo = () => manager?.getUndoManager()?.undo();
const redo = () => manager?.getUndoManager()?.redo();
const saveVersion = () => {
  void manager?.saveVersion('Manual checkpoint');
};

const initialContent = JSON.stringify({
  root: {
    children: [{
      children: [{
        detail: 0,
        format: 0,
        mode: 'normal',
        style: '',
        text: 'Start writing…',
        type: 'text',
        version: 1,
      }],
      direction: null,
      format: '',
      indent: 0,
      type: 'paragraph',
      version: 1,
    }],
    direction: null,
    format: '',
    indent: 0,
    type: 'root',
    version: 1,
  },
});

async function main() {
  const client = await initVelt(API_KEY);

  client.setDocument(DOCUMENT_ID, {
    documentName: 'Shared Lexical Document',
  });

  await client.identify({
    userId: 'ada',
    name: 'Ada Lovelace',
    email: 'ada@example.com',
    organizationId: 'my-org-id',
  });

  initSubscription = client.getVeltInitState().subscribe(async (isReady) => {
    if (!isReady || manager) return;

    editor = createEditor({
      namespace: 'lexical-collab-demo',
      nodes: [HeadingNode, QuoteNode],
      onError: console.error,
    });
    editor.setRootElement(document.querySelector('#editor'));
    unregisterRichText = registerRichText(editor);

    manager = await createCollaboration({
      editorId: DOCUMENT_ID,
      editor,
      veltClient: client,
      initialContent,
      cursorData: {
        name: 'Ada Lovelace',
        color: '#7c3aed',
        awarenessData: { userId: 'ada' },
      },
      onError: (error) => console.error('Collaboration error:', error),
    });

    const renderStatus = () => {
      const element = document.getElementById('status');
      if (element && manager) {
        element.textContent = `${manager.status} / synced: ${manager.synced}`;
      }
    };

    renderStatus();
    offStatus = manager.onStatusChange(renderStatus);
    offSynced = manager.onSynced(renderStatus);

    crdtSubscription = client
      .getCrdtElement()
      .on('updateData')
      .subscribe((event) => console.log('CRDT update:', event));

    document.getElementById('undo')?.addEventListener('click', undo);
    document.getElementById('redo')?.addEventListener('click', redo);
    document.getElementById('save-version')?.addEventListener('click', saveVersion);
  });
}

export function destroy() {
  document.getElementById('undo')?.removeEventListener('click', undo);
  document.getElementById('redo')?.removeEventListener('click', redo);
  document.getElementById('save-version')?.removeEventListener('click', saveVersion);
  crdtSubscription?.unsubscribe();
  crdtSubscription = null;
  offStatus?.();
  offStatus = null;
  offSynced?.();
  offSynced = null;
  initSubscription?.unsubscribe();
  initSubscription = null;

  manager?.destroy();
  manager = null;
  unregisterRichText?.();
  unregisterRichText = null;
  editor?.setRootElement(null);
  editor = null;
}

window.addEventListener('pagehide', destroy, { once: true });
void main();

Do not add Lexical’s history plugin to this example. The remote cursor overlay is created and removed automatically by the collaboration manager.

How It Works

Velt initialization and authentication happen through VeltProvider in React or initVelt() and identify() in other frameworks. Both paths establish the same stable document context.
React wrappers obtain the editor from LexicalComposerContext or accept an explicit editor. Other frameworks create the Lexical editor, register its nodes, and attach its root before creating collaboration.
The collaboration manager creates a Velt CRDT store backed by a Yjs document and a shared Y.XmlText.
The official @lexical/yjs binding connects Lexical updates to the shared Y.XmlText, so text, formatting, headings, and concurrent edits merge at the character level.
Yjs awareness drives the manager-owned remote cursor overlay, while the binding’s Y.UndoManager provides collaboration-aware undo and redo.
Version management saves the complete Yjs state as a named snapshot that can be restored for every connected user.
React cleanup is automatic when the wrapper unmounts or collaboration is disabled. Other frameworks unsubscribe callbacks and destroy the manager before discarding Lexical.

APIs

React: useLexicalComposerCollaboration()

The primary hook for applications using <LexicalComposer>. It reads the editor from context, waits for the root element, and manages the collaboration lifecycle.

Signature: useLexicalComposerCollaboration(config: UseLexicalComposerCollaborationConfig): UseCollaborationReturn
Alias: useLexicalCollaboration
Params:
- editorId: Unique identifier for the collaborative editor.
- veltClient: Optional explicit Velt client. Falls back to VeltProvider context.
- enabled: Delay initialization or destroy active collaboration. Default: true.
- initialContent: Serialized Lexical editor state or plain text for a brand-new document.
- forceResetInitialContent: Replace existing shared content during initialization. Default: false.
- cursorData: Cursor name, color, and custom awareness data.
- debounceMs: Throttle interval in milliseconds for backend writes. Store default: 0 ms (immediate). The internal snapshot-flush scheduler separately falls back to 250 ms when this option is omitted.
- onError: Callback for non-fatal collaboration errors.
Returns:
- primitives: Lexical, Yjs, and Velt integration handles. null while loading.
- isLoading: true until the manager is initialized.
- isSynced: true after initial backend sync completes.
- status: 'connecting', 'connected', or 'disconnected'.
- error: Most recent error, or null.
- manager: Underlying CollaborationManager, or null before initialization.

React: useCollaboration()

Explicit-editor form of the React hook. It has the same lifecycle and return values, but requires an editor: LexicalEditor config value.

const collab = useCollaboration({
  editorId: 'my-lexical-editor',
  editor: myLexicalEditor,
});

React: LexicalCollaborationPlugin

Null-rendering component form of useLexicalComposerCollaboration(). Use it when you only need collaboration lifecycle wiring.

<LexicalCollaborationPlugin editorId="my-lexical-editor" />

Other Frameworks: createCollaboration()

The framework-agnostic createCollaboration() factory from @veltdev/lexical-crdt creates and initializes the manager for an existing LexicalEditor.

Signature: createCollaboration(config: CollaborationConfig): Promise<CollaborationManager>
Required config: editorId, editor, and an initialized, authenticated veltClient.
Optional config: initialContent, cursorData, debounceMs (Store default: 0 ms), forceResetInitialContent, and onError. The internal snapshot-flush scheduler separately falls back to 250 ms when debounceMs is omitted.
Cleanup: Call manager.destroy() before disposing the editor.

LexicalCollaborationPrimitives

Field	Type	Description
`editor`	`LexicalEditor \| null`	Bound Lexical editor instance.
`binding`	`Binding \| null`	Binding created by `@lexical/yjs`.
`lexicalProvider`	`Provider \| null`	Lexical-compatible adapter around Velt’s provider.
`doc`	`Y.Doc \| null`	Shared Yjs document.
`xmlText`	`Y.XmlText \| null`	Shared content type used by `@lexical/yjs`.
`provider`	`SyncProvider \| null`	Velt real-time sync provider.
`awareness`	`Awareness \| null`	Yjs awareness instance for remote users and cursors.
`undoManager`	`Y.UndoManager \| null`	Collaborative undo manager.
`store`	`Store<string> \| null`	Underlying Velt CRDT store.

LexicalProviderAdapter

LexicalProviderAdapter is exported from @veltdev/lexical-crdt. It adapts Velt’s SyncProvider events to the provider interface expected by @lexical/yjs; the collaboration manager creates it automatically, so most applications should access the existing adapter through manager.getLexicalProvider() instead of constructing another one.

Version

Field	Type	Description
`versionId`	`string`	Unique version identifier.
`versionName`	`string`	Human-readable version name.
`timestamp`	`number`	Time the version was saved, in epoch milliseconds.

CollaborationManager Methods

manager.onStatusChange()

Subscribe to connection status changes.

Signature: manager.onStatusChange(callback: (status: SyncStatus) => void): Unsubscribe

manager.onSynced()

Subscribe to initial sync state changes.

Signature: manager.onSynced(callback: (synced: boolean) => void): Unsubscribe

manager.initialized

Whether initialization has completed.

Returns: boolean

manager.synced

Whether initial backend sync has completed.

Returns: boolean

manager.status

Current connection status.

Returns: SyncStatus ('connecting' | 'connected' | 'disconnected')

manager.saveVersion()

Save a named snapshot and return its version ID.

Signature: manager.saveVersion(name: string): Promise<string>

manager.getVersions()

List all saved versions.

Returns: Promise<Version[]>

manager.restoreVersion()

Restore a saved version for all connected users.

Signature: manager.restoreVersion(versionId: string): Promise<boolean>

manager.setStateFromVersion()

Apply a Version object’s state to the shared document.

Signature: manager.setStateFromVersion(version: Version): Promise<void>

manager.getEditor()

Get the bound Lexical editor.

Returns: LexicalEditor | null

manager.getBinding()

Get the @lexical/yjs binding.

Returns: Binding | null

manager.getLexicalProvider()

Get the provider adapter used by the Lexical binding.

Returns: Provider | null

manager.getDoc()

Get the underlying Yjs document.

Returns: Y.Doc | null

manager.getXmlText()

Get the shared Y.XmlText bound to Lexical content.

Returns: Y.XmlText | null

manager.getXmlFragment()

Alias of getXmlText() provided for parity with other CRDT integrations.

Returns: Y.XmlText | null

manager.getProvider()

Get the Velt sync provider.

Returns: SyncProvider | null

manager.getAwareness()

Get the Yjs awareness instance.

Returns: Awareness | null

manager.getUndoManager()

Get the collaborative Yjs undo manager.

Returns: Y.UndoManager | null

manager.getStore()

Get the underlying Velt CRDT store.

Returns: Store<string> | null

manager.destroy()

Destroy the binding, provider adapter, awareness state, listeners, and store. The React hooks call this automatically.

Returns: void

Custom Encryption

Encrypt CRDT data before it is stored in Velt by registering a custom encryption provider.

<VeltProvider
  apiKey="YOUR_API_KEY"
  authProvider={authProvider}
  encryptionProvider={{
    encrypt: async ({ data }) => myEncrypt(data),
    decrypt: async ({ data }) => myDecrypt(data),
  }}
>
  ...
</VeltProvider>

Limitations

Content written through the CRDT REST API is not currently materialized into the Lexical editor. Browser-to-REST reads work, but REST-to-browser content does not.
Online and offline concurrent editor changes merge at the character level through the official @lexical/yjs binding.

​Prerequisites

​Setup

​Step 1: Install Dependencies

​Step 2: Setup Velt

​Step 3: Initialize Collaborative Editor

​Step 4: Use an Explicit Editor Instance in React (Optional)

​Step 5: Status Monitoring (Optional)

​Step 6: Version Management (Optional)

​Step 7: Force Reset Initial Content (Optional)

​Step 8: Style Collaboration Cursors

​Step 9: CRDT Event Subscription (Optional)

​Step 10: Custom Encryption (Optional)

​Step 11: Error Handling (Optional)

​Step 12: Access Yjs Internals (Advanced)

​Step 13: Cleanup

​Notes

​Testing and Debugging

​Complete Example

​How It Works

​APIs

​React: useLexicalComposerCollaboration()

​React: useCollaboration()

​React: LexicalCollaborationPlugin

​Other Frameworks: createCollaboration()

​LexicalCollaborationPrimitives

​LexicalProviderAdapter

​Version

​CollaborationManager Methods

​manager.onStatusChange()

​manager.onSynced()

​manager.initialized

​manager.synced

​manager.status

​manager.saveVersion()

​manager.getVersions()

​manager.restoreVersion()

​manager.setStateFromVersion()

​manager.getEditor()

​manager.getBinding()

​manager.getLexicalProvider()

​manager.getDoc()

​manager.getXmlText()

​manager.getXmlFragment()

​manager.getProvider()

​manager.getAwareness()

​manager.getUndoManager()

​manager.getStore()

​manager.destroy()

​Custom Encryption

​Limitations

Prerequisites

Setup

Step 1: Install Dependencies

Step 2: Setup Velt

Step 3: Initialize Collaborative Editor

Step 4: Use an Explicit Editor Instance in React (Optional)

Step 5: Status Monitoring (Optional)

Step 6: Version Management (Optional)

Step 7: Force Reset Initial Content (Optional)

Step 8: Style Collaboration Cursors

Step 9: CRDT Event Subscription (Optional)

Step 10: Custom Encryption (Optional)

Step 11: Error Handling (Optional)

Step 12: Access Yjs Internals (Advanced)

Step 13: Cleanup

Notes

Testing and Debugging

Complete Example

How It Works

APIs

React: useLexicalComposerCollaboration()

React: useCollaboration()

React: LexicalCollaborationPlugin

Other Frameworks: createCollaboration()

LexicalCollaborationPrimitives

LexicalProviderAdapter

Version

CollaborationManager Methods

manager.onStatusChange()

manager.onSynced()

manager.initialized

manager.synced

manager.status

manager.saveVersion()

manager.getVersions()

manager.restoreVersion()

manager.setStateFromVersion()

manager.getEditor()

manager.getBinding()

manager.getLexicalProvider()

manager.getDoc()

manager.getXmlText()

manager.getXmlFragment()

manager.getProvider()

manager.getAwareness()

manager.getUndoManager()

manager.getStore()

manager.destroy()

Custom Encryption

Limitations