Abstract

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 section describes the status of this document at the time of its publication. A list of currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.

🚩
This document is retired andMUST NOT be used for further technical work.
See theHTML Living Standard Page Visibility section instead and raise issues in thewhatwg/html repository.

This document was published by theWeb Performance Working Group as a Discontinued Draft using theRecommendation track.

Publication as a Discontinued Draft does not imply endorsement byW3C 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 theW3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.

This document is governed by the2 November 2021W3C Process Document.

This section is non-normative.

ThePage Visibility API defines a means to programmatically determine thevisibility state of a top-level browsing context, and to be notified if thevisibility state changes. Without knowing thevisibility state of a page, web developers have been designing web pages as if they are alwaysvisible. This not only results in higher machine resource utilization, but it prevents web developers from making runtime decisions based on whether the web page isvisible to the user. Designing web pages with knowledge of the document'svisibility 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 arevisible to the user or not. For example, this API can be used to scale back work when the page is no longervisible.

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 isvisible, and automatically pause the playback when the application ishidden:

const videoElement =document.getElementById("videoElement");// Autoplay the video if application is visibleif (document.visibilityState ==="visible") {  videoElement.play();}// Handle page visibility change eventsfunctionvisibilityListener(){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 thevisibilityState attribute of theDocument 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.

Thedocument of thetop-level browsing context can be in one of the followingvisibility states:

hidden

Thedocument is notvisible at all on any screen, as determined by running the steps todetermine the visibility state of thedocument'srelevant global object'sbrowsing context.

Note

Examples of actions that can cause a document to behidden:

• A tab is made into a background tab.
• The user agent is minimized.
• The user agent is moved off of the screen.
• The operating system's lock screen covers the user agent.

visible

Thedocument is at least partially visible on at least one screen, as determined by running the steps todetermine the visibility state of thedocument'srelevant global object'sbrowsing context.

Thevisibility states are reflected in the API via theVisibilityState enum.

The steps todetermine the visibility state of abrowsing contextcontext are as follows. The steps return avisibility state.

1. Letdoc be thecontext'stop-level browsing context'sactive document.
2. Assert:doc is aDocument.
3. Returnvisible if:
   • The user agent has assistive technologies attached to thedoc.
   • Any of thedoc's viewport contents are visible to the user.
4. Otherwise, returnhidden.

WebIDLenumVisibilityState {"hidden","visible"};

TheVisibilityState enum is used to represent thevisibility states.

The "hidden" enum value represents thehiddenvisibility state.

Likewise, the "visible" enum value represents thevisiblevisibility state.

This specification extends theDocument interface:

WebIDLpartial interfaceDocument {  readonly attributebooleanhidden;  readonly attributeVisibilityStatevisibilityState;  attributeEventHandleronvisibilitychange;};

Thetask source for thesetasks is theuser interaction task source.

When the user agent determines that the visibility of theDocument of thetop-level browsing context has changed, the user agentMUST run the following steps:

1. Letdoc be theDocument of thetop-level browsing context.
2. Ifdoc is nowvisible:
   1. If traversing to asession history entry, run thenow visible algorithm before running the step to fire thepageshow event.
   2. Otherwise,queue a task that runs thenow visible algorithm.
3. Else ifdoc is now notvisible, or if the user agent is tounloaddoc:
   1. If the user agent is tounload theDocument, run thenow hidden algorithm during theunloading document visibility change steps.
   2. Otherwise,queue a task that runs thenow hidden algorithm.

Thenow visible algorithm runs the following steps synchronously:

1. Letdoc be theDocument of thetop-level browsing context.
2. Fire an event named "visibilitychange" that bubbles, isn't cancelable, and has no default action, at thedoc.
3. Runexternal now visible algorithm if one is defined by another specification.

Thenow hidden algorithm runs the following steps synchronously:

1. Letdoc be theDocument of thetop-level browsing context.
2. Fire an event named "visibilitychange" that bubbles, isn't cancelable, and has no default action, at thedoc.
3. Runexternal now hidden algorithm if one is defined by another specification.

ThePage Visibility API enables developers to know when aDocument is visible or in focus. Existing mechanisms, such as thefocus andblur events, when attached to theWindow object already provide a mechanism to detect when theDocument is the active document; theunload 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, thevisibilityState attributeMAY return "visible", instead of "hidden", 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:

• session history entry
• unloading document visibility change steps

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 wordsMAY,MUST, andMUST NOT in this document are to be interpreted as described inBCP 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.