Page Visibility API

Page Visibility API

Sometimes, developers need to know that the user is leaving the page. The common method is to listen for the following three events.

  • pagehide
  • beforeunload
  • unload

However, these events may not fire on the phone, and the page just closes. Because the mobile phone system can directly transfer a process to the background and then kill it.

  • The user taps a system notification to switch to another app.
  • The user enters the task switching window and switches to another app.
  • The user clicked the Home button to switch back to the home screen.
  • The operating system automatically switches to another app (eg, when a phone call is received).

The above situations will cause the mobile phone to switch the browser process to the background, and then in order to save resources, the browser process may be killed.

Previously, the page was switched by the system and the system cleared the browser process, which could not be monitored. The developer wants to specify the code that will be executed in any kind of page unload situation, which is also impossible. To solve this problem, the Page Visibility API was born. In all cases, mobile or desktop, this API will listen for changes in the visibility of the page.

The significance of this new API is that by monitoring the visibility of web pages, it can predict the uninstallation of web pages, and can also be used to save resources and slow down power consumption. For example, once the user does not view the webpage, the following webpage behaviors can be suspended.

  • polling the server
  • Web animation
  • the audio or video that is playing


This API mainly adds a document.visibilityState property on the document object. This property returns a string representing the current visibility state of the page, with three possible values.

  • hidden: The page is completely invisible.
  • visible: At least part of the page is visible.
  • prerender: The page is about to be or is being rendered, in an invisible state.

Among them, hidden state and visible state are all browsers must support. The prerender state will only appear on browsers that support “pre-rendering”. For example, the Chrome browser has a pre-rendering function, which can render the page in advance when the user is invisible, and wait until the user wants to browse. , which directly displays the rendered web page.

The document.visibilityState property returns visible as long as the page is visible, even if only one corner is exposed. hidden is returned only in the following four cases.

  • Browser minimized.
  • The browser is not minimized, but the current page is switched to the background page.
  • The browser is about to unload the page.
  • The OS triggers the lock screen.

It can be seen that the above four scenarios cover all situations in which the page may be unloaded. That is, before the page is unloaded, the document.visibilityState property must become hidden. In fact, this is the main purpose of designing this API.

In addition, in earlier versions of the API, this attribute had a fourth value of unloaded, which indicated that the page was about to be unloaded, and is now deprecated.

Note that the document.visibilityState property is only for the top-level window, and the document.visibilityState property of the embedded <iframe> page is determined by the top-level window. Hiding the <iframe> page using CSS properties (eg display: none;) does not affect the visibility of the inline page.


For historical reasons, this API also defines the document.hidden property. This property is read-only and returns a boolean value indicating whether the current page is visible.

When the document.visibilityState property returns visible, the document.hidden property returns false; otherwise, it returns true.

This property is only reserved for historical reasons, and whenever possible, the document.visibilityState property should be used instead of this property.

visibilitychange event

The visibilitychange event is fired whenever the document.visibilityState property changes. Therefore, changes in page visibility can be tracked by listening to this event (via the document.addEventListener() method or the document.onvisibilitychange property).

document.addEventListener('visibilitychange', function () {
  // The user has left the current page
  if (document.visibilityState === 'hidden') {
    document.title = 'Page not visible';

  // User opens or returns to the page
  if (document.visibilityState === 'visible') {
    document.title = 'Page visible';

The above code is the most basic usage of Page Visibility API, which can monitor visibility changes.

Here’s another example that pauses the video once the page is not visible.

var vidElem = document.getElementById('video-demo');
document.addEventListener('visibilitychange', startStopVideo);

function startStopVideo() {
  if (document.visibilityState === 'hidden') {
  } else if (document.visibilityState === 'visible') {;

page unload

Let’s discuss how to properly monitor page unloading.

Page unloading can be divided into three situations.

  • User closes the tab page or browser window while the page is visible.
  • When the page is visible, the user goes to another page in the current window.
  • The user or the system closes the browser window when the page is not visible.

In all three cases, the visibilitychange event will be triggered. In the first two cases, the event fires when the user leaves the page; in the last case, the event fires when the page changes from a visible state to an invisible state.

It can be seen that the visibilitychange event is more reliable than the pagehide, beforeunload, unload events, and fires in all cases (from visible to hidden). Therefore, you can only listen to this event, and run the code that needs to be run when the page is unloaded, without listening to the latter three events.

It can even be said that the unload event does not need to be monitored under any circumstances, and the beforeunload event has only one applicable scenario, that is, the user modifies the form and leaves the current page without submitting it. On the other hand, if the listener functions for these two events are specified, the browser will not cache the current page.

Reference link