Live Cursors :: Lab :: Carter Ogunsola

Everyone else on the page, in real time. You broadcast your pointer as a 0-to-1 position, a Cloudflare Durable Object fans it out, and each peer eases toward its latest spot, on the same server that counts who's online in the header.

Dependencies

PartyKitPartyServer :: Durable Object rooms + presence partysocket :: reconnecting WebSocket client GSAPCore :: one ticker for the interpolation loop

Someone else is here

Most of the web is single-player. You move your cursor, nothing moves back. Open this page in a second tab, or send it to a friend, and their pointer slides across your screen in real time, tinted and named, easing wherever they go.

One object in the middle

Every visitor holds one WebSocket to a room called live-cursors, served by a single Cloudflare Durable Object (the same one that counts who’s online up in the header). You send your pointer; the object fans it out to everyone else. Nobody talks to anyone directly, which is what makes it trustworthy: the server stamps each message with the sender’s real connection id and clamps the coordinates before forwarding, so a peer can’t claim to be someone else or fling a cursor off the stage. Names and colors are derived from that id on the client and written with textContent, so a hostile payload has nowhere to land.

Positions travel as a pair of 0-to-1 fractions of the stage, not pixels. A peer at 0.5, 0.5 sits dead center of your stage whatever your window size. There’s no shared artwork to line up against, so relative is the honest mapping: your top-right is their top-right.

The feel is in the easing

Raw network positions land in bursts, and drawn straight they make a cursor teleport. So each peer carries two positions, a target (the last thing that arrived) and a rendered one, and every frame the rendered position moves a fraction of the way toward the target. That fraction is time-based (1 − e^(−λ·dt)), so the glide feels the same at 30fps and 120fps instead of turning twitchy on a fast display.

You broadcast at most once every 50ms (~20 a second, under the server’s rate cap), and even holding still your position re-sends every 4s so you never flicker out on anyone else’s screen. Smoothing sits at λ18. Go 12s with no word from a peer and their cursor is pulled, which is the thing that catches a shut laptop lid that never sends a clean goodbye.

The moving parts

The room — one Durable Object per room name. live-cursors is this stage, global is the header count. Same server, different rooms.
Normalized coordinates — pointer stored as x/width, y/height, so it maps across any window size.
Server-stamped id — the relay attaches the real sender id; the client trusts nothing else on the message.
Stale sweep — drop a peer after 12s of silence, for the disconnect that was never clean. Clean departures arrive instantly as a leave from the server.
Keepalive — your position re-sends every 4s even at rest, so idle-but-present peers keep their cursor instead of blinking out.

The cursor art is Central Icons’ collaboration pointer, flipped left or right by the peer’s travel direction. Reduced-motion callers get the same cursors with the easing off: they snap to each position instead of gliding.

Built on PartyKit, by Sunil Pai, now part of Cloudflare.

Setup

1
<!-- GSAP (from CDN) -->
2
<script src="https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js"></script>
3
<!-- partysocket via import map (ES modules) -->
4
<script type="importmap">
5
{
6
  "imports": {
7
    "partysocket": "https://cdn.jsdelivr.net/npm/partysocket@1.3.0/+esm"
8
  }
9
}
10
</script>
11

12
<!-- Site tokens the styles use — swap freely -->
13
<style>
14
  :root {
15
    --font-mono: "PP Neue Montreal Mono", "Geist Mono", ui-monospace, monospace;
16
    --fs-mono-sm: 0.625rem;
17
    --paper: #d6d6d5;
18
    --ink: #1e1e1e;
19
    --ink-muted: rgba(30, 30, 30, 0.7);
20
    --r-sm: 4px;
21
    --ease-out-quad: cubic-bezier(0.5, 1, 0.89, 1);
22
  }
23
</style>
24

25
<!-- Live cursors need a relay server of your own: deploy a PartyServer
26
     (github.com/cloudflare/partykit/tree/main/packages/partyserver) with a
27
     "presence" party, then set SITE.presence.host in the Script to its host.
28
     It relays {type:"cursor",x,y} as {type:"cursors",c:[[id,x,y]]} frames
29
     and sends {type:"leave",id} when a connection closes. -->
30

