@y-presence/react
v2.0.1
Published
Easy way to add presence (live cursors/avatars) to your multiplayer application using Yjs
Downloads
797
Maintainers
Readme
@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.
Other examples/integrations:
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()
: TheuseOthers
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()
: TheuseUsers
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 aUser
object containing information about the current user. This hook triggers a rerender everytime the user presence is updated (using either ofuseSetPresence
oruseUpdatePresence
hook). We'll learn more aboutuseSetPresence
anduseUpdatePresence
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 theupdatePresence
method that accepts a subset of the presence object. Because this method updates the user's presence object, any component that is using theuseSelf
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 thesetPresence
method that accepts a a presence object (unlike only a subset of presence object inuseUpdatePresence
). 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 theuseSelf
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()
: TheuseRoom
hook returns aRoom
, 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 theRoom
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.