Live Cursors
Multiplayer presence cursors with name labels — for collaborative whiteboards, shared editors, and real-time surfaces. Each collaborator gets a stable color assigned from a fixed palette; cursors are decorative and aria-hidden.
Cursors with labels
Pass a cursors array with id, name, x, and y to render labeled cursors at those positions.
Three collaborators on a shared surface
Color assignment
Colors are assigned deterministically from an 8-entry palette via assignCursorColor(id, index?). Providing an explicit color on a cursor entry overrides the palette.
Colors are assigned deterministically — same id, same color, every time.
On a canvas
Place <LiveCursors /> as a direct child of a position: relative container. It fills via absolute inset-0 and is pointer-events-none so it never blocks interaction.
Move your mouse — Maya follows your cursor
Installation
pnpm add @refraction-ui/reactUsage
import { LiveCursors } from '@refraction-ui/react'
import type { CursorData } from '@refraction-ui/react'
const cursors: CursorData[] = [
{ id: 'user-1', name: 'Maya', x: 120, y: 80 },
{ id: 'user-2', name: 'Kwame', x: 340, y: 210 },
{ id: 'user-3', name: 'Camille', x: 220, y: 150 },
]
export function Whiteboard() {
return (
<div className="relative w-full h-full">
{/* …canvas content… */}
<LiveCursors cursors={cursors} />
</div>
)
}LiveCursors props
| Prop | Type | Default | Description |
|---|---|---|---|
cursors | CursorData[] | -- | Array of collaborator cursor entries. Each entry: `{ id, name, x, y, color? }`. |
className | string | -- | Additional CSS classes applied to the overlay container. |
Cursor props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | -- | Collaborator display name shown in the label chip. |
x | number | -- | Horizontal position in pixels from the left of the container. |
y | number | -- | Vertical position in pixels from the top of the container. |
color | string | -- | Hex color applied to the SVG arrow fill and the name label chip background. |