W3cubDocs

/Web APIs

Document: visibilitychange event

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 addEventListener(), or set an event handler property.

js

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

onvisibilitychange = (event) => {};

Event type

A generic Event.

Usage notes

The event doesn't include the document's updated visibility status, but you can get that information from the document's 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 begins playing a music track when the document becomes visible, and pauses the music when the document is no longer visible.

js

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    backgroundMusic.play();
  } else {
    backgroundMusic.pause();
  }
});

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 Navigator.sendBeacon() API:

js

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

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
visibilitychange_event 62
33The onvisibilitychange event handler property is not supported.
13The onvisibilitychange event handler property is not supported.
18
12The onvisibilitychange event handler property is not supported.
56
10The onvisibilitychange event handler property is not supported.
49
20The onvisibilitychange event handler property is not supported.
15The onvisibilitychange event handler property is not supported.
12.1–15The onvisibilitychange event handler property is not supported.
14.1
14Doesn't fire the visibilitychange event when navigating away from a document, so also include code to check for the pagehide event (which does fire for that case in all current browsers). See WebKit bugs 116769, 151234, 151610, and 194897.
10.1["Doesn't fire the visibilitychange event when navigating away from a document, so also include code to check for the pagehide event (which does fire for that case in all current browsers). See WebKit bugs 116769, 151234, 151610, and 194897.", "Before Safari 14, the event does not bubble, so document.addEventListener('visibilitychange', ...) works, but window.addEventListener('visibilitychange', ...) does not."]
7["Doesn't fire the visibilitychange event when navigating away from a document, so also include code to check for the pagehide event (which does fire for that case in all current browsers). See WebKit bugs 116769, 151234, 151610, and 194897.", "Before Safari 14, the event does not bubble, so document.addEventListener('visibilitychange', ...) works, but window.addEventListener('visibilitychange', ...) does not.", "The onvisibilitychange event handler property is not supported."]
62
≤37The onvisibilitychange event handler property is not supported.
4.4.3The onvisibilitychange event handler property is not supported.
62
33The onvisibilitychange event handler property is not supported.
18The onvisibilitychange event handler property is not supported.
56 46
20The onvisibilitychange event handler property is not supported.
14The onvisibilitychange event handler property is not supported.
12.1–14The onvisibilitychange event handler property is not supported.
14.5
14Doesn't fire the visibilitychange event when navigating away from a document, so also include code to check for the pagehide event (which does fire for that case in all current browsers). See WebKit bugs 116769, 151234, 151610, and 194897.
10.3["Doesn't fire the visibilitychange event when navigating away from a document, so also include code to check for the pagehide event (which does fire for that case in all current browsers). See WebKit bugs 116769, 151234, 151610, and 194897.", "Before Safari 14, the event does not bubble, so document.addEventListener('visibilitychange', ...) works, but window.addEventListener('visibilitychange', ...) does not."]
7["Doesn't fire the visibilitychange event when navigating away from a document, so also include code to check for the pagehide event (which does fire for that case in all current browsers). See WebKit bugs 116769, 151234, 151610, and 194897.", "Before Safari 14, the event does not bubble, so document.addEventListener('visibilitychange', ...) works, but window.addEventListener('visibilitychange', ...) does not.", "The onvisibilitychange event handler property is not supported."]
8.0
2.0The onvisibilitychange event handler property is not supported.
1.0The onvisibilitychange event handler property is not supported.

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event