Awareness

• Introduction
• Set your state
• Set your state
• Listen for changes
• Usage

#Introduction

Through awareness, information about all present users can be shared. Awareness allows you to sync the names, cursor positions, or even coordinates in a complex 3D world. Under the hood it has its own CRDT, but does not have a history of updates. You can read more about it in the Yjs documentation on awareness.

#Set your state

Pass a key and a value to set awareness information for the current users, you are free to pass whatever data you would like to share with other users. Here is an example with a name and a hex color under the user key:

You can also read more in our events section of the provider about the related events: awarenessUpdate and awarenessChange.

#Set your state

// Set the awareness field for the current user
provider.setAwarenessField("user", {
  name: "Kevin Jahns",
  color: "#ffcc00",
});

#Listen for changes

Register an event listener to receive and react to any changes, not only for your, but for all awareness states of all connected users:

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

#Usage

Gosh, all those tiny snippets. Here is complete working example of how that could look like in your app:

import * as Y from 'yjs'
import { HocuspocusProvider } from '@hocuspocus/provider'

// Set up the provider
provider = new HocuspocusProvider({
  url: "ws://127.0.0.1:1234",
  name: "awareness-example",
  document: new Y.Doc(),
  // Listen for updates …
  onAwarenessUpdate: ({ states }) => {
    console.log(states);
  },
});

// For example, listen for mouse movements
document.addEventListener("mousemove", (event) => {
  // Share any information you like
  provider.setAwarenessField("user", {
    name: "Kevin Jahns",
    color: "#ffcc00",
    mouseX: event.clientX,
    mouseY: event.clientY,
  });
});