JavaScript Document visibilitychange Event

What You’ll Learn

The Document visibilitychange event fires when the page’s visibility status changes—for example when the user switches tabs, minimizes the browser, or (on mobile) leaves the app. Learn to read document.visibilityState and document.hidden, and practice with five try-it labs.

Introduction

A page can be open but not what the user is looking at—another tab is focused, the window is minimized, or the phone switched to a different app. The Page Visibility API reports that with document.visibilityState and document.hidden.

Whenever that status changes, Document visibilitychange fires. The Event object itself does not include the new state; you read document.visibilityState (or document.hidden) inside the handler.

Understanding Document visibilitychange

A standard Document event that answers: “Did this page just become visible or hidden to the user?”

• Fires when the document’s visibility status changes (MDN).
• Triggers include switching tabs, navigating away, minimizing/closing the browser, or switching apps on mobile.
• Not cancelable.
• Event type — a generic Event.
• Handler — document.onvisibilitychange or addEventListener("visibilitychange", ...).
• Status — Baseline Widely available since April 2021 (MDN).

📝 Syntax

Use the event name with addEventListener, or set the handler property:

addEventListener("visibilitychange", (event) => { });

onvisibilitychange = (event) => { };

Event type

A generic Event. The event is not cancelable.

Read the visibility status

document.addEventListener("visibilitychange", () => {
  console.log(document.visibilityState); // "visible" or "hidden"
  console.log(document.hidden);          // true when hidden
});

visibilityState values (beginner view)

⚖️ visibilitychange vs unload / blur

Examples Gallery

Examples follow MDN Document: visibilitychange event. In try-it labs, switch away from the tab (or minimize) then come back to see hidden ↔ visible updates.

const log = document.getElementById("log");

document.addEventListener("visibilitychange", () => {
  log.textContent +=
    "visibilityState: " + document.visibilityState + "\n";
});

visibilityState: hidden
visibilityState: visible

const out = document.getElementById("out");

document.onvisibilitychange = () => {
  out.textContent =
    "Now: " + document.visibilityState +
    " (hidden=" + document.hidden + ")";
};

out.textContent =
  "Now: " + document.visibilityState +
  " (hidden=" + document.hidden + ")";

Now: visible (hidden=false)

const out = document.getElementById("out");
let ticks = 0;
let timer = null;

function start() {
  if (timer) return;
  timer = setInterval(() => {
    ticks += 1;
    out.textContent = "Ticks: " + ticks + " (" + document.visibilityState + ")";
  }, 500);
}

function stop() {
  clearInterval(timer);
  timer = null;
}

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    stop();
  } else {
    start();
  }
});

start();

Ticks increase while visible
Switch tab → timer pauses
Return → timer resumes

const out = document.getElementById("out");
const analyticsData = "session=demo&action=leave";

document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    // Real apps: navigator.sendBeacon("/log", analyticsData);
    out.textContent =
      "Would sendBeacon with: " + analyticsData +
      " at " + new Date().toLocaleTimeString();
  } else {
    out.textContent = "Visible again — session continuing";
  }
};

Would sendBeacon with: session=demo&action=leave at 9:05:12 AM

const badge = document.getElementById("badge");
const detail = document.getElementById("detail");

function render() {
  const state = document.visibilityState;
  badge.textContent = state.toUpperCase();
  badge.dataset.state = state;
  detail.textContent =
    "document.hidden = " + document.hidden +
    " · updated " + new Date().toLocaleTimeString();
}

document.addEventListener("visibilitychange", render);
render();

VISIBLE
document.hidden = false · updated 9:05:40 AM

🚀 Common Use Cases

• Pausing video, audio, or animations when the tab is hidden.
• Stopping polling / WebSocket chatter in the background.
• Sending analytics with sendBeacon on transition to hidden.
• Saving draft state before the user leaves the page.
• Resuming work only when visibilityState becomes visible again.

🔧 How It Works

📝 Notes

• Baseline Widely available (since April 2021)—no Deprecated / Experimental / Non-standard banner.
• The event is not cancelable; it does not carry the new state on the Event object.
• Read document.visibilityState or document.hidden in the handler.
• Prefer hidden + sendBeacon for end-of-session analytics over relying only on unload.
• Related learning: visibilityState, selectionchange, JavaScript hub.

💡 Best Practices

❓ Frequently Asked Questions