Collaboration and sharing integration reference

This reference describes the collaboration-related integration points exposed by Excalidraw. It covers the UI trigger, the encryption helpers, and selection-link callbacks; it does not define a hosted collaboration backend, persistence guarantee, access-control model, or link-expiration policy.

Integration model

Your host application owns the collaboration service and decides how to persist and distribute scene updates. Excalidraw exposes UI and data hooks that let you connect that service to the editor.

The diagram shows the supported boundary: the embedded editor can expose collaboration controls and generate or open links, while the host supplies transport, persistence, routing, and policy.

LiveCollaborationTrigger

LiveCollaborationTrigger is exported from @excalidraw/excalidraw as a child component you can use when composing the embedded editor UI. It provides the entry point for a host-controlled live-collaboration flow. The exported component does not establish a backend contract for you.

Use the trigger alongside your collaboration state and service. Keep the service responsible for session identity, participant updates, scene synchronization, and failure recovery. When connectivity or saving fails, preserve a local copy before stopping or replacing a session; the hosted application warns that stopping can overwrite the locally stored drawing and that offline changes might not be saved.

Collaborator and scene state

Collaboration state commonly crosses three boundaries:

The source snapshot does not establish backend limits, participant guarantees, or persistence semantics. Document those properties from the service you operate, not from this package reference.

Encrypt data

encryptData accepts a string key or CryptoKey and data as a Uint8Array, ArrayBuffer, Blob, File, or string. It returns an object containing encryptedBuffer and the initialization vector iv.

import { encryptData } from "@excalidraw/excalidraw";

const payload = JSON.stringify({ elements, appState });
const { encryptedBuffer, iv } = await encryptData(privateKey, payload);

// Send both values through your collaboration transport.
await transport.send({ encryptedBuffer, iv });

The implementation uses AES-GCM through the browser Web Crypto API and creates a new IV for each encryption. Your transport must preserve the IV with the ciphertext so the receiving side can decrypt it. Do not log keys, plaintext scene data, ciphertext, or IVs in production diagnostics.

The matching decryptData helper accepts an IV, encrypted data, and a private key and returns an ArrayBuffer. Encryption does not provide authentication, authorization, session membership, or storage by itself; implement those in the host service.

Generate links for selections

generateLinkForSelection

Pass generateLinkForSelection as an Excalidraw prop to replace the default link-generation function. The callback receives an ID and a type, then returns a string.

const generateLinkForSelection = (id: string, type: "element" | "group") =>
  `/diagrams/${diagramId}/${type}/${encodeURIComponent(id)}`;

<Excalidraw generateLinkForSelection={generateLinkForSelection} />

If your host uses a different key for the element-link ID, also implement onLinkOpen so your router can interpret that key and navigate to the target. For internal navigation, call event.preventDefault() after handling the route yourself. Preserve modifier-key behavior if your application supports opening links in a new tab or window.

Common integration failures

The session appears active but changes are not saved

Cause: the host collaboration service is offline or its save request failed. Fix: surface the failure, save the current scene locally, and retry through the service's supported recovery path before stopping the session.

A recipient cannot decrypt a scene update

Cause: the recipient did not receive the matching IV, or the key does not match the encryption key. Fix: transmit the IV with the encrypted buffer and verify key agreement without logging either secret.

A selection link opens the wrong object

Cause: generateLinkForSelection and onLinkOpen use different ID or type conventions. Fix: define one encoding for element and group, decode it in the host router, and verify both a single-element link and a group link.

Stopping a session loses a local change

Cause: the session stop flow can overwrite locally stored drawing data. Fix: save a local copy before stopping, then verify that the saved scene opens independently.

Next step

Use ExcalidrawAPI reference to apply incoming scene updates and inspect editor state. For the serialized payload shape, see Excalidraw file and clipboard format.