Collaboration

Collaboration replicates the document across peers. Each peer edits a local replica, and the replicas converge. Local typing stays responsive during network delays.

Peers also share presence. You see each participant, caret, and selection in the participant's author color. The same color marks their tracked changes and comments.

The @docx-editor.dev/pro package provides collaboration as an editor module. You can use peer-to-peer WebRTC, a Hocuspocus server, or an existing Yjs provider.

The adapters provide room hooks, a wired collaboration root, status fields, and custom presence renderers. Server code can also export synchronized room state as DOCX bytes. The real-time collaboration guide documents these interfaces and their recovery behavior.

Start in one component

Use the framework hook to own the room. With create-or-join, the first peer seeds the room from your document bytes. Later peers join the room.

import { useRef } from 'react';
import { DocxEditor, type DocxEditorRef } from '@docx-editor.dev/react';
import { useWebrtcCollaboration } from '@docx-editor.dev/pro/react/webrtc';

interface CollaborativeEditorProps {
  roomId: string;
  bytes: Uint8Array;
}

export function CollaborativeEditor({ roomId, bytes }: CollaborativeEditorProps) {
  const editorRef = useRef<DocxEditorRef>(null);
  const { document, modules, session, pending, error, leave } = useWebrtcCollaboration({
    room: {
      roomId,
      identity: { actorId: 'alex', name: 'Alex' },
      bootstrap: { kind: 'create-or-join', document: bytes },
    },
  });

  async function leaveRoom() {
    const saved = await editorRef.current?.save();
    if (saved) {
      leave(new Uint8Array(saved));
    }
  }

  if (error) {
    return <p>{error.detail ?? error.code}</p>;
  }
  if (pending || !document) {
    return <p>Connecting…</p>;
  }

  return (
    <>
      <button type="button" onClick={leaveRoom}>
        Leave
      </button>
      <DocxEditor ref={editorRef} key={session?.sessionId} document={document} modules={modules} />
    </>
  );
}

Vue provides the same hook at @docx-editor.dev/pro/vue/webrtc. For setup details, see the real-time collaboration guide.

What replicates

Replicated content includes text, formatting, document structure, tables, headers, footers, notes, images, comments, tracked-change decisions, tables of contents, and custom nodes. Each person can undo only their own edits.

Review workflows also work in a room. One person can suggest changes while another person accepts or rejects them. The review sidebar stays live for every peer. See the tracked changes guide and comments guide.

Show presence

After module registration, the editor paints remote carets and selections. The Pro package also provides these presence components and hooks:

• DocxEditorCollaboration.Avatars renders the participant stack, colored to match each participant's review markup.
• DocxEditorCollaboration.CaretLabels replaces caret labels with your component. The component renders in the adapter tree, so hooks work in it.
• useCollaborationStatus and useCollaborationParticipants provide data for connection and participant interfaces.

Presence renderers receive the resolved color and optional participant data. They also receive a locally declared avatarUrl. You can omit session inside the editor provider tree.

See the presence interface guide.

Pick a transport

Use Yjs 13 with each server. The standard y-websocket server and Hocuspocus work without changes.

Offline editing

Set offlineEditing: true to continue editing after a transport disconnection. Buffered edits merge with concurrent edits after reconnection. Show connection status so people know when their edits have not reached the room.

Learn more

• Real-time collaboration: rooms, providers, presence, limits, and recovery.
• Tracked changes: suggesting mode and the review sidebar.
• Build a DOCX agent: connect a headless replica to a room for real-time agent edits.