Skip to content
TrademarkTrademark
Docs
Components

PeerCursor

Updated: November 12, 2026
View on GitHub

PeerCursor draws what other people are pointing at: an arrow in their colour, a label with their name, and, if they type one, a short message. It has no backend. Feed PeerCursors the positions from whatever carries them (Supabase Realtime, Liveblocks, a WebSocket) and send your own with usePeerPointer.

Positions from the network arrive 20 to 30 times a second. Each cursor glides to the latest one by writing transform every frame, without a React render, so a full room costs nothing between updates. Under reduced motion they jump.

Positions

PeerCursors fills its positioned parent and reads x and y as a fraction of it by default (units="fraction"), so people on screens of different widths point at the same spot of a fluid layout. Use units="px" for a fixed-size surface. usePeerPointer reports in the same units.

On a canvas that pans and zooms, there are two ways:

  • Put PeerCursors inside the world layer, with units="px" in world coordinates and scale={1 / zoom} so the cursors keep their size. Panning moves them with the layer for free.
  • Put it in a screen overlay and pass project (world to screen), with unproject (screen to world) on usePeerPointer.

Colour, label and message

Each person keeps the same hue on every screen: left out, scheme comes from peerColor(id), a hash of the id over the palette. Light hues take dark text.

  • message: a live line of text in a bubble under the pointer (cursor chat).
  • avatar: a small picture before the name.
  • idle: set it when someone has not moved for a while; the label folds away and only the arrow stays.

Accessibility

Cursors are decorative and hidden from screen readers. Say who is here in a way that reads, such as an AvatarGroup of the people in the room.

API

PeerCursors

Prop
Type
Default
Description
peersPeerCursorData[]Everyone else's pointer: { id, name, x, y, scheme?, message?, avatar?, idle? }.
units"fraction" | "px""fraction"What x and y mean.
project(x, y) => { x, y }Maps a position to px in the layer, after units.
scalenumberCursor scale about the tip; also --peer-cursor-scale.
smoothbooleantrueGlide between positions.

PeerCursor

Prop
Type
Default
Description
namestringThe label.
x, ynumberPx from the top left of the positioned parent.
idstringPicks the default colour.
schemeSchemespeerColor(id)The hue.
messagestringA bubble under the pointer.
avatarstringA picture before the name.
idlebooleanfalseFolds the label away.
smoothbooleantrueGlide between positions.

usePeerPointer(ref, onMove, options)

Calls onMove({ x, y }) as the pointer moves over ref's element, at most once per interval ms (default 40) with the last move always sent, and onMove(null) when it leaves. Options: interval, units, unproject, disabled. Touch is left out.

Edit this page on GitHub