Page Visibility API: Know when a user is on your page

Reading time: 30 minutes

There was a need for the developers to know when a user is leaving the page. There are three events that can help us achieve this task. They are:

• pagehide
• beforeunload
• unload events.

However, these events may not be triggered on the phone and the page is closed directly, as the mobile system can transfer a process into the background directly and then kill it.

The situations that pages were switched by the system and the system cleared the browser process, couldn't be monitored. And it was impossible for developers to specify the code that can be executed under any case of unloading a page. In order to solve this problem, Page Visibility API was introduced. The API will listen to any visible change of the page under all the cases, regardless of that, it's on the the phone or desktop.

The Page Visibility API can be used to predict the unloading of the web page. Also, it can save resources by slowing down the consumption of power.

For Example, it can be used to pause a video playback, when the user is not looking at the page.

1. The document.visibilityState property

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

• hidden：The page is completely invisible.
• visible：The page is visible.
• prerender：The page is about to be or is being rendered and it is invisible.

The hidden and visible states are supported by all browsers. The prerender state only appears on browsers that support "pre-rendering". For example, the Chrome browser has a pre-rendering function which can render the page in advance under the invisible state to users, and display the rendered we bpage directly when the user wants to browse the page.

The document.visibilityState property returns visible, even if only a part of a web page is visible to the user. The value of document.visibilityState returns hidden only if,

• The browser is minimized.
• Though the browser is not minimized, the current page is switched to be a background page.
• The browser will unload the page.
• The operating system triggers the lock screen.

▶ Important: In addition, in the earlier version of the API, there is a fourth value unloaded which is used to indicate that the page is about to be unloaded, which is now deprecated.

2. The document.hidden property

This property returns a boolean value, which indicates that the current page is visible or not.
The document.hidden property returns false when the document.visibilityState property returns visible. In other cases, it returns true.

▶ Important: The property is reserved for historical reasons only, and whenever possible, you should use the document.visibilityState property instead.

3. The visibilitychange event

The visibilitychange event will be triggered as long as the document.visibilityState property changes. Thus, we can track changes on page visibility by listening to this event through document.addEventListener() method or the document.onvisibilitychange property. The below example shows the basic usage of this event.

Example 1:

document.addEventListener('visibilitychange', function () {
  // The user leaves the current page.
  if (document.visibilityState === 'hidden') {
    alert('Page is not visible');
  }

  // The user opens or returns to the page.
  if (document.visibilityState === 'visible') {
    alert('Page is visible');
  }
});

It can be also used to automatically pause a video when the user is not viewing the web page. The code snippet below shows an example of this feature.

Example 2:

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

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

Output of Example 2:

The Video will Stop playing when you switch to other tab or minimize the browser. Your browser does not support the video tag.

4. Page Unloading

There can be three situations about unloading a page. Firstly, the page is visible, the user closes the Tab page or the browser window. Secondly, the page is visible, the user goes to another page from the current window. Lastly, the page is not visible, the user or system closes the browser window. All of the three cases will trigger the visibilitychange event. Under the first two cases, the event is triggered when the user leaves the page. And, under the last case, the event is triggered when the page changes from the visible state to the invisible state.