State and change events

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

Use provider events

Event	Description
`open`	Triggered when the WebSocket connection opens.
`connect`	Triggered when the provider connects to the server.
`authenticated`	Indicates successful client authentication.
`authenticationFailed`	Triggered when client authentication fails.
`status`	Tracks changes in connection status.
`close`	Triggered when the WebSocket connection closes.
`disconnect`	Triggered when the provider disconnects.
`destroy`	Signifies the impending destruction of the provider.
`message`	Triggered by incoming messages.
`outgoingMessage`	Triggered before a message is sent.
`synced`	Indicates the initial successful sync of the Yjs document.
`stateless`	Triggered when the stateless message is received.
`awarenessUpdate`	Triggered when user awareness information updates.
`awarenessChange`	Triggered when the awareness state changes.

Configure event listeners

To track events immediately, pass event listeners directly to the provider's constructor. This 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 more event listeners...
})

Bind events dynamically

To add or remove listeners after initialization, the provider supports dynamic binding and unbinding of event handlers.

Example: Binding event listeners during provider initialization

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

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

Example: Binding/unbinding event listeners after provider initialization

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

// Binding
provider.on('message', onMessage)

// Unbinding
provider.off('message', onMessage)

Provider event examples

Display connection status

Use 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')
})

Sync document status

Use synced to alert users when the document is fully synced initially, ensuring they start working with the latest version.

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

Handle authentication issues

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

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