JavaScript Document visibilitychange Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word VISIBILITYCHANGE

Definition

In JavaScript, the visibilitychange event fires on the document when its visibility status changes (MDN)—for example when the user switches tabs, navigates away, minimizes the browser, or switches apps on mobile.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for visibilitychange. Start with this line.

JavaScript
addEventListener("visibilitychange", …)
CallWhat it does
addEventListener("visibilitychange", …)Primary signature.

Built into the browser. Listen with document.addEventListener("visibilitychange", …) — no import required.

Library declarations
JavaScript
addEventListener("visibilitychange", …)

Parameters

ParameterDescription
ListenerRequired. addEventListener or onvisibilitychange
visibilityState / hiddenRequired. Current visibility after the change
Event objectOptional. Generic Event — no state fields

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Listen and Read visibilityState

Log the new state whenever visibility changes (MDN pattern).

JavaScript
document.addEventListener("visibilitychange", () => {
  console.log(document.visibilityState);
  // "visible" or "hidden"
});
Try It Yourself

How It Works

  1. Listen on document. Visibility changes are delivered here.
  2. Event has no payload. Read properties on document instead (MDN).
  3. Check visibilityState. Typically "visible" or "hidden".
  4. Test by switching tabs. Leave and return to see both values.

Example 2 — Pause Work When Hidden

MDN-style pattern: stop background work while the tab is not visible.

JavaScript
let timerId = null;

function startWork() {
  if (timerId) return;
  timerId = setInterval(() => {
    console.log("tick while visible");
  }, 1000);
}

function stopWork() {
  clearInterval(timerId);
  timerId = null;
  console.log("paused (hidden)");
}

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    stopWork();
  } else {
    startWork();
  }
});

if (!document.hidden) startWork();
Try It Yourself

How It Works

  1. Use document.hidden. Boolean shortcut for “not visible.”
  2. Stop on hide. Clear timers so work does not run in the background.
  3. Resume on show. Restart only if the page is visible again.
  4. Same idea for media. MDN pauses audio when hidden and resumes when visible.

Example 3 — Analytics with sendBeacon

Treat transition to hidden as end of session and ping the server (MDN).

JavaScript
document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    const payload = JSON.stringify({
      event: "session_end",
      t: Date.now()
    });
    // Replace "/log" with your analytics endpoint
    navigator.sendBeacon("/log", payload);
    console.log("beacon queued for hidden transition");
  }
};
Try It Yourself

How It Works

  1. Gate on hidden. Only send when visibilityState === "hidden".
  2. Use sendBeacon. Designed to finish sending even as the page unloads.
  3. Why here? MDN: transitioning to hidden is often the last reliable signal.
  4. Prefer over unload alone. unload / beforeunload are less reliable for analytics.
Compatibility

Browser Support

Document visibilitychange is part of the Page Visibility API. MDN marks it Baseline Widely available since April 2021 — safe for everyday use in modern browsers.

✓ Baseline Widely available

Document visibilitychange

Fires when the document becomes visible or hidden — read visibilityState or hidden inside the handler.

Wide Baseline
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
visibilitychange Widely available

Bottom line: Listen on document, read visibilityState/hidden, pause work when hidden, and prefer sendBeacon for end-of-session analytics.

Frequently Asked Questions

It fires on the document when visibility status changes — for example switching tabs, navigating away, minimizing the browser, or switching apps on mobile (MDN).
No. MDN marks Document visibilitychange as Baseline Widely available (since April 2021). It is not Deprecated, Experimental, or Non-standard.
Read document.visibilityState ("visible" or "hidden") or document.hidden. The Event object does not include the new state (MDN).
No. MDN states visibilitychange is not cancelable.
Transitioning to hidden is often the last reliably observable event. MDN recommends sending end-of-session data then (for example with navigator.sendBeacon).
Yes. Use document.onvisibilitychange or document.addEventListener("visibilitychange", …).

Next: scrollingElement

Learn which element is the document’s scrolling root.

scrollingElement tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

JavaScript Document selectionchange Event JavaScript Document scrollingElement Property