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
Specification |
---|
HTML Standard # event-visibilitychange |
HTML Standard # handler-onvisibilitychange |
Browser compatibility
BCD tables only load in the browser
See also
- Page Visibility API
Document.visibilityState
- Don't lose user and app state, use Page Visibility explains in detail why you should use
visibilitychange
, notbeforeunload
/unload
. - Page Lifecycle API gives best-practices guidance on handling page lifecycle behavior in your web applications.