Copyright © 2022 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. 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/.
🚩
This document is retired and MUST NOT be used for further technical work.
See the
HTML Living Standard Page Visibility section
instead and raise issues in the whatwg/html repository.
This document was published by the Web Performance Working Group as a Discontinued Draft using the Recommendation track.
Publication as a Discontinued Draft does not imply endorsement by W3C and its Members.
Publication as a Discontinued Draft implies that this document is no longer intended to advance or to be maintained. It is inappropriate to cite this document as other than abandoned work.
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 2 November 2021 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 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.
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 :
const videoElement = document.getElementById("videoElement");
// Autoplay the video if application is visible
if (document.visibilityState === "visible") {
videoElement.play();
}
// Handle page visibility change events
function visibilityListener() {
switch(document.visibilityState) {
case "hidden":
videoElement.pause();
break;
case "visible":
videoElement.play();
break;
}
}
document.addEventListener("visibilitychange", visibilityListener);
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 document of the top-level browsing context can be in one of the following visibility states:
The document is not visible at all on any screen, as determined by running the steps to determine the visibility state of the document's relevant global object's browsing context.
The visibility states are reflected in the API via the
VisibilityState
enum.
The steps to determine the visibility state of a browsing context context are as follows. The steps return a visibility state.
WebIDLenum VisibilityState
{
"hidden
", "visible
"
};
The VisibilityState
enum is used to represent the
visibility states.
The "hidden
" enum value represents the
visibility state.
Likewise, the "visible
" enum value represents the
visible visibility state.
This specification extends the Document
interface:
WebIDLpartial interface Document {
readonly attribute VisibilityState
visibilityState
;
attribute EventHandler onvisibilitychange
;
};
On getting, the visibilityState
attribute the user agent
MUST:
visible
". Otherwise, return
" ".
The onvisibilitychange
attribute is an event handler
IDL attribute for the "visibilitychange"
event type (see
6.
Reacting to "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.
Document
, run
the 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.
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 " ",
when the user agent is not minimized but is fully obscured by other
applications.
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, MUST, and MUST NOT 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.
onvisibilitychange
attribute for Document
§5.3visibilityState
attribute for Document
§5.2VisibilityState
enum
§4.Document
interface
Window
)
EventHandler
Window
)
Window
)
Window
)
Window
interface
boolean
type
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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: