FlockRoom

FlockRoom represents a single room. You get one back from client.joinRoom(). It holds the room's current cursor and presence state and lets you send updates and listen for changes.

If you're using React, you don't need to use FlockRoom directly — the hooks handle it for you. Use useRoom() to get the raw room instance if you need escape-hatch access.

State accessors

`roomId`

readonly roomId: string

The room's identifier, as passed to joinRoom.

`getCursors`

getCursors(): Map<UserId, UserCursor>

Returns a snapshot of all other users' current cursor positions in the room.

`getPresence`

getPresence(): Map<UserId, PresenceUser>

Returns a snapshot of all users currently present in the room (excluding yourself).

`getMyPresence`

getMyPresence(): UserMetadata

Returns your own current presence metadata.

Actions

`updateCursor`

updateCursor(position: CursorPosition): void

Sends a cursor position update. Throttled to the cursor.throttleMs configured in joinRoom (default 50ms, ~20 updates/sec). Position values should be in 0–1 normalized coordinates.

document.addEventListener("mousemove", (e) => {
  room.updateCursor({
    x: e.clientX / window.innerWidth,
    y: e.clientY / window.innerHeight,
  });
});

`updatePresence`

updatePresence(metadata: Partial<UserMetadata>): void

Merges a partial update into your presence metadata. Only the fields you provide are changed; others are untouched.

room.updatePresence({ status: "idle" });
// color and name are preserved

`leave`

leave(): void

Sends a clean leave message to the server and removes the room locally. Other users see you leave immediately rather than waiting for the TTL to expire.

Events

`on`

on(event: string, handler: Function): () => void

Subscribes to room events. Returns an unsubscribe function.

Available events:

// Another user moved their cursor
on("cursor:update", (userId: UserId, cursor: UserCursor) => void): () => void
 
// Another user's cursor was removed (they left the viewport or left the room)
on("cursor:remove", (userId: UserId) => void): () => void
 
// A user joined the room
on("presence:join", (userId: UserId, user: PresenceUser) => void): () => void
 
// A user left the room
on("presence:leave", (userId: UserId) => void): () => void
 
// A user updated their presence metadata
on("presence:update", (userId: UserId, metadata: UserMetadata) => void): () => void

`off`

off(event: string, handler: Function): void

Removes an event listener.

Types

UserCursor

interface UserCursor {
  userId: UserId;
  position: CursorPosition;   // { x: 0–1, y: 0–1 }
  metadata: UserMetadata;
  lastUpdatedAt: number;       // unix ms
}

PresenceUser

interface PresenceUser {
  userId: UserId;
  metadata: UserMetadata;
  joinedAt: number;            // unix ms
}

CursorPosition

interface CursorPosition {
  x: number;   // 0–1, viewport-relative
  y: number;   // 0–1, viewport-relative
}

On this page