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.
Status of This Document
This is a
preview
Do not attempt to implement this version of the specification. Do not
reference this version as authoritative in any way.
Instead, see
https://w3c.github.io/page-visibility/ for the Editor's draft.
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:
GitHub Issues are preferred for
discussion of this specification.
Alternatively, you can send comments to our mailing list.
Please send them to
public-web-perf@w3.org
(archives).
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.
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 document'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.
2.
Examples of usage
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:
const videoElement = document.getElementById("videoElement");
// Autoplay the video if application is visibleif (document.visibilityState === "visible") {
videoElement.play();
}
// Handle page visibility change eventsfunctionhandleVisibilityChange() {
if (document.visibilityState === "hidden") {
videoElement.pause();
} else {
videoElement.play();
}
}
document.addEventListener('visibilitychange', handleVisibilityChange);
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.
The doc's viewport contents are not observable to the
user
Note
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.
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:
Fire an event named "visibilitychange" that bubbles, isn't
cancelable, and has no default action, at the doc.
Run external now hidden algorithm if one is defined by
another specification.
7.
Privacy and Security
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.
8.
Terminology
The following concepts and interfaces are defined in the [HTML]
specification:
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 MAY and MUST in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
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.