Page visibility

Article
11/03/2017

Note The Visibility API may not work correctly for Windows apps using JavaScript in Windows 8.

Internet Explorer 10 introduced support for the Page Visibility API, which provides a means for developers to use programming techniques to determine the current visibility of a document and be notified when the visibility changes. Without knowing the visibility state of a page, a web developer must design the webpage with the assumption that it is always visible. This results in higher machine resource utilization and it prevents web developers from making runtime decisions based on whether the webpage is visible to the user.

The Page Visibility API

Knowing the page visibility when designing webpages will allow for improved user experiences and power efficient sites. The Page Visibility API makes this possible. It consists of the following two properties.

Property	Description
document.hidden	A Boolean value that describes whether the page is visible or not.
document.visibilityState	Returns the page visibility state. Values include PAGE_VISIBLE, PAGE_PREVIEW, and so on.

The Page Visibility API also exposes the following event.

Event	Description
visibilitychange	An event that gets fired anytime the visibility state of the page changes.

By using this API, web applications can choose to alter behavior based on whether they are visible to the user or not. This API can be used to scale back work when the page is no longer visible. For example, if a web-based email client is visible, it might check the server for new mail every few seconds. When hidden, it might scale back so it checks email every few minutes instead of every few seconds. This API can also be used to provide a more effective user experience in situations not related to power management. For example, a puzzle game could be paused when the user no longer has the game visible. Similarly, advertisers could use it to not charge for ads when they are not visible to viewers.

Code Examples

The following JavaScript example demonstrates a technique for checking email without knowing if the page is visible or not. The code will always check for email every second even if the user is not actively viewing the page because it is not visible. This is an example of poor resource management.

<!DOCTYPE html>
<html>
<head>
  <script>
   var timer = 0;
   var PERIOD = 1000;   function onLoad() {
       timer = setInterval(checkEmail, PERIOD);
   }
   function checkEmail() { 
       // Check server for new emails
   }
  </script>
</head>
<body onload="onLoad()">
</body>
</html>

Page visibility can improve resource management because it can check email less frequently when the page is not visible. The following code shows a technique for using page visibility that checks for new emails every second when the page is visible and every minute when it is not.

<!DOCTYPE html>
<html>
<head>
  <script>
   var timer = 0;
   var PERIOD_VISIBLE = 1000;
   var PERIOD_NOT_VISIBLE = 60000;
   function onLoad() {
       timer = setInterval(checkEmail, (document.hidden) ? PERIOD_NOT_VISIBLE : PERIOD_VISIBLE);
       if(document.addEventListener) document.addEventListener("visibilitychange", visibilityChanged);
   }  
   function visibilityChanged() {
       clearTimeout(timer);
       timer = setInterval(checkEmail, (document.hidden) ? PERIOD_NOT_VISIBLE : PERIOD_VISIBLE);
   }  
   function checkEmail() { 
       // Check server for new emails
   }
  </script>
</head>
<body onload="onLoad()">
</body>
</html>