y-presence

Implement and manage presence/awareness using Yjs in any React application using two simple React hooks: useSelf and useUsers.

Codesandbox demo/examples

For all the demos, you can open a new tab on your browser to observe how the presence updates in each example.

- Multiplayer avatars: Demo | Code
- Multiplayer cursors: Demo | Code
- Simple room: Demo | Code

$3

- perfect-cursors: Demo | Code


Recommended Reading

- API documentation of the Awareness CRDT

Usage

$3

``bash
yarn add y-presence


or


npm i y-presence
`

$3

`tsx
// src/store.ts
import { WebsocketProvider } from "y-websocket";
import { Doc } from "yjs";

// Create the shared doc (from Yjs)
const doc = new Doc();

// Create a provider
const provider = new WebsocketProvider(
"wss://demos.yjs.dev",
"y-presence-demo",
doc
);

// Get the provider's awareness API
export const awareness = provider.awareness;

// Set the local awareness state
awareness.setLocalState({ name: "John Doe", email: "johndoe@gmail.com" });
`

$3

`tsx
// src/App.tsx

import { useUsers } from "y-presence";
import { awareness } from "./store.ts";

export default function App() {
// Fetch all users connected in the room
const users = useSelf(awareness);

return

;
}
`

Hooks

$3

The useUsers hook subscribes to updates to the awareness states of all users connected in the room. It accepts three arguments:

1. An awareness object returned by connection provider.
2. (Optional) A selector function that accepts a map of the awareness states and enables selecting a subset of this map. This signals React to rerender the component only when this subset has changed.
3. (Optional) A equality function to detect if the selected subset has changed.

#### Example Usage:

`tsx
// Returns a map of the client id to their awareness state and rerenders when any such awareness state changes
const users = useUsers(awareness);
// equivalent to:
const users = useUsers(awareness, (state) => state);
// Map {
// 3965141439 => { name: "John Doe", email: "johndoe@gmail.com" }
// }

// Returns the number of users connected in the room and rerenders when this number changes
const size = useUsers(awareness, (state) => state.size);
// 1

// Returns the awareness state of the current user (self) and rerenders when this state changes. A simpler/optimized hook for this use case is also provided, and is discussed below:
const self = useUsers(awareness, (state) => state.get(awareness.clientId));
// {
// name: "John Doe",
// email: "johndoe@gmail.com"
// }
`

$3

The useSelf hook subscribes to updates to the awareness state of the current user (self) in the room. It accepts three arguments:

1. An awareness object returned by connection provider.
2. (Optional) A selector function that accepts an awareness state object and enables selecting a subset of this object. This signals React to rerender the component only when this subset has changed.
3. (Optional) A equality function to detect if the selected subset has changed.

#### Example Usage:

`tsx
// Returns the awareness state of the current user (self) and rerenders when this state changes.
const self = useSelf(awareness);
// is equivalent to:
const self = useSelf(awareness, (state) => state);
// {
// name: "John Doe",
// email: "johndoe@gmail.com"
// }

// Returns the value of the property name of the current user's awareness state and rerenders when this value changes
const name = useSelf(awareness, (state) => state?.name);
// "John Doe"
``

$3

This project is licensed under MIT.

$3

The two hooks are inspired by the Liveblocks' Presence hooks. Check out their website and documentation to learn more about their presence/awareness implementation.

Author

- @nayajunimesh