JavaScript Document visibilityState Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word VISIBILITYSTATE

Definition

document.visibilityState is a read-only string from the Page Visibility API that tells you whether the document is "visible" or "hidden" (MDN). When it changes, the browser fires visibilitychange on document.

Read the notes below before you get or set this property. Prefer feature detection when support is limited.

Syntax

Use document.visibilityState. Start with this line.

JavaScript
document.visibilityState
CallWhat it does
document.visibilityStatePrimary signature.

Built into the browser. Read or assign document.visibilityState — no import required.

Library declarations
JavaScript
document.visibilityState

Parameters

ParameterDescription
Writable?Optional. Read-only
EventOptional. visibilitychange on change

Return Value

Return ValueDescription
*"visible" or "hidden"

JavaScript Examples

Example 1 — Read visibilityState

Log the current Page Visibility string on the active tab.

JavaScript
console.log(document.visibilityState);
// "visible" on an active foreground tab
Try It Yourself

How It Works

  1. Read the property. No arguments — it is not a method.
  2. Expect a string. MDN: "visible" or "hidden".
  3. On this tab while you view it, the value is usually "visible".
  4. Read-only. You observe state; you cannot assign a new value.

Example 2 — vs document.hidden

MDN: document.hidden is a boolean alternative for the same idea.

JavaScript
console.log("state:", document.visibilityState);
console.log("hidden:", document.hidden);
console.log("match?", document.hidden === (document.visibilityState === "hidden"));
Try It Yourself

How It Works

  1. Log the string. Exact Page Visibility value.
  2. Log the boolean. true only when the page is hidden.
  3. Compare them. hidden === (visibilityState === "hidden").
  4. Pick one API. String for clarity; boolean for short if checks.

Example 3 — Listen for visibilitychange

MDN pattern: log the new state whenever the tab visibility changes.

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

How It Works

  1. Attach the listener on document for visibilitychange.
  2. Read the property inside the handler — it already reflects the new state.
  3. Branch on the string to pause or resume work (MDN use cases).
  4. Switch tabs in Try It Yourself to see live updates.
Compatibility

Browser Support

Document.visibilityState is marked Baseline Widely available on MDN (since July 2015). Logos use the shared browser-image-sprite.png sprite from this project.

✓ Baseline · Widely available

Document.visibilityState

Read-only Page Visibility string — visible or hidden — with visibilitychange on change.

Widely Available
Google Chrome Full support · Desktop & Mobile
Full support
Mozilla Firefox Full support · Desktop & Mobile
Full support
Apple Safari Full support · macOS & iOS
Full support
Microsoft Edge Full support · Chromium
Full support
Opera Full support · Modern versions
Full support
Internet Explorer IE 10+ with prefixes historically
Partial support
Document.visibilityState Baseline support

Bottom line: Use document.visibilityState (or document.hidden) to detect background tabs and pause work. See the MDN Document.visibilityState reference.

Frequently Asked Questions

A read-only string describing document visibility. MDN documents two values: visible (page may be at least partially visible) and hidden (page content is not visible to the user).
No. MDN marks Document.visibilityState as Baseline Widely available (since July 2015). It is part of the standard Page Visibility API.
document.hidden is a boolean shortcut. document.visibilityState returns the exact string state. MDN notes hidden as an alternative way to determine whether the page is hidden.
MDN: when the document is a background tab, part of a minimized window, or the OS screen lock is active — the page content is not visible to the user.
The visibilitychange event on document. Read document.visibilityState inside the handler to react (MDN example).
No. It is read-only. You observe visibility; you cannot force the page hidden from script.

Next: Document vlinkColor

Learn the legacy visited-link color property (and modern CSS alternative).

vlinkColor tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document URL Property JavaScript Document vlinkColor Property