tiptap/docs/collaboration/events.md

tableOfContents
true

What are provider events?

Events in Collaboration providers allow you to respond to various states and changes, such as successful connections or authentication updates. You can attach event listeners during the provider's initialization or add them later based on your application's needs.

Configuring Event Listeners

To ensure immediate event tracking, you can pass event listeners directly to the provider's constructor. This method guarantees that listeners are active from the start.

const provider = new TiptapCollabProvider({
  appId: '', // Use for cloud setups, replace with baseUrl in case of on-prem
  name: "example-document", // Document identifier
  token: '', // Your authentication JWT token
  document: ydoc,
  onOpen() {
    console.log("WebSocket connection opened.");
  },
  onConnect() {
    console.log("Connected to the server.");
  },
  // See below for all event listeners...
});

Dynamic Event Binding

For scenarios where you need to add or remove listeners post-initialization, the provider allows for dynamic binding and unbinding of event handlers

Binding Event Listeners

const provider = new TiptapCollabProvider({
  // …
});

provider.on("synced", () => {
  console.log("Document synced.");
});

Unbinding Event Listeners

const onMessage = () => {
  console.log("New message received.");
};

// Binding
provider.on("message", onMessage);

// Unbinding
provider.off("message", onMessage);

Key Events and their uses

Event	Description
open	Triggered when the WebSocket connection is established.
connect	Occurs when the provider successfully connects to the server.
authenticated	Indicates successful client authentication.
authenticationFailed	Fires when client authentication fails.
status	Reflects changes in connection status.
message	Captures incoming messages.
outgoingMessage	Signals when a message is about to be sent.
synced	Marks the initial successful sync of the Y.js document.
close	Triggered when the WebSocket connection closes.
disconnect	Occurs upon provider disconnection.
destroy	Signifies the impending destruction of the provider.
awarenessUpdate	Tracks updates in user awareness information.
awarenessChange	Indicates changes in the awareness state.
stateless	When the stateless message was received.

Use cases for event handling

Real-time Connection Status

Utilize onConnect and onDisconnect to provide users with real-time connection status feedback, enhancing the user experience.

provider.on("connect", () => {
  showStatus("Connected");
});

provider.on("disconnect", () => {
  showStatus("Disconnected");
});

Document Sync Status

The synced event can be used to alert users when the document is fully synced initially, ensuring they start working with the latest version.

provider.on("synced", () => {
  alert("Document initialized");
});

Handling Authentication Issues

Use authenticationFailed to catch authentication errors and prompt users to reauthenticate, maintaining secure access.

provider.on("authenticationFailed", ({ reason }) => {
  console.error("Authentication failed:", reason);
  requestUserReauthentication();
});