MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla

Revision 26384 of Using the Page Visibility API

  • Revision slug: DOM/Using_the_Page_Visibility_API
  • Revision title: Using the Page Visibility API
  • Revision id: 26384
  • Created:
  • Creator: teoli
  • Is current revision? No
  • Comment Removed See also as not related to the page; 3 words removed

Revision Content

{{ SeeCompatTable() }}

With tabbed browsing, there’s a reasonable chance that any given web page is in the background and thus not visible to the user. Some sites might want to behave differently in such a case. A few examples:

  • A site has an image carousel that shouldn’t advance to the next slide unless the user is viewing the page
  • An application showing a dashboard of information doesn’t want to poll the server for updates when the page isn’t visible
  • A page wants to detect when it is being prerendered so it can keep accurate count of page views

Developers have historically used imperfect proxies to detect this. For example, registering an onblur/onfocus handler on the window helps you know when your page is not the active page, but it does not tell you that your page is hidden to the user.

document.hidden

Returns true if the page is in a state considered to be hidden to the user, and false otherwise.

document.visibilityState

Returns a string denoting the visibility state of the document. Possible Values:

  • “visible” : the page content may be at least partially visible.  In practice this means that the page is the foreground tab of a non-minimized window. 
  • “hidden” : the page content is not visible to the user.  In practice this means that the document is either a background tab or part of a minimized window.
  • “prerender” : the page content is being prerendered and is not visible to the user (considered hidden for purposes of document.webkitVisible).  The document may start in this state, but will never transition to it from another value.

//startSimulation and pauseSimulation defined elsewhere

function handleVisibilityChange() {
if (document.hidden) {
        pauseSimulation();
} else {
        startSimulation();
}
}
document.addEventListener("visibilitychange", handleVisibilityChange, false);
<meta charset="utf-8"/>

Example

View live example (video with sound). (Warning: really poor example as it works only in Chrome as it uses only one prefix!)

Specifications

Specification Status Comment
W3C Page Visibility API {{ Spec2('Page Visibility API') }}  

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome (Webkit) Firefox (Gecko)* Internet Explorer Opera Safari (WebKit)
Basic support

13 {{ property_prefix("webkit") }}

10 {{ property_prefix("moz") }} 10 {{ property_prefix("ms") }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Revision Source

<p>{{ SeeCompatTable() }}</p>
<p>With tabbed browsing, there’s a reasonable chance that any given web page is in the background and thus not visible to the user. Some sites might want to behave differently in such a case. A few examples:</p>
<ul> <li>A site has an image carousel that shouldn’t advance to the next slide unless the user is viewing the page</li> <li>An application showing a dashboard of information doesn’t want to poll the server for updates when the page isn’t visible</li> <li>A page wants to detect when it is being prerendered so it can keep accurate count of page views</li>
</ul>
<p>Developers have historically used imperfect proxies to detect this. For example, registering an onblur/onfocus handler on the window helps you know when your page is not the active page, but it does not tell you that your page is hidden to the user.</p>
<h4>document.hidden</h4>
<p>Returns true if the page is in a state considered to be hidden to the user, and false otherwise.</p>
<h4>document.visibilityState</h4>
<p>Returns a string denoting the visibility state of the document. Possible Values:</p>
<ul> <li>“visible” : the page content may be at least partially visible.  In practice this means that the page is the foreground tab of a non-minimized window. </li> <li>“hidden” : the page content is not visible to the user.  In practice this means that the document is either a background tab or part of a minimized window.</li> <li>“prerender” : the page content is being prerendered and is not visible to the user (considered hidden for purposes of document.webkitVisible).  The document may start in this state, but will never transition to it from another value.</li>
</ul>
<div class="note"> <p>//startSimulation and pauseSimulation defined elsewhere</p> <div style="background-color: transparent; margin-top: 0px; margin-left: 0px; margin-bottom: 0px; margin-right: 0px; color: rgb(0, 0, 0); line-height: normal; "><span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; ">function handleVisibilityChange() {</span><br> <span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; "> if (document.hidden) {</span><br>         <span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; ">pauseSimulation();</span><br> <span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; "> } else {</span><br>         <span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; ">startSimulation();</span><br> <span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; "> }</span><br> <span style="font-size: 11pt; font-family: 'Courier New'; color: rgb(0, 0, 0); background-color: transparent; font-weight: normal; font-style: normal; font-variant: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap; ">}</span></div> <div style="background-color: transparent; margin-top: 0px; margin-left: 0px; margin-bottom: 0px; margin-right: 0px; color: rgb(0, 0, 0); line-height: normal; "><code>document.addEventListener("visibilitychange", handleVisibilityChange, false);</code></div> <code>&lt;meta charset="utf-8"/&gt;</code></div>
<h2 name="Example">Example</h2>
<p>View <a class="external" href="http://www.samdutton.com/pageVisibility/">live example</a> (video with sound). (Warning: really poor example as it works only in Chrome as it uses only one prefix!)</p><h2>Specifications</h2>
<table class="standard-table"> <thead> <tr style="background-color: rgb(255, 204, 255);"> <th scope="col">Specification</th> <th scope="col">Status</th> <th scope="col">Comment</th> </tr> </thead> <tbody> <tr> <td><a class="external" href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html" title="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html">W3C Page Visibility API</a></td> <td>{{ Spec2('Page Visibility API') }}</td> <td> </td> </tr> </tbody>
</table>
<h2 name="Browser_Compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Chrome (Webkit)</th> <th>Firefox (Gecko)*</th> <th>Internet Explorer</th> <th>Opera</th> <th>Safari (WebKit)</th> </tr> <tr> <td>Basic support</td> <td> <p>13 <a class="external" href="http://blogs.msdn.com/b/ie/archive/2011/07/08/using-pc-hardware-more-efficiently-in-html5-new-web-performance-apis-part-2.aspx" title="http://blogs.msdn.com/b/ie/archive/2011/07/08/using-pc-hardware-more-efficiently-in-html5-new-web-performance-apis-part-2.aspx"></a> {{ property_prefix("webkit") }}</p> </td> <td>10 <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=690056" title="https://bugzilla.mozilla.org/show_bug.cgi?id=690056"></a> {{ property_prefix("moz") }}</td> <td>10 <a class="external" href="http://blogs.msdn.com/b/ie/archive/2011/07/08/using-pc-hardware-more-efficiently-in-html5-new-web-performance-apis-part-2.aspx" title="http://blogs.msdn.com/b/ie/archive/2011/07/08/using-pc-hardware-more-efficiently-in-html5-new-web-performance-apis-part-2.aspx"></a> {{ property_prefix("ms") }}</td> <td>{{ CompatNo() }}</td> <td>{{ CompatNo() }}</td> </tr> </tbody> </table>
</div>
<div id="compat-mobile"> <table class="compat-table"> <tbody> <tr> <th>Feature</th> <th>Android</th> <th>Firefox Mobile (Gecko)</th> <th>IE Phone</th> <th>Opera Mobile</th> <th>Safari Mobile</th> </tr> <tr> <td>Basic support</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> <td>{{ CompatUnknown() }}</td> </tr> </tbody> </table>
</div>
Revert to this revision