Tiptap Docs

Awareness in Collaboration

Awareness in Tiptap Collaboration, powered by Yjs, is helping you share real-time info on users' activities within a collaborative space. This can include details like user presence, cursor positions, and custom user states.

At its core, awareness utilizes its own Conflict-Free Replicated Data Type (CRDT) to ensure that this shared meta-information remains consistent and immediate across all users, without maintaining a historical record of these states.

You can read more about Awareness in the Yjs documentation on awareness.

Necessary provider events

Awareness updates trigger specific provider events to develop interactive features based on user actions and presence:

  • awarenessUpdate: This event signals that a user is active. It triggers without actual state changes, serving as a 'heartbeat' to inform others the user is in the document.
  • awarenessChange: This event alerts you to any additions, updates, or deletions in the awareness state, reflecting both your local changes and those from remote users.

These events serve as hooks for integrating custom Awareness features.

Integrate awareness

With your collaborative environment set up, you're all set to integrate Awareness, which is natively supported by the Collaboration Provider.

To kick things off, update the Awareness state with any relevant information. As an example we'll use a user's name, cursor color, and mouse position as examples.

Set the awareness field

Let's assign a name, color, and mouse position to the user. This is just an example; feel free to use any data relevant to your application.

// Set the awareness field for the current user
provider.setAwarenessField('user', {
  // Share any information you like
  name: 'Kevin James',
  color: '#ffcc00',
})

Listen for changes

Set up an event listener to track changes in the Awareness states across all connected users:

// Listen for updates to the states of all users
provider.on('awarenessChange', ({ states }) => {
  console.log(states)
})

You can now view these updates in your browser's console as you move on to the next step.

Track mouse movement

Next, we'll add an event listener to our app to track mouse movements and update the awareness' information accordingly.

document.addEventListener('mousemove', (event) => {
  // Share any information you like
  provider.setAwarenessField('user', {
    name: 'Kevin James',
    color: '#ffcc00',
    mouseX: event.clientX,
    mouseY: event.clientY,
  })
})

Check your browser's console to see the stream of events as users move their mice.

Add cursors and carets

With basic Awareness in place, consider adding the Collaboration Cursor extension to your editor. This extension adds cursor positions, text selections, and personalized details (such as names and colors) of all participating users to your editor.