useCursors

import { useCursors } from "@xevrion/flock-react";

Signature

function useCursors(): Record<UserId, UserCursor>

Returns

A Record mapping each other user's userId to their current UserCursor. Your own cursor is not included.

interface UserCursor {
  userId: string;
  position: { x: number; y: number };  // normalized 0–1
  metadata: UserMetadata;               // name, color, avatar, custom fields
  lastUpdatedAt: number;                // unix ms of last received update
}

With interpolation enabled (the default), the hook drives a requestAnimationFrame loop and updates state once per animation frame while any cursor is moving, giving you smooth cursor positions at display refresh rate.

With interpolate={false} on the provider, the hook updates only when a cursor update arrives from the server (roughly the throttle rate, default 20/sec).

Usage

function CursorOverlay() {
  const cursors = useCursors();
 
  return (
    <div style={{ position: "fixed", inset: 0, pointerEvents: "none" }}>
      {Object.values(cursors).map((cursor) => (
        <div
          key={cursor.userId}
          style={{
            position: "absolute",
            left: `${cursor.position.x * 100}%`,
            top: `${cursor.position.y * 100}%`,
            transform: "translate(-50%, -50%)",
            color: cursor.metadata.color,
          }}
        >
          {cursor.metadata.name}
        </div>
      ))}
    </div>
  );
}

Requirements

Must be called inside a <FlockProvider>. Throws if used outside one.

Signature

Returns

Re-renders

Usage

Requirements

See also

On this page