Pause polling in hidden tabs

How to do it

People leave tabs open for days, and each one that polls every few seconds adds load for nobody. Browsers throttle timers in hidden tabs anyway, so the data there is stale whatever you do. Listen for visibilitychange and stop the timers when document.visibilityState is hidden. Refetch when it turns visible. Data libraries such as TanStack Query do this when refetchIntervalInBackground is off. Updates that must reach a hidden tab come over one live connection, as choose the transport that the feature needs says.

Examples

TypeScript example

const POLL_INTERVAL_MS = 30_000;

export function pollWhileVisible(refresh: () => void) {
  let timer: number | undefined;
  const start = () => { timer = window.setInterval(refresh, POLL_INTERVAL_MS); };
  const stop = () => window.clearInterval(timer);
  document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'hidden') return stop();
    refresh();
    start();
  });
  if (document.visibilityState === 'visible') start();
}

Python example

HIDE_PAGE = """
Object.defineProperty(document, 'visibilityState', { value: 'hidden', configurable: true });
document.dispatchEvent(new Event('visibilitychange'));
"""

def test_hidden_tab_stops_polling(page):
    page.goto("https://app.example.com/dashboard")
    page.evaluate(HIDE_PAGE)
    polls = []
    page.on("request", lambda request: "/api/stats" in request.url and polls.append(request))
    page.clock.run_for(120_000)
    assert polls == []

How to check

A browser test opens a dashboard, sets the page hidden and fires visibilitychange, then counts requests for 2 minutes. It sees 0 polling requests. After the page turns visible, 1 refresh request goes out within 1 second.

Sources

• HTML Standard on page visibility

Related rules

• API-69 Choose the transport that the feature needs in API design