Page Visibility API

TL;DR

Explanation

document.visibilityState is 'visible' or 'hidden'. The visibilitychange event fires when it changes. Use cases: pause autoplay video when tab hides, stop polling when hidden (save bandwidth/battery), pause Canvas animations, pause WebSocket reconnection attempts. document.hidden is a boolean shorthand. The API fires reliably on tab switch, minimise, and screen lock. On mobile, it fires on home button press. Page Visibility should be the primary trigger for any 'pause when not visible' logic.

Common Misconception

Why It Matters

Common Mistakes

• Using blur/focus events instead of visibilitychange for tab-switch detection.
• Not pausing WebSocket reconnection when page is hidden — wastes connections.
• Not resuming state when page becomes visible again.

Code Examples

// Always polling regardless of tab visibility:
setInterval(fetchUpdates, 5000);

let pollInterval;

function startPolling() {
    pollInterval = setInterval(fetchUpdates, 5000);
}

function stopPolling() {
    clearInterval(pollInterval);
}

document.addEventListener('visibilitychange', () => {
    document.hidden ? stopPolling() : startPolling();
});

startPolling(); // Start initially

References

• ↗ https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API

Tags

Related Terms