Cursor Presence (Live User Cursors)

Implementing Cursor Presence (User Cursors) on Website

Cursor presence — displaying other participants' cursors and selections in real time. Visually simple; complexity hidden in: efficient coordinate transmission, movement interpolation, correct position mapping when content changes.

Presence Data Model

Each client broadcasts state: cursor position, active element, text selection. Minimal structure:

interface UserPresence {
  userId:    string;
  name:      string;
  color:     string;
  cursor: {
    x:       number;
    y:       number;
  } | null;
  selection?: {
    anchor:  number;
    head:    number;
  };
  activeElement?: string;
  lastSeen:  number;
}

WebSocket Transmission: Throttle Mandatory

Mousemove fires 50–100 events/second. Without throttle, 10 users = thousands messages/sec to server. Reasonable limit — 30 fps (33ms).

import { throttle } from 'lodash-es';

const sendCursor = throttle((x: number, y: number) => {
  socket.emit('cursor:move', { x, y });
}, 33);

document.addEventListener('mousemove', (e) => {
  sendCursor(e.clientX, e.clientY);
});

document.addEventListener('mouseleave', () => {
  socket.emit('cursor:leave');
});

Server (Socket.IO) — broadcast to room, excluding sender:

socket.on('cursor:move', (data: { x: number; y: number }) => {
  socket.to(roomId).emit('cursor:update', {
    userId: socket.data.userId,
    ...data,
  });
});

socket.on('cursor:leave', () => {
  socket.to(roomId).emit('cursor:remove', {
    userId: socket.data.userId,
  });
});

socket.on('disconnect', () => {
  socket.to(roomId).emit('cursor:remove', {
    userId: socket.data.userId,
  });
});

Rendering: Interpolation

Direct position update per event — jerky cursors. CSS transition: transform 0.1s linear — introduces lag. Correct — linear interpolation (lerp) in requestAnimationFrame:

interface RemoteCursor {
  userId:    string;
  name:      string;
  color:     string;
  current:   { x: number; y: number };
  target:    { x: number; y: number };
  el:        HTMLElement;
}

const cursors = new Map<string, RemoteCursor>();

function lerp(a: number, b: number, t: number) {
  return a + (b - a) * t;
}

function animateCursors() {
  cursors.forEach((cursor) => {
    cursor.current.x = lerp(cursor.current.x, cursor.target.x, 0.35);
    cursor.current.y = lerp(cursor.current.y, cursor.target.y, 0.35);
    cursor.el.style.transform =
      `translate(${cursor.current.x}px, ${cursor.current.y}px)`;
  });
  requestAnimationFrame(animateCursors);
}

animateCursors();

// On update — only change target
socket.on('cursor:update', ({ userId, x, y, name, color }) => {
  if (!cursors.has(userId)) {
    const el = createCursorElement(userId, name, color);
    document.body.appendChild(el);
    cursors.set(userId, {
      userId, name, color,
      current: { x, y },
      target:  { x, y },
      el,
    });
  } else {
    cursors.get(userId)!.target = { x, y };
  }
});

Cursor HTML Element

function createCursorElement(userId: string, name: string, color: string): HTMLElement {
  const wrapper = document.createElement('div');
  wrapper.style.cssText = `
    position: fixed;
    top: 0; left: 0;
    pointer-events: none;
    z-index: 9999;
    will-change: transform;
  `;
  wrapper.innerHTML = `
    <svg width="16" height="20" viewBox="0 0 16 20" fill="none">
      <path d="M0 0L0 16L4 12L7 18L9 17L6 11L11 11Z"
            fill="${color}" stroke="white" stroke-width="1"/>
    </svg>
    <span style="
      background: ${color};
      color: white;
      font-size: 11px;
      padding: 2px 6px;
      border-radius: 4px;
      white-space: nowrap;
      margin-left: 12px;
      margin-top: -4px;
      display: inline-block;
      font-family: system-ui;
    ">${name}</span>
  `;
  return wrapper;
}

Presence via Yjs Awareness

If project already using Yjs, Awareness — built-in presence mechanism:

import { WebsocketProvider } from 'y-websocket';

const provider = new WebsocketProvider(wsUrl, roomName, ydoc);

// Set local state
provider.awareness.setLocalState({
  user: {
    id:    currentUser.id,
    name:  currentUser.name,
    color: generateColor(currentUser.id),
  },
  cursor: null,
});

// Update cursor position
document.addEventListener('mousemove', throttle((e) => {
  provider.awareness.setLocalStateField('cursor', {
    x: e.clientX,
    y: e.clientY,
  });
}, 33));

// Subscribe to changes
provider.awareness.on('change', ({ added, updated, removed }) => {
  const states = provider.awareness.getStates();

  [...added, ...updated].forEach((clientId) => {
    if (clientId === provider.awareness.clientID) return;
    const state = states.get(clientId);
    if (state?.cursor) {
      updateCursor(clientId, state.user, state.cursor);
    }
  });

  removed.forEach((clientId) => {
    removeCursor(clientId);
  });
});

Coordinates: Viewport vs Document

Scrolling page — viewport coords (clientX/Y) insufficient — remote cursors shift. Need document-relative:

document.addEventListener('mousemove', throttle((e) => {
  provider.awareness.setLocalStateField('cursor', {
    x: e.clientX + window.scrollX,
    y: e.clientY + window.scrollY,
  });
}, 33));

// On render — convert back
function getCursorViewportPos(docX: number, docY: number) {
  return {
    x: docX - window.scrollX,
    y: docY - window.scrollY,
  };
}

Cursors in Text Editors

Position in text — not coordinate, but character offset. Map to screen position via Range API:

function getCaretCoordinates(offset: number): { x: number; y: number } | null {
  const range = document.createRange();
  const editorEl = document.getElementById('editor')!;
  let charCount = 0;

  function findNode(node: Node): boolean {
    if (node.nodeType === Node.TEXT_NODE) {
      const len = node.textContent!.length;
      if (charCount + len >= offset) {
        range.setStart(node, offset - charCount);
        range.collapse(true);
        return true;
      }
      charCount += len;
    } else {
      for (const child of node.childNodes) {
        if (findNode(child)) return true;
      }
    }
    return false;
  }

  if (!findNode(editorEl)) return null;

  const rect = range.getBoundingClientRect();
  return { x: rect.left, y: rect.top };
}

For ProseMirror and CodeMirror — ready utils (view.coordsAtPos()), no manual.

TTL and Cleanup

User closes tab without explicit disconnect — cursor stays. Solution — heartbeat + TTL:

const CURSOR_TTL = 5000; // 5 sec no updates

const lastSeen = new Map<string, number>();

socket.on('cursor:update', ({ userId, ...pos }) => {
  lastSeen.set(userId, Date.now());
  updateCursor(userId, pos);
});

setInterval(() => {
  const now = Date.now();
  lastSeen.forEach((ts, userId) => {
    if (now - ts > CURSOR_TTL) {
      removeCursor(userId);
      lastSeen.delete(userId);
    }
  });
}, 1000);

Implementation cursor presence from scratch — 1–2 days. If already using Yjs or Socket.IO, via awareness/broadcast — half day.