Live Cursors

#Installation & usage

Use live cursors on anything several people work on at once: a design canvas, a whiteboard, a shared document, a dashboard being reviewed together. Youj has no transport of its own: you send the local pointer over whatever you already use (WebSockets, WebRTC, Liveblocks, Supabase Realtime, a CRDT's awareness) and pass everyone else back in.

import { LiveCursors, PresenceAvatars, useLiveCursorsInput, type LiveCursorUser } from '@youj/react'

const surface = useRef<HTMLDivElement>(null)
const [others, setOthers] = useState<LiveCursorUser[]>([])
const [following, setFollowing] = useState<string | null>(null)

// Send your pointer: { x, y } in fractions of the surface, or null when it leaves.
useLiveCursorsInput(surface, (position) => channel.send({ id: me.id, name: me.name, ...position }))
// Receive everyone else's into `others` (leave yourself out).
useEffect(() => channel.onPresence(setOthers), [])

<PresenceAvatars users={others} following={following} onFollowingChange={setFollowing} />
<LiveCursors ref={surface} users={others} following={following}>
  <Canvas />
</LiveCursors>

LiveCursors wraps the surface (it renders a relative box around its children) and draws a cursor for each person in users with an x and y. Positions are fractions of the surface, 0 to 1 from the top left, so a person on a wide screen and one on a phone point at the same spot. Leave x and y out while someone's pointer is elsewhere and their cursor goes; remove them from users when they leave.

Each person has a color, by default one of the theme's five chart colors picked from their id, so every screen gives them the same one. Five colors mean two people can share one; pass color (a slot your server hands out, say) where they must differ. The name tag's text turns black or white for contrast. A message shows as a chat bubble under the name, and selection draws their selected areas as tinted rectangles.

Updates can be sparse: each cursor springs to its newest position, all of them on one animation loop that stops when they rest or the surface scrolls out of view. A cursor that hasn't moved for idleAfter milliseconds (10 seconds by default; 0 keeps them) fades out until it moves or speaks again.

useLiveCursorsInput(ref, onMove, { throttle }) reports the pointer at most every throttle milliseconds (50 by default), always ending on the last move, and null when it leaves the surface.

PresenceAvatars shows who is here, with each person's color as a ring and their status ("Viewing" or "Editing") in a tooltip. Give it following and onFollowingChange and each avatar becomes a button that follows that person: pass the same following to LiveCursors, which scrolls their cursor into view as they move. Without them, the avatars only show who's here. Past max (5) the rest are counted.

#Description

#Code