JavaScript Document hidden Property

What You’ll Learn

Document.hidden is a read-only instance property that returns true when the page is not visible to the user (background tab, minimized window, etc.). Learn the Page Visibility API, MDN’s visibilitychange example, pausing media, and five examples with try-it labs.

Introduction

When a user switches tabs or minimizes the browser, your page may still run JavaScript—but it is no longer visible. document.hidden tells you that in one boolean value.

MDN: the read-only property returns whether the page is considered hidden. Use it to check whether the document is in the background, minimized, or otherwise not visible to the user. It is part of the Page Visibility API.

Related Document tutorials: head, body, activeElement, Document constructor.

Understanding Document.hidden

A read-only instance property on Document. Its value updates as the user changes tab or window visibility.

• Value — true if the page is hidden; false if visible (MDN).
• Event — listen for visibilitychange on document (MDN).
• Alternative — document.visibilityState returns "visible", "hidden", or "prerender" (MDN).
• Not settable — you observe visibility; scripts cannot assign a hidden state.
• Common pattern — if (document.hidden) pause(); else play();

📝 Syntax

document.hidden

Value

A boolean: true when the page is hidden, false when visible (MDN).

MDN example

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

⚖️ Page Visibility API

Examples Gallery

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

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

false
visible? true

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

false
true
false

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

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    video.pause();
  } else {
    video.play().catch(() => {});
  }
});

Video pauses when tab hidden; plays when visible

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

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

{ hidden: false, state: "visible" }

let timerId = setInterval(() => console.log("poll"), 2000);

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    clearInterval(timerId);
    timerId = null;
    console.log("polling stopped");
  } else if (!timerId) {
    timerId = setInterval(() => console.log("poll"), 2000);
    console.log("polling resumed");
  }
});

poll
polling stopped
polling resumed

🚀 Common Use Cases

• Video / audio — pause when the tab is hidden.
• Animations — pause requestAnimationFrame loops in background.
• Analytics — measure time-on-page only while visible.
• Live data — 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.
• Part of the Page Visibility API with visibilityState and visibilitychange.
• Read-only — you cannot assign to document.hidden.
• Not identical to document.hasFocus() (window focus vs page visibility).
• Related: head, body, ownerDocument, Document constructor.

💡 Best Practices