31
<!-- Sized stage — the script fills it -->
32
<div class="stage" style="position: relative; height: 100vh; background: var(--paper);"></div>
33

34
<!-- Then the Script, inside <script type="module"> (CodePen's JS panel does this for you) -->

Style

1
.lc {
2
  position: absolute;
3
  inset: 0;
4
  overflow: hidden;
5
}
6

7
.lc__hint {
8
  position: absolute;
9
  inset: 0;
10
  display: grid;
11
  place-items: center;
12
  padding: 2rem;
13
  text-align: center;
14
  color: var(--ink-muted);
15
  font-family: var(--font-mono);
16
  font-size: var(--fs-mono-sm,0.8rem);
17
  letter-spacing: 0.02em;
18
  transition: opacity .4s var(--ease-out-quad);
19
  pointer-events: none;
20
}
21

22
.lc__peer {
23
  position: absolute;
24
  top: 0;
25
  left: 0;
26
  will-change: transform;
27
  pointer-events: none;
28
  transform-origin: top left;
29
}
30

31
.lc__ptr {
32
  display: block;
33
  filter: drop-shadow(0 1px 2px rgba(0,0,0,0.18));
34
}
35

36
.lc__ptr svg {
37
  display: block;
38
  width: 22px;
39
  height: 22px;
40
}
41

42
.lc__name {
43
  position: absolute;
44
  top: 18px;
45
  left: 16px;
46
  white-space: nowrap;
47
  padding: 2px 6px;
48
  border-radius: var(--r-sm,4px);
49
  font-family: var(--font-mono);
50
  font-size: 0.62rem;
51
  letter-spacing: 0.02em;
52
  color: #fff;
53
  transform: translateZ(0);
54
}

Script

1
import PartySocket from "partysocket";
2
const SITE = {
3
  "presence": {
4
    "host": "your-partyserver.example"
5
  }
6
};
7
const leftSvg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"><path d="M13.6262 12.7752L18.0914 11.0286C19.4037 10.5153 19.3481 8.63955 18.0078 8.20483L6.29674 4.40666C5.13162 4.02878 4.02927 5.13113 4.40715 6.29625L8.20532 18.0073C8.64004 19.3477 10.5158 19.4032 11.0291 18.0909L12.7757 13.6257C12.9282 13.236 13.2365 12.9277 13.6262 12.7752Z" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/><path d="M21 14L16.6049 15.7762C16.2277 15.9286 15.9286 16.2277 15.7762 16.6049L14 21" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>';
8
const rightSvg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"><path d="M10.3739 12.7752L5.90868 11.0286C4.59639 10.5153 4.65197 8.63955 5.99235 8.20483L17.7034 4.40666C18.8685 4.02878 19.9708 5.13113 19.593 6.29625L15.7948 18.0073C15.3601 19.3477 13.4843 19.4032 12.971 18.0909L11.2244 13.6257C11.072 13.236 10.7636 12.9277 10.3739 12.7752Z" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/><path d="M3 14L7.39513 15.7762C7.77231 15.9286 8.07141 16.2277 8.22383 16.6049L10 21" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>';
9
const clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
10
const SEND_MS = 50;
11
const KEEPALIVE_MS = 4e3;
12
const HEARTBEAT_MS = 2e4;
13
const STALE_MS = 12e3;
14
const DEFAULTS = {
15
  smoothing: 18,
16

17
  size: 1
18

19
};
20
const COLORS = ["#3f76b5", "#838348", "#c2661f", "#9c6b77", "#a67f1e", "#8670a2"];
21
const ADJ = ["quiet", "swift", "warm", "spare", "lucid", "keen", "soft", "bright"];
22
const ANIMAL = ["otter", "heron", "lynx", "moth", "fox", "wren", "koi", "hare"];
23
function hash(s) {
24
  let h = 0;
25
  for (let i = 0; i < s.length; i++) h = h * 31 + s.charCodeAt(i) | 0;
26
  return Math.abs(h);
27
}
28
const colorFor = (id) => COLORS[hash(id) % COLORS.length];
29
const nameFor = (id) => {
30
  const h = hash(id);
31
  return `${ADJ[h % ADJ.length]} ${ANIMAL[(h >> 3) % ANIMAL.length]}`;
32
};
33
const STYLE_ID = "exp-cursors-style";
34
const CSS = `
35
.lc {
36
  position: absolute;
37
  inset: 0;
38
  overflow: hidden;
39
}
40

41
.lc__hint {
42
  position: absolute;
43
  inset: 0;
44
  display: grid;
45
  place-items: center;
46
  padding: 2rem;
47
  text-align: center;
48
  color: var(--ink-muted);
49
  font-family: var(--font-mono);
50
  font-size: var(--fs-mono-sm,0.8rem);
51
  letter-spacing: 0.02em;
52
  transition: opacity .4s var(--ease-out-quad);
53
  pointer-events: none;
54
}
55

56
.lc__peer {
57
  position: absolute;
58
  top: 0;
59
  left: 0;
60
  will-change: transform;
61
  pointer-events: none;
62
  transform-origin: top left;
63
}
64

65
.lc__ptr {
66
  display: block;
67
  filter: drop-shadow(0 1px 2px rgba(0,0,0,0.18));
68
}
69

70
.lc__ptr svg {
71
  display: block;
72
  width: 22px;
73
  height: 22px;
74
}
75

76
.lc__name {
77
  position: absolute;
78
  top: 18px;
79
  left: 16px;
80
  white-space: nowrap;
81
  padding: 2px 6px;
82
  border-radius: var(--r-sm,4px);
83
  font-family: var(--font-mono);
84
  font-size: 0.62rem;
85
  letter-spacing: 0.02em;
86
  color: #fff;
87
  transform: translateZ(0);
88
}
89
`;
90
function injectStyle() {
91
  if (document.getElementById(STYLE_ID)) return;
92
  const el = document.createElement("style");
93
  el.id = STYLE_ID;
94
  el.textContent = CSS;
95
  document.head.appendChild(el);
96
}
97
const experiment = {
98
  mount(root) {
99
    injectStyle();
100
    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
101
    const finePointer = window.matchMedia("(pointer: fine)").matches;
102
    const P = { ...DEFAULTS };
103
    const wrap = document.createElement("div");
104
    wrap.className = "lc";
105
    const hint = document.createElement("p");
106
    hint.className = "lc__hint";
107
    hint.textContent = finePointer ? "Open this page in another tab or on another device :: you'll see each other move." : "Others' cursors show up here. Touch has no pointer, so you're here in spirit.";
108
    wrap.appendChild(hint);
109
    root.appendChild(wrap);
110
    const peers =  new Map();
111
    const host = SITE.presence.host;
112
    const socket = new PartySocket({ host, room: "live-cursors", party: "presence" });
113
    const ac = new AbortController();
114
    const { signal } = ac;
115
    const send = (s) => {
116
      try {
117
        socket.send(s);
118
      } catch {
119
      }
120
    };
121
    const hb = window.setInterval(() => send('{"type":"ping"}'), HEARTBEAT_MS);
122
    let selfX = 0;
123
    let selfY = 0;
124
    let hasSelf = false;
125
    let lastSend = 0;
126
    let sentX = -1;
127
    let sentY = -1;
128
    const maybeSend = (force = false) => {
129
      if (!hasSelf || socket.readyState !== 1) return;
130
      const now = performance.now();
131
      if (!force && now - lastSend < SEND_MS) return;
132
      if (!force && selfX === sentX && selfY === sentY) return;
133
      send(JSON.stringify({ type: "cursor", x: clamp01(selfX), y: clamp01(selfY) }));
134
      sentX = selfX;
135
      sentY = selfY;
136
      lastSend = now;
137
    };
138
    if (finePointer) {
139
      wrap.addEventListener(
140
        "pointermove",
141
        (e) => {
142
          const r = wrap.getBoundingClientRect();
143
          if (r.width === 0 || r.height === 0) return;
144
          selfX = (e.clientX - r.left) / r.width;
145
          selfY = (e.clientY - r.top) / r.height;
146
          hasSelf = true;
147
          maybeSend();
148
        },
149
        { signal }
150
      );
151
    }
152
    const keepalive = window.setInterval(() => {
153
      if (!document.hidden) maybeSend(true);
154
    }, KEEPALIVE_MS);
155
    socket.addEventListener("message", (e) => {
156
      let m;
157
      try {
158
        m = JSON.parse(e.data);
159
      } catch {
160
        return;
161
      }
162
      if (m.type === "cursors" && Array.isArray(m.c)) {
163
        for (const c of m.c) {
164
          if (!Array.isArray(c) || typeof c[0] !== "string" || c[0] === socket.id) continue;
165
          if (typeof c[1] !== "number" || typeof c[2] !== "number") continue;
166
          upsert(c[0], clamp01(c[1]), clamp01(c[2]));
167
        }
168
      } else if (m.type === "cursor" && typeof m.id === "string" && typeof m.x === "number" && typeof m.y === "number") {
169
        upsert(m.id, clamp01(m.x), clamp01(m.y));
170
      } else if (m.type === "leave" && typeof m.id === "string") {
171
        remove(m.id);
172
      }
173
    });
174
    function upsert(id, x, y) {
175
      let p = peers.get(id);
176
      if (!p) p = create(id, x, y);
177
      if (x > p.tx + 4e-3) p.dir = 1;
178
      else if (x < p.tx - 4e-3) p.dir = -1;
179
      p.tx = x;
180
      p.ty = y;
181
      p.last = performance.now();
182
      if (reduced) {
183
        p.x = x;
184
        p.y = y;
185
      }
186
      hint.style.opacity = "0";
187
    }
188
    function create(id, x, y) {
189
      const color = colorFor(id);
190
      const el = document.createElement("div");
191
      el.className = "lc__peer";
192
      const ptr = document.createElement("span");
193
      ptr.className = "lc__ptr";
194
      ptr.style.color = color;
195
      const name = document.createElement("span");
196
      name.className = "lc__name";
197
      name.style.background = color;
198
      name.textContent = nameFor(id);
199
      ptr.innerHTML = rightSvg;
200
      el.appendChild(ptr);
201
      el.appendChild(name);
202
      el.style.transform = `translate3d(${x * W}px, ${y * H}px, 0) scale(${P.size})`;
203
      wrap.appendChild(el);
204
      const p = { id, tx: x, ty: y, x, y, dir: 1, shownDir: 1, last: performance.now(), el, ptr };
205
      return peers.set(id, p), p;
206
    }
207
    function remove(id) {
208
      const p = peers.get(id);
209
      if (!p) return;
210
      p.el.remove();
211
      peers.delete(id);
212
      if (peers.size === 0) hint.style.opacity = "1";
213
    }
214
    let W = wrap.clientWidth;
215
    let H = wrap.clientHeight;
216
    const ro = new ResizeObserver(() => {
217
      W = wrap.clientWidth;
218
      H = wrap.clientHeight;
219
    });
220
    ro.observe(wrap);
221
    const tick = (_time, dtMs) => {
222
      const now = performance.now();
223
      const dt = Math.min(dtMs, 50) / 1e3;
224
      const alpha = reduced ? 1 : 1 - Math.exp(-P.smoothing * dt);
225
      for (const p of peers.values()) {
226
        if (now - p.last > STALE_MS) {
227
          remove(p.id);
228
          continue;
229
        }
230
        p.x += (p.tx - p.x) * alpha;
231
        p.y += (p.ty - p.y) * alpha;
232
        p.el.style.transform = `translate3d(${p.x * W}px, ${p.y * H}px, 0) scale(${P.size})`;
233
        if (p.dir !== p.shownDir) {
234
          p.ptr.innerHTML = p.dir === 1 ? rightSvg : leftSvg;
235
          p.shownDir = p.dir;
236
        }
237
      }
238
    };
239
    gsap.ticker.add(tick);
240
    const set = (key, value) => {
241
      if (key in P) P[key] = Number(value);
242
    };
243
    const destroy = () => {
244
      ac.abort();
245
      window.clearInterval(hb);
246
      window.clearInterval(keepalive);
247
      gsap.ticker.remove(tick);
248
      ro.disconnect();
249
      try {
250
        socket.close();
251
      } catch {
252
      }
253
      peers.forEach((p) => p.el.remove());
254
      peers.clear();
255
      wrap.remove();
256
    };
257
    return { destroy, set };
258
  }
259
};
260
experiment.mount(document.querySelector(".stage"));

Live Cursors

InteractionNew

Experiment coming soonLoading experiment

Live Cursors — Lab experiment