This specification defines a means to programmatically determine the visibility state of a document. This can aid in the development of resource efficient web applications.
Pave Visility Level 2 replaces the first version of [[PAGE-VISIBILITY]] and includes:
VisibilityState.unloaded
has been removed.hidden
when the user agent is unloading a document;The Page Visibility API defines a means to programmatically determine the visibility state of a top level browsing context, and to be notified if the visibility state changes. Without knowing the visibility state of a page, web developers have been designing web pages as if they are always visible. This not only results in higher machine resource utilization, but it prevents web developers from making runtime decisions based on whether the web page is visible to the user. Designing web pages with knowledge of the page's visibility state can result in improved user experiences and power efficient sites.
With this API, web applications can choose to alter their behavior based on whether they are visible to the user or not. For example, this API can be used to scale back work when the page is no longer visible.
To improve the user experience and optimize CPU and power efficiency the application could autoplay a video when the application is visible, and automatically pause the playback when the application is hidden:
var videoElement = document.getElementById("videoElement"); // pause video buffering if page is being prerendered if (document.visibilityState == "prerender") { // ... } // Autoplay the video if application is visible if (document.visibilityState == "visible") { videoElement.play(); } // Handle page visibility change events function handleVisibilityChange() { if (document.visibilityState == "hidden") { videoElement.pause(); } else { videoElement.play(); } } document.addEventListener('visibilitychange', handleVisibilityChange, false);
Similar logic can be applied to intellegently pause and resume, or
throttle, execution of application code such as animation loops,
analytics, and other types of processing. By combining the
visibilityState
attribute of the Document interface
and the visibilitychange
event, the application is able to
both query and listen to page visibility events to deliver a better
user experience, as well as improve efficiency and performance of its
execution.
VisibilityState
enum
The Document of the top level browsing context can be in one of the following visibility states:
hidden
attribute is set to false
.
The visibility states are reflected in the API via the VisibilityState enum.
enum VisibilityState { "hidden", "visible", "prerender" };
This specification extends the [[!HTML51]] Document interface:
partial interface Document { readonly attribute boolean hidden; readonly attribute VisibilityState visibilityState; attribute EventHandler onvisibilitychange; };
hidden
attribute
On getting, the hidden attribute MUST run the steps to determine if the document is hidden:
visible
, then return false
.
true
.
Support for hidden
attribute is maintained for
historical reasons. Developers should use
visibilityState
where possible.
visibilityState
attribute
On getting, the visibilityState attribute the user agent MUST run the steps to determine the visibility state:
Document
of the top
level browsing context.
defaultView
of doc is
null
, return hidden
.
To accommodate assistive technologies that are typically full screen
but still show a view of the page, when applicable, on getting, the
visibilityState
attribute MAY return
visible
, instead of hidden
, when the user
agent is not minimized but is fully obscured by other applications.
onvisiblitychange
event handler
onvisibilitychange is an event handler IDL attribute for the visibilitychange event type.
The task source for these tasks is the user interaction task source.
When the user agent determines that the visibility of the Document of the top level browsing context has changed, the user agent MUST run the following steps:
pageshow
event.
The now visible algorithm runs the following steps synchronously:
visibilitychange
that
bubbles, isn't cancelable, and has no default action, at the
doc.
The now hidden algorithm runs the following steps synchronously:
visibilitychange
that
bubbles, isn't cancelable, and has no default action, at the
doc.
The Page Visibility API enables developers to know when a
Document is visible or in focus. Existing mechanisms, such as
the focus
and blur
events, when attached to
the Window
object already provide a mechanism to detect
when the Document is the active document; the unload
event provides a notification that the page is being unloaded. This API
extends these capabilities by also exposing the prerender
state of the Document—see [[!RESOURCE-HINTS]] security and privacy
section for relevant considerations and best practices on the use of
prerender—and unifies all of the above in a single API to simplify
development of visibility-aware and efficient applications.
The following concepts and interfaces are defined in the [[!HTML51]] specification:
defaultView
pageshow
Document
blur
focus
The [[!DOM4]] specification defines how to fire a simple event.
Thanks to Alex Komoroske, Arvind Jain, Boris Zbarsky, Cameron McCormack, James Robinson, Jason Weber, Jonas Sicking, Karen Anderson, Kyle Simpson, Nat Duca, Nic Jansma, Philippe Le Hegaret, and Todd Reifsteck for their contributions to this work.