Implementing Cursor Presence (User Cursors) on Your Website
Picture this: ten editors working on one document, and each user's cursor jumps, disappears, or overlaps. This is typical without proper cursor presence implementation. Cursor presence—displaying real-time cursors and selections—seems simple, but there are many pitfalls: efficient coordinate transmission, smooth animation, correct mapping during scrolling and disconnection. Without optimization, traffic can reach 10,000 messages per second with 50 users, which is critical for mobile networks and increases server costs up to 50% (about $70/month for 10 users). Our team has five years of experience in real-time collaboration and has implemented cursor presence for 30+ projects (editors, boards, chats). We offer a turnkey solution: in 1–2 days we integrate user presence with traffic optimization and guaranteed smoothness. Contact us for a consultation and demo.
Throttle and Its Impact on Traffic
The mousemove event fires 50–100 times per second. Sending each to the server, with 10 users, traffic reaches thousands of messages per second. Optimal throttling is 30 fps (33 ms). Use a throttle function—like from lodash-es:
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');
});
On the server (Socket.IO) — broadcast to the room, excluding the 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,
});
});
Traffic savings with 30 fps instead of 60 is up to 50%—critical for mobile networks.
Traffic savings calculation
At 50 messages per second per user and 10 users, traffic is 500 messages/s. Throttle to 30 fps reduces to 300 messages/s. Savings of 40%—approximately $30–40/month at current rates.Why Lerp Interpolation Is Mandatory?
Direct position updates per event cause jumps. CSS transition transition: transform 0.1s linear creates a lag in the wrong direction. The only correct solution is linear interpolation (lerp) inside 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 };
}
});
An interpolation factor of 0.35 gives smooth movement without noticeable lag.
Comparison of Approaches: WebSocket vs Yjs Awareness
| Criteria | Plain WebSocket | Yjs Awareness |
|---|---|---|
| Implementation time | 1–2 days from scratch | Half a day if Yjs already in use |
| Server load | Higher (own broadcast logic) | Lower (built-in broadcast) |
| Ease of extension | Medium (manual field addition) | Low (automatic state) |
| Text selection support | Requires additional logic | Built-in via Awareness |
Yjs Awareness is 3x faster to implement than plain WebSocket if Yjs is already in use. The WebSocket standard (see RFC 6455) defines a bidirectional communication protocol.
How to Choose Between WebSocket and Yjs Awareness?
If Yjs is already used in the project—use Awareness: it automatically syncs cursor state, text selection, and other fields. Otherwise, plain WebSocket suffices. For reference: WebSocket is a standard protocol, and Yjs is a CRDT library for collaborative editing.
Work Process
- Analysis — define use cases, load, current stack.
- Design — choose protocol (WebSocket or Yjs), design data model.
- Implementation — write client-server part, integrate throttle, lerp, TTL.
- Testing — test with 50+ simultaneous users, measure traffic.
- Deployment and support — deploy on your hosting, offer 30-day warranty.
What to Do If Cursors Disappear During Scroll?
Store coordinates relative to the document (clientX + scrollOffset), then subtract the current scroll when rendering. Otherwise, others' cursors will shift during scrolling.
document.addEventListener('mousemove', throttle((e) => {
provider.awareness.setLocalStateField('cursor', {
x: e.clientX + window.scrollX,
y: e.clientY + window.scrollY,
});
}, 33));
function getCursorViewportPos(docX: number, docY: number) {
return {
x: docX - window.scrollX,
y: docY - window.scrollY,
};
}
TTL and Cleaning Stale Cursors
If a user closes a tab without explicit disconnect, the cursor remains on screen. Solution — heartbeat + TTL on the client:
const CURSOR_TTL = 5000; // 5 seconds without 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);
Comparison of Throttle Options
| Frequency (fps) | Traffic for 10 users (messages/sec) | Smoothness |
|---|---|---|
| 60 | 600 | Perfect |
| 30 | 300 | Sufficient |
| 15 | 150 | Noticeable jitter |
For most tasks, 30 fps is the optimal balance.
What's Included in the Work?
When ordering cursor presence implementation, you get:
- Data transfer architecture (WebSocket or Yjs)
- Client-side code with throttle and lerp interpolation
- Coordinate handling (document-relative, scroll)
- TTL mechanism for removing stale cursors
- Integration with existing system (editor, chat, etc.)
- Documentation and team training
Implementation from scratch takes 1–2 days. If Yjs or Socket.IO is already in use, half a day. Contact us for a consultation: we'll evaluate your project and propose the optimal solution. Over five years we've completed more than 30 integrations—your project will be in safe hands. Order implementation today and get free testing.