Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Document visibility: `Document.hidden` and `visibilitychange`

Read the document’s current visibility with `document.hidden` and use `visibilitychange` to respond to changes without polling.

Version: Current web platform; runtime support varies

Syntax

document.hidden
 document.visibilityState
 document.addEventListener("visibilitychange", listener)
 document.removeEventListener("visibilitychange", listener)

Document.hidden/visibilitychange pairs a state property with a change notification. document.hidden is a read-only Boolean: it is true when document.visibilityState is "hidden" and false when it is "visible". A background tab or a minimized window is a common reason for a document to be hidden. This state does not tell you whether the page has focus, whether a particular element is visible, or whether someone is looking at the page.

The browser fires visibilitychange at document after the state changes in either direction. It is a plain Event that bubbles and cannot be canceled. It does not carry the new state, so read the property inside the listener. Registering a listener does not call it immediately; read the initial state separately. To stop listening, pass the same function to removeEventListener.

For example, pause unnecessary UI updates while the document is hidden and resume them when it is visible again. A transition to "hidden" does not mean the page has closed, and you should not count on the browser giving your code time to finish work. This is a Web Platform API, not part of ECMAScript. Availability depends on the runtime.

Examples

const stopVisibilityLog = (() => {
  const hasDocument = typeof document !== "undefined";
  const page = hasDocument ? document : new EventTarget();
  let simulatedHidden = false;

  if (!hasDocument) {
    // Node.js fixture: simulate visibility without a browser document.
    Object.defineProperty(page, "hidden", { get: () => simulatedHidden });
  }

  const logVisibility = () => {
    console.log(page.hidden ? "hidden" : "visible");
  };

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

  const stop = () => {
    page.removeEventListener("visibilitychange", logVisibility);
  };

  if (!hasDocument) {
    const changeVisibility = (hidden) => {
      simulatedHidden = hidden;
      page.dispatchEvent(new Event("visibilitychange", { bubbles: true }));
    };

    changeVisibility(true);
    changeVisibility(false);
    stop();
    changeVisibility(true); // No log after removing the listener.
  }

  return stop;
})();

Result

visible
hidden
visible

Run the code once in the browser console for a visible page. Switch to another tab, then return. The shown output assumes exactly those two changes after the initial reading. Call `stopVisibilityLog()` to stop logging. In Node.js, the example simulates visibility changes instead of using a browser document.

Related lessons

  • JavaScript · Lesson 27 · Intermediate · Version: 3
  • JavaScript · Lesson 29 · Intermediate · Version: 3
  • JavaScript · Lesson 31 · Intermediate · Version: 3

Sources