VisibilityStateEntry

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

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:

js

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 ocurred before the first contentful paint:

js

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

Specification
HTML Standard
# the-visibilitystateentry-interface

Browser compatibility

BCD tables only load in the browser

See also