Page Visibility Level 2

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. 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/.

This document replaces the first edition of Page Visibility, and includes:

Processing and IDL clarifications:
- VisibilityState enum value "unloaded" was removed.
- onvisibilitychange event handler was added.
- Various enhancements and clarifications in the processing model and algorithms.
Visibility state is set to hidden when the user agent is unloading a document;

This document was published by the Web Performance Working Group as a Candidate Recommendation Snapshot. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. A Candidate Recommendation Snapshot has received wide review and is intended to gather implementation experience.

This Candidate Recommendation is not expected to advance to Proposed Recommendation any earlier than 31 July 2021.

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 15 September 2020 W3C Process Document.

1. Introduction

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.

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:

Example 1: Visibility-aware video playback

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.

3. Visibility states

The document of the top-level browsing context can be in one of the following visibility states:

hidden

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.

Note

visible

The document is at least partially visible on at least one 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.

Let doc be the context's top-level browsing context's active document.
Assert: doc is a Document.
Return visible if:
- The user agent has assistive technologies attached to the doc.
- Any of the doc's viewport contents are visible to the user.
Otherwise, return hidden.

4. `VisibilityState` enum

WebIDLenum VisibilityState {
  "hidden", "visible"
};

The VisibilityState enum is used to represent the visibility states.

The "hidden" enum value represents the hidden visibility state.

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

5. Extensions to the `Document` interface

This specification extends the Document interface:

WebIDLpartial interface Document {
  readonly attribute boolean hidden;
  readonly attribute VisibilityState visibilityState;
  attribute EventHandler onvisibilitychange;
};

5.1 `hidden` attribute

On getting, the hidden attribute MUST:

Let state be the result of determine the visibility state of this's relevant global object's browsing context.
If state is visible, then return false. Return true otherwise.

5.2 `visibilityState` attribute

On getting, the visibilityState attribute the user agent MUST:

Let state be the result of determine the visibility state of this's relevant global object's browsing context.
If state is visible, return "visible". Otherwise, return "hidden".

5.3 `onvisibilitychange` event handler attribute

The onvisibilitychange attribute is an event handler IDL attribute for the "visibilitychange" event type (see § 6. Reacting to "visibilitychange" changes).

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:

Let doc be the Document of the top-level browsing context.
If doc is now visible:
1. If traversing to a session history entry, run the now visible algorithm before running the step to fire the pageshow event.
2. Otherwise, queue a task that runs the now visible algorithm.
Else if doc is now not visible, or if the user agent is to unload doc:
1. If the user agent is to unload the Document, run the now hidden algorithm during the unloading document visibility change steps.
2. Otherwise, queue a task that runs the now hidden algorithm.

The now visible algorithm runs the following steps synchronously:

Let doc be the Document of the top-level browsing context.
Fire an event named "visibilitychange" that bubbles, isn't cancelable, and has no default action, at the doc.
Run external now visible algorithm if one is defined by another specification.

The now hidden algorithm runs the following steps synchronously:

Let doc be the Document of the top-level browsing context.
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. Accessibility considerations

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.

A. Index

A.1 Terms defined by this specification

determine the visibility state §3.
external now hidden algorithm §6.
external now visible algorithm §6.
hidden
- definition of §3.
- enum value for VisibilityState §4.
- attribute for Document §5.1
now hidden algorithm §6.
now visible algorithm §6.
onvisibilitychange attribute for Document §5.3
visibility states §3.
visibilityState attribute for Document §5.2
visible
- definition of §3.
- enum value for VisibilityState §4.
VisibilityState enum §4.

A.2 Terms defined by reference

[DOM] defines the following:
- document
- Document interface
- Fire an event
[HTML] defines the following:
- active document
- blur (for Window)
- browsing context
- event handler IDL attribute
- EventHandler
- focus (for Window)
- pageshow (for Window)
- queue a task
- relevant global object
- session history entry
- task source
- tasks
- top-level browsing context
- unload (for Window)
- unloading document visibility change steps
- user interaction task source
- Window interface
[WEBIDL] defines the following:
- boolean type
- this

C. References

C.1 Normative references

[dom]: DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[webidl]: Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

Page Visibility Level 2

W3C Candidate Recommendation Snapshot 18 May 2021

Abstract

Status of This Document

1. Introduction

2. Examples of usage

3. Visibility states

4. `VisibilityState` enum

5. Extensions to the `Document` interface

5.1 `hidden` attribute

5.2 `visibilityState` attribute

5.3 `onvisibilitychange` event handler attribute

6. Reacting to `"visibilitychange"` changes

7. Privacy and Security

8. Accessibility considerations

9. Terminology

10. Conformance

A. Index

A.1 Terms defined by this specification

A.2 Terms defined by reference

B. Acknowledgments

C. References

C.1 Normative references

Page Visibility Level 2

W3C Candidate Recommendation Snapshot 18 May 2021

Abstract

Status of This Document

1. Introduction

2. Examples of usage

3. Visibility states

4. VisibilityState enum

5. Extensions to the Document interface

5.1 hidden attribute

5.2 visibilityState attribute

5.3 onvisibilitychange event handler attribute

6. Reacting to "visibilitychange" changes

7. Privacy and Security

8. Accessibility considerations

9. Terminology

10. Conformance

A. Index

A.1 Terms defined by this specification

A.2 Terms defined by reference

B. Acknowledgments

C. References

C.1 Normative references

4. `VisibilityState` enum

5. Extensions to the `Document` interface

5.1 `hidden` attribute

5.2 `visibilityState` attribute

5.3 `onvisibilitychange` event handler attribute

6. Reacting to `"visibilitychange"` changes