docs.rodeo

MDN Web Docs mirror

Page Visibility API

{{DefaultAPISidebar("Page Visibility API")}} 

The Page Visibility API provides events you can watch for to know when a document becomes visible or hidden, as well as features to look at the current visibility state of the page.

This is especially useful for saving resources and improving performance by letting a page avoid performing unnecessary tasks when the document isn’t visible.

Concepts and usage

When the user minimizes the window, switches to another tab, or the document is entirely obscured by another window, the API sends a {{domxref("document.visibilitychange_event", "visibilitychange")}}  event to let listeners know the state of the page has changed. You can detect the event and perform some actions or behave differently. For example, if your web app is playing a video, it can pause the video when the user puts the tab into the background, and resume playback when the user returns to the tab. The user doesn’t lose their place in the video, the video’s soundtrack doesn’t interfere with audio in the new foreground tab, and the user doesn’t miss any of the video in the meantime.

Visibility states of an {{HTMLElement("iframe")}}  are the same as the parent document. Hiding an <iframe> using CSS properties (such as {{cssxref("display", "display: none;")}} ) doesn’t trigger visibility events or change the state of the document contained within the frame.

Use cases

Let’s consider a few use cases for the Page Visibility API.

Developers have historically used imperfect proxies to detect this. For example, watching for {{domxref("Window/blur_event", "blur")}}  and {{domxref("Window/focus_event", "focus")}}  events on the window helps you know when your page is not the active page, but it does not tell you that your page is actually hidden to the user. The Page Visibility API addresses this.

[!NOTE] While {{domxref("Window.blur_event", "onblur")}}  and {{domxref("Window.focus_event", "onfocus")}}  will tell you if the user switches windows, it doesn’t necessarily mean it’s hidden. Pages only become hidden when the user switches tabs or minimizes the browser window containing the tab.

Policies in place to aid background page performance

Separately from the Page Visibility API, user agents typically have a number of policies in place to mitigate the performance impact of background or hidden tabs. These may include:

Some processes are exempt from this throttling behavior. In these cases, you can use the Page Visibility API to reduce the tabs’ performance impact while they’re hidden.

Extensions to other interfaces

Instance properties

The Page Visibility API adds the following properties to the {{domxref("Document")}}  interface:

Events

The Page Visibility API adds the following events to the {{domxref("Document")}}  interface:

Examples

Pausing audio on page hide

This example pauses playing audio when the page is hidden and resumes playing when the page becomes visible again. The <audio> element controls allow the user to toggle between playing and paused audio. The boolean playingOnHide is used to prevent audio from playing if the page changes to a visible state, but the media wasn’t playing on page hide.

audio {
  width: 100%;
}

HTML

<audio
  controls
  src="https://mdn.github.io/webaudio-examples/audio-basics/outfoxing.mp3"></audio>

JavaScript

const audio = document.querySelector("audio");

let playingOnHide = false;

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else {
    // Page became visible! Resume playing if audio was "playing on hide"
    if (playingOnHide) {
      audio.play();
    }
  }
});

Result

{{EmbedLiveSample("Pausing audio on page hide", "", 50)}} 

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

See also

In this article

View on MDN