Document: visibilitychange event

{{APIRef}}

The visibilitychange event is fired at the document when the contents of its tab have become visible or have been hidden.

The event is not cancelable.

Syntax

Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}} , or set an event handler property.

addEventListener("visibilitychange", (event) => {});

onvisibilitychange = (event) => {};

Event type

A generic {{domxref("Event")}} .

Usage notes

The event doesn’t include the document’s updated visibility status, but you can get that information from the document’s {{domxref("Document.visibilityState", "visibilityState")}} property.

This event fires with a visibilityState of hidden when a user navigates to a new page, switches tabs, closes the tab, minimizes or closes the browser, or, on mobile, switches from the browser to a different app. Transitioning to hidden is the last event that’s reliably observable by the page, so developers should treat it as the likely end of the user’s session (for example, for sending analytics data).

The transition to hidden is also a good point at which pages can stop making UI updates and stop any tasks that the user doesn’t want to have running in the background.

Examples

Pausing music on transitioning to hidden

This example pauses playing audio when the page is hidden and resumes playing when the page becomes visible again. For a full example, see the Page Visibility API: Pausing audio on page hide documentation.

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else {
    // Resume playing if audio was "playing on hide"
    if (playingOnHide) {
      audio.play();
    }
  }
});

Sending end-of-session analytics on transitioning to hidden

This example treats the transition to hidden as the end of the user’s session, and sends the appropriate analytics using the {{domxref("Navigator.sendBeacon()")}} API:

document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
};

Specifications

{{Specifications}}

Browser compatibility

{{Compat}}

docs.rodeo

MDN Web Docs mirror