MDN self-hosted library · e01.org

VisibilityStateEntry

Performance API

Performance API

The VisibilityStateEntry interface provides timings of page visibility state changes, i.e., when a tab changes from the foreground to the background or vice versa.

This can be used to pinpoint visibility changes on the performance timeline, and cross-reference them against other performance entries such as "first-contentful-paint" (see PerformancePaintTiming).

There are two key visibility state change times that this API reports on:

  • visible: The time when the page becomes visible (i.e., when its tab moves into the foreground).
  • hidden: The time when the pages become hidden (i.e., when its tab moves into the background).

The performance timeline will always have a "visibility-state" entry with a startTime of 0 and a name representing the initial page visibility state.

[!NOTE] Like other Performance APIs, this API extends PerformanceEntry.

Instance properties

This interface has no properties but it extends the properties of PerformanceEntry by qualifying and constraining them as follows:

  • PerformanceEntry.entryType
  • : Returns "visibility-state".
  • PerformanceEntry.name
  • : Returns either "visible" or "hidden".
  • PerformanceEntry.startTime
  • : Returns the timestamp when the visibility state change occurred.
  • PerformanceEntry.duration
  • : Returns 0.

Instance methods

This interface has no methods.

Examples

Basic usage

The following function could be used to log a table of all "visibility-state" performance entries to the console:

function getVisibilityStateEntries() {
  const visibilityStateEntries =
    performance.getEntriesByType("visibility-state");
  console.table(visibilityStateEntries);
}

Correlating visibility state changes with paint timing

The below function gets a reference to all "visibility-state" entries and the "first-contentful-paint" entry, then uses Array.some() to test whether any of the "hidden" visibility entries occurred before the first contentful paint:

function wasHiddenBeforeFirstContentfulPaint() {
  const fcpEntry = performance.getEntriesByName("first-contentful-paint")[0];
  const visibilityStateEntries =
    performance.getEntriesByType("visibility-state");
  return visibilityStateEntries.some(
    (e) => e.startTime < fcpEntry.startTime && e.name === "hidden",
  );
}

Specifications

Browser compatibility

See also

Page Visibility API