English  

Deutsch  

Español  América Latina  

Français  

Indonesia  

Italiano  

Polski  

Português  Brasil  

Tiếng Việt  

Türkçe  

Русский  

עברית  

العربيّة  

فارسی  

ि  

 

 

    

    

 

 

 



















Resources  

More  



Baseline  

How to use Baseline  

Blog  

Case Studies  





Web Platform  

HTML  

CSS  

JavaScript  

User experience  

Performance  

Accessibility  

Identity  

Learn  

Learn HTML  

Learn CSS  

Learn JavaScript  

Learn AI  

Learn Performance  

Learn Accessibility  

More courses  

Additional resources  

AI and the web  

Explore  

PageSpeed Insights  

Patterns  

Podcasts & shows  

Developer Newsletter  

About web.dev  









Home  


Articles  

Using the Page Visibility APIay organized with collections   Save and categorize content based on your preferences.  






Ernest Delgado
Ernest Delgado  
X



Introduction


As Web developers, we tend to get excited by new technologies that enable us to create ever more engaging, interactive Web pages. 3D graphics with WebGL? Absolutely. Advanced audio capabilities with WebAudio? Sure thing. Real-time collaboration applications using the Web camera and microphone? Sign me up!

Less exciting, though equally important, are the technologies that allow us to build applications that run more efficiently and provide a better overall user experience. This is where an API like PageVisibility comes in.

The Page Visibility API performs a simple but important function  it lets your application know when a page is visible to the user. This basic piece of information enables the creation of Web pages that behave differently when they are not being viewed. Consider a few examples:


A Web page that retrieves information from a server can slow down its update cycle when not being actively viewed

A page that displays a rotating image carousel or video/audio content can pause until the user displays the page again

An application can decide to display notifications to the user only when it is hidden from view


At first, this API may not seem very useful beyond user convenience, but considering the huge increase in mobile Web browsing, anything that helps save the device's battery power becomes very important. By using the PageVisibility API, your site can help the user's device consume less power and last longer.



Browser Support


Chrome: 33.

Edge: 12.

Firefox: 18.

Safari: 7.


Source
 


The API specification, which as of this writing is in the Candidate Recommendation stage, provides both properties for detecting the document's visibility state as well as an event for responding to visibility changes.

In this tutorial, I'll cover the basics of the API and show how to apply it to some practical examples (feel free to skip ahead to them if you're the impatient type).

Document Visibility Properties


The current version of the PageVisibilityAPI spec defines two document properties: the boolean hiddenand the enumeration visibilityState. The visibilityState property currently has four possible values: hidden, visible, prerender, and unloaded.

As you might expect, the hidden attribute returns true when the document is not visible at all. Typically, this means that the document is either minimized, on a background tab, the OS's lock screen is up, etc. The attribute is set to false if any part of the document is at least partially visible on at least one display. In addition, to accommodate accessibility tools, the hidden attribute can be set to false when a tool such as a screen magnifier completely obscures the document, but is showing a view of it.

Dealing with vendor prefixes


To keep the focus on the code instead of all the vendor-specific prefixing, Im going to use some helper functions to isolate the browser-specifics. As soon as you drop support for Android 4.4 Browser you can remove this part and stick to the standard names.

function getHiddenProp(){
    var prefixes = ['webkit','moz','ms','o'];

    // if 'hidden' is natively supported just return it
    if ('hidden' in document) return 'hidden';

    // otherwise loop over all the known prefixes until we find one
    for (var i = 0; i < prefixes.length; i++){
        if ((prefixes[i] + 'Hidden') in document)
            return prefixes[i] + 'Hidden';
    }

    // otherwise it's not supported
    return null;
}

Document Properties Example


Now we can write a cross-browser function, isHidden(), to see if the document is visible.

function isHidden() {
    var prop = getHiddenProp();
    if (!prop) return false;

    return document[prop];
}

For a more granular view of the document's visibility, you can use the visibilityState property. This property returns one of four values:


hidden: the document is completely hidden from view

visible: the document is at least partially visible on at least one display device

prerender: the document is loaded off-screen and not visible (this value is optional; not all browsers will necessarily support it)

unloaded: if the document is to be unloaded, then this value will be returned (this value is optional; not all browsers will necessarily support it)

The VisibilityChange Event


In addition to the visibility properties, there is a visibilitychange event that fires whenever the document's visibility state changes. You can register an event listener for this event directly on the document object:

Event Example


// use the property name to generate the prefixed event name
var visProp = getHiddenProp();
if (visProp) {
  var evtname = visProp.replace(/[H|h]idden/,'') + 'visibilitychange';
  document.addEventListener(evtname, visChange);
}

function visChange() {
   var txtFld = document.getElementById('visChangeText');

   if (txtFld) {
      if (isHidden())
         txtFld.value += "Tab Hidden!\n";
      else
         txtFld.value += "Tab Visible!\n";
   }
}

Summary


Building a great Web application involves far more than just using the whiz-bang, eye catching features that users can see and interact with. A truly great application makes considerate use of the user's resources and attention, and the Page Visibility API is an important piece of that puzzle. To learn more about building resource-conscious Web applications, check out our other performance-related articles.

External References



W3C PageVisibility API Spec

Web Performance Working Group

PageVisibility example in IE10

Visibility.js - a polyfill for PageVisibility

isVis - another PageVisibility polyfill

 


Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2010-02-24 UTC.
 






We want to help you build beautiful, accessible, fast, and secure websites that work cross-browser, and for all of your users. This site is our home for content to help you on that journey, written by members of the Chrome team, and external experts.
 





File a bug  

See open issues  





Chrome for Developers  

Chromium updates  

Case studies  

Podcasts & shows  





@ChromiumDev on X  

YouTube  

Chrome for Developers on LinkedIn  

RSS  






Terms  

Privacy  





English  

Deutsch  

Español  América Latina  

Français  

Indonesia  

Italiano  

Polski  

Português  Brasil  

Tiếng Việt  

Türkçe  

Русский  

עברית  

العربيّة  

فارسی  

ि