@y-presence/react

React hooks to add multiplayer presence (live cursors/avatars) to any react application.

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.

• Simple room: Demo | Code
• Live cursors: Demo | Code
• Live avatars: Demo | Code

Other examples/integrations:

• perfect-cursors: Demo | Code

Installation

yarn add @y-presence/react
# or
npm i @y-presence/react

Usage

Wrap the components you'd like to provide access to @y-presence/react hooks inside RoomProvider in your React application.

// src/app.js

import * as Y from 'yjs'
import { RoomProvider } from '@y-presence/react'

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

// Create a provider
const provider = ...

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

// Define your presence object here
interface AppPresence {
  name: string;
  color: string;
}

// Define your initial app presence
const initialPresence: AppPresence = { name: "John Doe" }

export default function App() {
  return (
    <RoomProvider<AppPresence> awareness={awareness} initialPresence={initialPresence}>
      <SimpleRoom />
    </RoomProvider>
  )
}

Using y-presence react hooks

@y-presence/react comes with six hooks: useOthers(), useUsers(), useSelf(), useUpdatePresence, useSetPresence and useRoom().

• useOthers(): The useOthers hook returns an array of users that are currently connected in the room (excluding yourself). Each user object in the array contains the client/connection id and the presence information associated to the user.

  import { useOthers } from '@y-presence/react'
  
  export default function Room() {
    const others = useOthers<AppPresence>()
  
    return (
      <>
        <h3>Others</h3>
        {others.map((user) => {
          return (
            <div key={user.id}>
              <p>{user.presence.name}</p>
              <p>{user.presence.color}</p>
            </div>
          )
        })}
      </>
    )
  }

• useUsers(): The useUsers hook returns an array of users that are currently connected in the room (including yourself). Each user object in the array contains the client/connection id and the presence information associated to the user.

  import { useUsers } from '@y-presence/react'
  
  export default function Room() {
    const users = useUsers<AppPresence>()
  
    return (
      <>
        <h3>Users</h3>
        {users.map((user) => {
          return (
            <div key={user.id}>
              <p>{user.presence.name}</p>
              <p>{user.presence.color}</p>
            </div>
          )
        })}
      </>
    )
  }

• useSelf():

  The useSelf hook returns a User object containing information about the current user. This hook triggers a rerender everytime the user presence is updated (using either of useSetPresence or useUpdatePresence hook). We'll learn more about useSetPresence and useUpdatePresence below.

  import { useSelf } from '@y-presence/react'
  
  export default function Room() {
    const self = useSelf<AppPresence>()
  
    return (
      <>
        <h3>Self</h3>
        <p>{self.presence.name}</p>
        <p>{self.presence.name}</p>
      </>
    )
  }

• useUpdatePresence():

  The useUpdatePresence hook returns a the updatePresence method that accepts a subset of the presence object. Because this method updates the user's presence object, any component that is using the useSelf method is rerendered.

  import { useSelf, useUpdatePresence } from '@y-presence/react'
  
  export default function Room() {
    const self = useSelf<AppPresence>()
  
    const updatePresence = useUpdatePresence<AppPresence>()
  
    const updateColor = () => {
      updatePresence({ color: 'red' })
    }
  
    return (
      <>
        <p>{self.presence.color}</p>
        <button onClick={updateColor}>Update Color to Red</button>
      </>
    )
  }

• useSetPresence():

  The useSetPresence hook returns a the setPresence method that accepts a a presence object (unlike only a subset of presence object in useUpdatePresence). This method overrides the current presence object in a single transaction. Because this method updates the user's presence object, any component that is using the useSelf method is rerendered.

  import { useSelf, useSetPresence } from '@y-presence/react'
  
  export default function Room() {
    const self = useSelf<AppPresence>()
  
    const setPresence = useSetPresence<AppPresence>()
  
    const updateNameAndColor = () => {
      setPresence({ name: 'Jane Doe', color: 'red' })
    }
  
    return (
      <>
        <p>{self.presence.color}</p>
        <button onClick={updateNameAndColor}>Update Name and Color</button>
      </>
    )
  }

• useRoom(): The useRoom hook returns a Room, a thin wrapper around the provider awareness. This object provides helper methods to listen to various user events in a room. For more examples on how to use the Room object, check out @y-presence/client.

  import { useRoom } from '@y-presence/react'
  
  export default function Room() {
    const room = useRoom<AppPresence>()
    const [numUsers, setNumUsers] = React.useState(room.getUsers().length)
  
    React.useEffect(() => {
      const unsubUsers = room.subscribe('users', (users) => {
        setNumUsers(users.length)
      })
  
      return () => {
        unsubUsers()
      }
    }, [])
  
    return <p>Number of connected users: {numUsers}</p>
  }

License

This project is licensed under MIT.

Author

• @nayajunimesh