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