JavaScript Document visibilityState Property

What You’ll Learn

Document.visibilityState is a read-only instance property that returns a string describing whether the page is "visible" or "hidden". Learn the Page Visibility API, MDN’s visibilitychange event, how it relates to document.hidden, and five examples with try-it labs.

Introduction

Users often leave a tab open but switch away. Your page may still run JavaScript in the background—burning battery, playing audio, or polling a server. The Page Visibility API lets scripts know when the document is actually visible.

MDN: the visibilityState read-only property returns the visibility of the document. It can be used to check whether the document is in the background or in a minimized window, or is otherwise not visible to the user. When the value changes, the visibilitychange event is sent to the Document.

Related Document tutorials: hidden, prerendering, readyState, Document constructor.

Understanding Document.visibilityState

A read-only string instance property from the Page Visibility API.

• "visible" — page may be at least partially visible (MDN).
• "hidden" — page content is not visible to the user (MDN).
• Event — visibilitychange fires when the value changes (MDN).
• Alternative — document.hidden boolean (MDN).
• Status — Baseline Widely available (since July 2015, MDN).

📝 Syntax

document.visibilityState

Value

A string with one of: "visible" or "hidden" (MDN).

MDN: listen for changes

document.addEventListener("visibilitychange", () => {
  console.log(document.visibilityState);
  // Modify behavior…
});

⚖️ Page Visibility APIs

Examples Gallery

Examples follow MDN Document: visibilityState. Switch tabs in the try-it editor to see the state change.

console.log(document.visibilityState);
console.log("visible?", document.visibilityState === "visible");

visible
visible? true

document.addEventListener("visibilitychange", () => {
  console.log(document.visibilityState);
  // Modify behavior…
});

visible
hidden
visible

function onVisibilityChange() {
  if (document.visibilityState === "hidden") {
    console.log("Page hidden — pause timers, media, polling");
  } else {
    console.log("Page visible — resume activity");
  }
}

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

Page visible — resume activity

function logVisibility() {
  console.log({
    state: document.visibilityState,
    hidden: document.hidden
  });
}

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

{ state: "visible", hidden: false }

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

function renderState() {
  badge.textContent = document.visibilityState;
  badge.dataset.state = document.visibilityState;
}

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

Badge shows "visible" or "hidden" as you switch tabs

🚀 Common Use Cases

• Media playback — pause video/audio when state is "hidden".
• Animations — pause requestAnimationFrame loops in background tabs.
• Analytics — measure engaged time only while "visible".
• Live dashboards — stop or slow polling when hidden.
• Games — pause gameplay when the user switches away.
• Autosave — flush drafts when visibility becomes "hidden".

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• MDN documents two values: visible and hidden.
• document.hidden is the boolean alternative (MDN).
• blur/focus on window are not a substitute for tab visibility.
• Related: hidden, prerendering, URL.

💡 Best Practices