Web APIsBaseline · Widely

Beacon API and visibilitychange Lifecycle

Mental Model

navigator.sendBeacon() hands a small POST payload (up to 64 KB) to the browser's network process so transmission finishes after the tab closes. Firing it on visibilitychange (hidden) instead of unload captures mobile app switches and keeps bfcache intact.

Interactive Simulator

Page-Exit Telemetry: unload + XHR vs visibilitychange + sendBeacon

Lines of Code
Before
5
After
5
Reflows / Browser Cost
Before
Kills bfcache
After
0 ms exit delay
Beforewindow.onunload + Sync XHR (Broken)
window.addEventListener('unload', () => {
  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/telemetry', false);
  xhr.send(payload); // Blocks navigation & kills bfcache
});
Lines: 5Reflows: Kills bfcacheDependencies: 0 kB

Fails on mobile backgrounding, stalls page exit, disqualifies bfcache.

After (Native)visibilitychange + navigator.sendBeacon
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    navigator.sendBeacon('/telemetry', new Blob([payload], { type: 'application/json' }));
  }
});
Lines: 5Reflows: 0 ms exit delayDependencies: 0 kB

Preserves bfcache; browser network process delivers POST in background.

Under the Hood

navigator.sendBeacon() hands the serialized payload directly to the browser's network process over IPC, decoupling socket transmission from the renderer lifecycle. Unlike fetch() without keepalive, which aborts on tab close, the network process finishes delivery after the renderer tears down.

  1. Reliable Trigger: Mobile browsers freeze or kill backgrounded tabs without firing unload; document.visibilityState === 'hidden' fires reliably when switching tabs or locking the screen.
  2. 64 KB Keepalive Pool: All pending beacons and fetch(..., { keepalive: true }) requests share a strict 64 KB per-origin buffer; sendBeacon() returns false if full.
  3. CORS Constraints: Passing a Blob with application/json triggers a CORS preflight on cross-origin endpoints; text/plain or FormData avoids preflight overhead.
JS
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState !== 'hidden') return;
  const body = JSON.stringify({ route: location.pathname, ts: Date.now() });
  const queued = navigator.sendBeacon('/api/telemetry', body);
  if (!queued) {
    localStorage.setItem('pending-telemetry', body);
  }
});

Problem Genealogy

  • 2006–2013 (Synchronous XHR on unload): Stalled the next page's navigation by hundreds of milliseconds while waiting for analytics TCP handshakes.
  • 2014 (W3C Beacon API): Delegated fire-and-forget POSTs to the browser process with zero exit delay.
  • 2019+ (bfcache & fetch keepalive): Deprecated unload across engines in favor of visibilitychange + pagehide + keepalive fetches.

Production Pitfalls

Production Pitfall
  • Wiring sendBeacon() to unload: Any unload listener disqualifies the document from bfcache in Chrome and Firefox; use visibilitychange and pagehide.
  • Ignoring the boolean return value: sendBeacon() never throws on quota overflow, it silently returns false when the 64 KB buffer is exhausted.
When Not to Use
  • When not to use sendBeacon(): If your code needs the HTTP response status, custom Authorization headers, or payloads > 64 KB, use fetch(..., { keepalive: true }) (for headers/status within 64 KB) or flush eagerly before exit; unlike Async Clipboard, sendBeacon() requires no transient user activation.

Connections & Logical Next Steps

Mechanical Comparisons