The Page Visibility API: Improve User Experience and Performance

I am always excited to share insights about lesser-known yet powerful APIs in the modern web ecosystem.

Today, we'll dive into the Page Visibility API. This invaluable tool helps developers optimize their web applications by detecting when users are actively viewing or interacting with a page.

Laptop on top of a purple background with the text "JavaScript"

What is the Page Visibility API?

The Page Visibility API allows developers to determine whether a web page is visible to users, partially visible, or hidden.

Getting Started with the Page Visibility API

Let's explore the two main components of the Page Visibility API: the document.hidden property and the visibilitychange event.

document.hidden property

The document.hidden property is a boolean value that indicates whether the page is currently hidden or visible. If the page is hidden, the property returns true; if visible, it returns false. Example:

if (document.hidden) {
  console.log("The page is hidden");
} else {
  console.log("The page is visible");

visibilitychange event

The visibilitychange event is fired when the visibility state of the document changes. Adding an event listener to the visibilitychange event allows you to execute specific functions or actions when the visibility state changes.


document.addEventListener("visibilitychange", function() {
  if (document.hidden) {
    console.log("The page is hidden");
  } else {
    console.log("The page is visible");

A Practical Example

Here's an example of a video that auto-plays and pauses if you change tabs from this article.

Check out the timer and watch how it "magically" stops when you go to a different tab.

Dive into the CodePen to explore the code.

When to use the Page Visibility API

The Page Visibility API should be used when you need to optimize the performance, user experience, or resource usage of your web application based on its visibility status.

Here are some common use cases when you should consider using the Page Visibility API:

  • Media playback: If your web application plays videos or audio, you can use the Page Visibility API to pause playback when the user switches to another tab or minimizes the browser and resume playback when they return. This reduces bandwidth usage and avoids unnecessary consumption of the user's battery or system resources.

  • Animations: When a page contains resource-intensive animations, you can use the API to pause or reduce the quality of the animations when the page is not visible and resume or restore the rate when the user returns to the page.

  • Real-time data updates: If your application displays real-time data (e.g., stock prices, weather updates), you can use the Page Visibility API to adjust the polling frequency or temporarily stop fetching data when the user is not actively viewing the page. This reduces server load and network traffic, improving performance and saving resources.

  • Auto-saving drafts: In a text editor or content management system, you can use the Page Visibility API to trigger an auto-save when the user leaves the page or moves to a different tab, ensuring that the user's work is saved without manual intervention.

  • Web analytics: By tracking the visibility status of your pages, you can collect more accurate analytics data about user engagement and session duration. This helps you make better-informed decisions about your web application's design and performance.

Follow me on Twitter or connect on LinkedIn.

🚨 Want to make friends and learn from peers? You can join our free web developer community here. 🎉

JavaScriptWeb DevelopmentTutorialJS
Avatar for Niall Maher

Written by Niall Maher

Founder of Codú - The web developer community! I've worked in nearly every corner of technology businesses; Lead Developer, Software Architect, Product Manager, CTO and now happily a Founder.


Fetching comments

Hey! 👋

Got something to say?

or to leave a comment.