Get started with DOCX collaboration

This quickstart uses useWebrtcCollaboration to add real-time DOCX collaboration to a React or Vue editor. It connects two editors through WebRTC and shows each participant's changes.

Start with a working editor from the Quickstart. For provider options and failure states, see the collaboration reference.

What to verify

Use the same room ID and a different actorId for each editor. Open two tabs to verify synchronized edits.

Keep the editor mounted if the connection fails. Let users save local work before reconnecting.

For a server deployment, follow Hocuspocus setup. Before upgrading, check collaboration compatibility.

Install the packages

Install the Pro package, Yjs, and the WebRTC provider:

npm install @docx-editor.dev/pro yjs y-webrtc

You also need @docx-editor.dev/react or @docx-editor.dev/vue in your application.

Create a room ID

Create one room ID and send it to each participant:

import { createCollaborationRoomId } from '@docx-editor.dev/pro/collaboration/webrtc';

const roomId = createCollaborationRoomId();

Store the room ID in your application state or URL. Do not create a new ID during each render.

Add a collaborative editor

Call useWebrtcCollaboration with a room ID, an identity, and the initial DOCX bytes. The first editor creates the room. Later editors join its document. Use a different actorId for each active editor, including tabs opened by the same user.

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

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

export function CollaborativeEditor({ roomId, bytes, actorId, name }: CollaborativeEditorProps) {
  const { document, modules, session, error } = useWebrtcCollaboration({
    room: {
      roomId,
      identity: { actorId, name },
      bootstrap: { kind: 'create-or-join', document: bytes },
    },
  });

  if (!document) {
    return <p>{error ? 'Could not join this document.' : 'Connecting…'}</p>;
  }

  return (
    <>
      {error && (
        <p role="alert">Collaboration needs attention. Save a copy before you reconnect.</p>
      )}
      <DocxEditor key={session?.sessionId} document={document} modules={modules} />
    </>
  );
}

<script setup lang="ts">
import { DocxEditor } from '@docx-editor.dev/vue';
import { useWebrtcCollaboration } from '@docx-editor.dev/pro/vue/webrtc';

const props = defineProps<{
  roomId: string;
  bytes: Uint8Array;
  actorId: string;
  name: string;
}>();

const { document, modules, session, error } = useWebrtcCollaboration(() => ({
  room: {
    roomId: props.roomId,
    identity: { actorId: props.actorId, name: props.name },
    bootstrap: { kind: 'create-or-join', document: props.bytes },
  },
}));
</script>

<template>
  <p v-if="error" role="alert">
    Collaboration is unavailable. Save any local work before you reconnect.
  </p>
  <p v-if="!document && !error">Connecting…</p>
  <DocxEditor v-if="document" :key="session?.sessionId" :document="document" :modules="modules" />
</template>

For leaving and rejoining a room, see Connect with useWebrtcCollaboration.

Test the room

1. Open the application in one browser tab.
2. Open a second tab with the same roomId and a different actorId.
3. Type in either editor.

Open the first tab before the second tab. This sequence prevents both peers from seeding an empty room at the same time.

The example uses the public demo signaling service when you omit signaling. Configure your own signaling URLs and TURN servers for production.

Continue the setup

• Collaboration versions and upgrades: check compatibility before deploying updates or reopening saved rooms.
• Production WebRTC setup: configure signaling and TURN servers.
• Hocuspocus setup: connect authentication and persistence.
• Custom Yjs providers: connect an existing Yjs deployment.
• Tracked changes: suggesting mode and the review sidebar.
• Connect an agent to a document: choose browser edits, shared server edits, or complete DOCX updates.