Copyright © 2018 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Page Visibility 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 Working Group expects to demonstrate 2 implementations of the
features listed in this specification by the end of the Candidate
Recommendation phase. prerender
is marked a feature at risk.
This document was published by the Web Performance Working Group as an Editor's Draft. Comments regarding this document are welcome. Please send them to public-web-perf@w3.org (subscribe, archives).
Please see the Working Group's implementation report.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 February 2018 W3C Process Document.
This section is non-normative.
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
.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST and SHOULD are to be interpreted as described in [RFC2119].
This section is non-normative.
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 intelligently 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
Document
is not visible
at all on any screen.
prerender
Document
is loaded in the prerender mode and is not yet
visible.
visible
Document
is at least partially visible on at least one
screen. This is the same condition under which the hidden
attribute is set to false
.
The visibility states are reflected in the API via the
VisibilityState
enum.
enum VisibilityState {
"hidden", "visible", "prerender"
};
Document
interface
This specification extends the Document
interface:
partial interface Document
{
readonly attribute VisibilityState
visibilityState
;
attribute EventHandler onvisibilitychange
;
};
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
".
visible
", return
"prerender
".
visible
" if:
hidden
" if:
When possible, if the user agent is fully obscured by another
application, the visibilityState
attribute SHOULD return
"hidden
", except if a view of the doc is displayed in an accessibility tool.
onvisibilitychange
event handler attribute
onvisibilitychange
is an
event handler IDL attribute for the visibilitychange
event
type.
visibilitychange
changes
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:
Document
of the top level
browsing context.
visible
:
visible
, or if the user
agent is to unload doc:
Document
, run
the now hidden algorithm during the unloading document
visibility change steps.
The now visible algorithm runs the following steps synchronously:
Document
of the top level
browsing context.
visibilitychange
that
bubbles, isn't cancelable, and has no default action, at the
doc.
The now hidden algorithm runs the following steps synchronously:
Document
of the top level
browsing context.
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 [HTML] specification:
blur
defaultView
Document
focus
Window
The [DOM] 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.