VisibilityStateEntry

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.

Instance properties

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

PerformanceEntry.entryType Experimental

Returns "visibility-state".

PerformanceEntry.name Experimental

Returns either "visible" or "hidden".

PerformanceEntry.startTime Experimental

Returns the timestamp when the visibility state change occurred.

PerformanceEntry.duration Experimental

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