web-vitals
Advanced tools
The web-vitals npm package is a library that provides a set of functions to measure the web vitals, which are metrics that Google considers important for a website's user experience. These metrics include Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS), among others. The package helps developers capture and report on these metrics to improve the performance of their web applications.
Measure Largest Contentful Paint (LCP)
This feature allows you to measure the Largest Contentful Paint (LCP), which reports the render time of the largest image or text block visible within the viewport. The code sample demonstrates how to import the getLCP function from the web-vitals package and use it to log the LCP metric to the console.
import { getLCP } from 'web-vitals';
getLCP(console.log);Measure First Input Delay (FID)
This feature measures the First Input Delay (FID), which captures the time from when a user first interacts with your site to the time when the browser is actually able to respond to that interaction. The code sample shows how to use the getFID function to log the FID metric.
import { getFID } from 'web-vitals';
getFID(console.log);Measure Cumulative Layout Shift (CLS)
This feature measures the Cumulative Layout Shift (CLS), which quantifies how often users experience unexpected layout shifts. The code sample illustrates how to use the getCLS function to log the CLS metric.
import { getCLS } from 'web-vitals';
getCLS(console.log);Lighthouse is an open-source, automated tool for improving the quality of web pages. It has audits for performance, accessibility, progressive web apps, and more. While web-vitals focuses specifically on performance metrics, Lighthouse provides a broader range of checks and can be used for comprehensive reporting and auditing.
PageSpeed Insights is a tool that incorporates the Lighthouse performance metrics and provides insights on how to improve web page speed. It is similar to web-vitals in that it measures core web vitals, but it also offers suggestions for optimizations and can be used for both mobile and desktop performance analysis.
Perfume.js is a JavaScript library for web performance monitoring that includes Google's web vitals. It offers additional features like analytics integration, custom metrics, and automatic vitals tracking. Compared to web-vitals, Perfume.js provides a more extensive set of tools for performance monitoring and analytics.
web-vitalsThe web-vitals library is a tiny (~1.5K, brotli'd), modular library for measuring all the Web Vitals metrics on real users, in a way that accurately matches how they're measured by Chrome and reported to other Google tools (e.g. Chrome User Experience Report, Page Speed Insights, Search Console's Speed Report).
The library supports all of the Core Web Vitals as well as a number of other metrics that are useful in diagnosing real-user performance issues.
The web-vitals library uses the buffered flag for PerformanceObserver, allowing it to access performance entries that occurred before the library was loaded.
This means you do not need to load this library early in order to get accurate performance data. In general, this library should be deferred until after other user-impacting code has loaded.
You can install this library from npm by running:
npm install web-vitals
Note: If you're not using npm, you can still load web-vitals via <script> tags from a CDN like unpkg.com. See the load web-vitals from a CDN usage example below for details.
There are a few different builds of the web-vitals library, and how you load the library depends on which build you want to use.
For details on the difference between the builds, see which build is right for you.
1. The "standard" build
To load the "standard" build, import modules from the web-vitals package in your application code (as you would with any npm package and node-based build tool):
import {onLCP, onFID, onCLS} from 'web-vitals';
onCLS(console.log);
onFID(console.log);
onLCP(console.log);
Note: in version 2, these functions were named getXXX() rather than onXXX(). They've been renamed in version 3 to reduce confusion (see #217 for details) and will continue to be available using the getXXX() until at least version 4. Users are encouraged to switch to the new names, though, for future compatibility.
2. The "attribution" build
Measuring the Web Vitals scores for your real users is a great first step toward optimizing the user experience. But if your scores aren't good, the next step is to understand why they're not good and work to improve them.
The "attribution" build helps you do that by including additional diagnostic information with each metric to help you identify the root cause of poor performance as well as prioritize the most important things to fix.
The "attribution" build is slightly larger than the "standard" build (by about 600 bytes, brotli'd), so while the code size is still small, it's only recommended if you're actually using these features.
To load the "attribution" build, change any import statements that reference web-vitals to web-vitals/attribution:
- import {onLCP, onFID, onCLS} from 'web-vitals';
+ import {onLCP, onFID, onCLS} from 'web-vitals/attribution';
Usage for each of the imported function is identical to the standard build, but when importing from the attribution build, the Metric object will contain an additional attribution property.
See Send attribution data for usage examples, and the attribution reference for details on what values are added for each metric.
3. The "base+polyfill" build
⚠️ Warning ⚠️ the "base+polyfill" build is deprecated. See #238 for details.
Loading the "base+polyfill" build is a two-step process:
First, in your application code, import the "base" build rather than the "standard" build. To do this, change any import statements that reference web-vitals to web-vitals/base:
- import {onLCP, onFID, onCLS} from 'web-vitals';
+ import {onLCP, onFID, onCLS} from 'web-vitals/base';
Then, inline the code from dist/polyfill.js into the <head> of your pages. This step is important since the "base" build will error if the polyfill code has not been added.
<!doctype html>
<html>
<head>
<script>
// Inline code from `dist/polyfill.js` here
</script>
</head>
<body>
...
</body>
</html>
It's important that the code is inlined directly into the HTML. Do not link to an external script file, as that will negatively affect performance:
<!-- GOOD -->
<script>
// Inline code from `dist/polyfill.js` here
</script>
<!-- BAD! DO NOT DO! -->
<script src="/path/to/polyfill.js"></script>
Also note that the code must go in the <head> of your pages in order to work. See how the polyfill works for more details.
Tip: while it's certainly possible to inline the code in dist/polyfill.js by copy and pasting it directly into your templates, it's better to automate this process in a build step—otherwise you risk the "base" and the "polyfill" scripts getting out of sync when new versions are released.
The recommended way to use the web-vitals package is to install it from npm and integrate it into your build process. However, if you're not using npm, it's still possible to use web-vitals by requesting it from a CDN that serves npm package files.
The following examples show how to load web-vitals from unpkg.com:
Important! The unpkg.com CDN is shown here for example purposes only. unpkg.com is not affiliated with Google, and there are no guarantees that the URLs shown in these examples will continue to work in the future.
Load the "standard" build (using a module script)
<!-- Append the `?module` param to load the module version of `web-vitals` -->
<script type="module">
import {onCLS, onFID, onLCP} from 'https://unpkg.com/web-vitals@3?module';
onCLS(console.log);
onFID(console.log);
onLCP(console.log);
</script>
Load the "standard" build (using a classic script)
<script>
(function () {
var script = document.createElement('script');
script.src = 'https://unpkg.com/web-vitals@3/dist/web-vitals.iife.js';
script.onload = function () {
// When loading `web-vitals` using a classic script, all the public
// methods can be found on the `webVitals` global namespace.
webVitals.onCLS(console.log);
webVitals.onFID(console.log);
webVitals.onLCP(console.log);
};
document.head.appendChild(script);
})();
</script>
Load the "attribution" build (using a module script)
<!-- Append the `?module` param to load the module version of `web-vitals` -->
<script type="module">
import {
onCLS,
onFID,
onLCP,
} from 'https://unpkg.com/web-vitals@3/dist/web-vitals.attribution.js?module';
onCLS(console.log);
onFID(console.log);
onLCP(console.log);
</script>
Load the "attribution" build (using a classic script)
<script>
(function () {
var script = document.createElement('script');
script.src =
'https://unpkg.com/web-vitals@3/dist/web-vitals.attribution.iife.js';
script.onload = function () {
// When loading `web-vitals` using a classic script, all the public
// methods can be found on the `webVitals` global namespace.
webVitals.onCLS(console.log);
webVitals.onFID(console.log);
webVitals.onLCP(console.log);
};
document.head.appendChild(script);
})();
</script>
Each of the Web Vitals metrics is exposed as a single function that takes a callback function that will be called any time the metric value is available and ready to be reported.
The following example measures each of the Core Web Vitals metrics and logs the result to the console once its value is ready to report.
(The examples below import the "standard" build, but they will work with the "attribution" build as well.)
import {onCLS, onFID, onLCP} from 'web-vitals';
onCLS(console.log);
onFID(console.log);
onLCP(console.log);
Note that some of these metrics will not report until the user has interacted with the page, switched tabs, or the page starts to unload. If you don't see the values logged to the console immediately, try reloading the page (with preserve log enabled) or switching tabs and then switching back.
Also, in some cases a metric callback may never be called:
In other cases, a metric callback may be called more than once:
visibilityState changes to hidden.Warning: do not call any of the Web Vitals functions (e.g. onCLS(), onFID(), onLCP()) more than once per page load. Each of these functions creates a PerformanceObserver instance and registers event listeners for the lifetime of the page. While the overhead of calling these functions once is negligible, calling them repeatedly on the same page may eventually result in a memory leak.
In most cases, you only want the callback function to be called when the metric is ready to be reported. However, it is possible to report every change (e.g. each larger layout shift as it happens) by setting reportAllChanges to true in the optional, configuration object (second parameter).
Important: reportAllChanges only reports when the metric changes, not for each input to the metric. For example, a new layout shift that does not increase the CLS metric will not be reported even with reportAllChanges set to true because the CLS metric has not changed. Similarly, for INP, each interaction is not reported even with reportAllChanges set to true—just when an interaction causes an increase to INP.
This can be useful when debugging, but in general using reportAllChanges is not needed (or recommended) for measuring these metrics in production.
import {onCLS} from 'web-vitals';
// Logs CLS as the value changes.
onCLS(console.log, {reportAllChanges: true});
Some analytics providers allow you to update the value of a metric, even after you've already sent it to their servers (overwriting the previously-sent value with the same id).
Other analytics providers, however, do not allow this, so instead of reporting the new value, you need to report only the delta (the difference between the current value and the last-reported value). You can then compute the total value by summing all metric deltas sent with the same ID.
The following example shows how to use the id and delta properties:
import {onCLS, onFID, onLCP} from 'web-vitals';
function logDelta({name, id, delta}) {
console.log(`${name} matching ID ${id} changed by ${delta}`);
}
onCLS(logDelta);
onFID(logDelta);
onLCP(logDelta);
Note: the first time the callback function is called, its value and delta properties will be the same.
In addition to using the id field to group multiple deltas for the same metric, it can also be used to differentiate different metrics reported on the same page. For example, after a back/forward cache restore, a new metric object is created with a new id (since back/forward cache restores are considered separate page visits).
Note: this is experimental and subject to change.
Currently Core Web Vitals are only tracked for full page navigations, which can affect how Single Page Applications that use so called "soft navigations" to update the browser URL and history outside of the normal browser's handling of this. The Chrome team are experimenting with being able to measure these soft navigations separately and report on Core Web Vitals separately for them.
This experimental support allows sites to measure how their Core Web Vitals might be measured differently should this happen.
At present a "soft navigation" is defined as happening after the following three things happen:
For some sites, these heuristics may lead to false positives (that users would not really consider a "navigation"), or false negatives (where the user does consider a navigation to have happened despite not missing the above criteria). We welcome feedback at https://github.com/WICG/soft-navigations/issues on the heuristics, at https://crbug.com for bugs in the Chrome implementation, and on [https://github.com/GoogleChrome/web-vitals/pull/308](this pull request) for implementation issues with web-vitals.js.
Note: At this time it is not known if this experiment will be something we want to move forward with. Until such time, this support will likely remain in a separate branch of this project, rather than be included in any production builds. If we decide not to move forward with this, the support of this will likely be removed from this project since this library is intended to mirror the Core Web Vitals as much as possible.
Some important points to note:
Note: It is not known at this time whether soft navigations will be weighted the same as full navigations. No weighting is included in this library at present and metrics are reported in the same way as full page load metrics.
The metrics can be reported for Soft Navigations using the reportSoftNavs: true reporting option:
import {
onCLS,
onFID,
onLCP,
} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';
onCLS(console.log, {reportSoftNavs: true});
onFID(console.log, {reportSoftNavs: true});
onLCP(console.log, {reportSoftNavs: true});
Note that this will change the way the first page loads are measured as the metrics for the inital URL will be finalized once the first soft nav occurs. To measure both you need to register two callbacks:
import {
onCLS,
onFID,
onLCP,
} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';
onCLS(doTraditionalProcessing);
onFID(doTraditionalProcessing);
onLCP(doTraditionalProcessing);
onCLS(doSoftNavProcessing, {reportSoftNavs: true});
onFID(doSoftNavProcessing, {reportSoftNavs: true});
onLCP(doSoftNavProcessing, {reportSoftNavs: true});
The following example measures each of the Core Web Vitals metrics and reports them to a hypothetical /analytics endpoint, as soon as each is ready to be sent.
The sendToAnalytics() function uses the navigator.sendBeacon() method (if available), but falls back to the fetch() API when not.
import {onCLS, onFID, onLCP} from 'web-vitals';
function sendToAnalytics(metric) {
// Replace with whatever serialization method you prefer.
// Note: JSON.stringify will likely include more data than you need.
const body = JSON.stringify(metric);
// Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
(navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
fetch('/analytics', {body, method: 'POST', keepalive: true});
}
onCLS(sendToAnalytics);
onFID(sendToAnalytics);
onLCP(sendToAnalytics);
Google Analytics does not support reporting metric distributions in any of its built-in reports; however, if you set a unique event parameter value (in this case, the metric_id, as shown in the example below) on every metric instance that you send to Google Analytics, you can create a report yourself by first getting the data via the Google Analytics Data API or via BigQuery export and then visualizing it any charting library you choose.
Google Analytics 4 introduces a new Event model allowing custom parameters instead of a fixed category, action, and label. It also supports non-integer values, making it easier to measure Web Vitals metrics compared to previous versions.
import {onCLS, onFID, onLCP} from 'web-vitals';
function sendToGoogleAnalytics({name, delta, value, id}) {
// Assumes the global `gtag()` function exists, see:
// https://developers.google.com/analytics/devguides/collection/ga4
gtag('event', name, {
// Built-in params:
value: delta, // Use `delta` so the value can be summed.
// Custom params:
metric_id: id, // Needed to aggregate events.
metric_value: value, // Optional.
metric_delta: delta, // Optional.
// OPTIONAL: any additional params or debug info here.
// See: https://web.dev/articles/debug-performance-in-the-field
// metric_rating: 'good' | 'needs-improvement' | 'poor',
// debug_info: '...',
// ...
});
}
onCLS(sendToGoogleAnalytics);
onFID(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
For details on how to query this data in BigQuery, or visualise it in Looker Studio, see Measure and debug performance with Google Analytics 4 and BigQuery.
The recommended way to measure Web Vitals metrics with Google Tag Manager is using the Core Web Vitals custom template tag created and maintained by Simo Ahava.
For full installation and usage instructions, see Simo's post: Track Core Web Vitals in GA4 with Google Tag Manager.
When using the attribution build, you can send additional data to help you debug why the metric values are they way they are.
This example sends an additional debug_target param to Google Analytics, corresponding to the element most associated with each metric.
import {onCLS, onFID, onLCP} from 'web-vitals/attribution';
function sendToGoogleAnalytics({name, delta, value, id, attribution}) {
const eventParams = {
// Built-in params:
value: delta, // Use `delta` so the value can be summed.
// Custom params:
metric_id: id, // Needed to aggregate events.
metric_value: value, // Optional.
metric_delta: delta, // Optional.
};
switch (name) {
case 'CLS':
eventParams.debug_target = attribution.largestShiftTarget;
break;
case 'FID':
eventParams.debug_target = attribution.eventTarget;
break;
case 'LCP':
eventParams.debug_target = attribution.element;
break;
}
// Assumes the global `gtag()` function exists, see:
// https://developers.google.com/analytics/devguides/collection/ga4
gtag('event', name, eventParams);
}
onCLS(sendToGoogleAnalytics);
onFID(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
Note: this example relies on custom event parameters in Google Analytics 4.
See Debug performance in the field for more information and examples.
Rather than reporting each individual Web Vitals metric separately, you can minimize your network usage by batching multiple metric reports together in a single network request.
However, since not all Web Vitals metrics become available at the same time, and since not all metrics are reported on every page, you cannot simply defer reporting until all metrics are available.
Instead, you should keep a queue of all metrics that were reported and flush the queue whenever the page is backgrounded or unloaded:
import {onCLS, onFID, onLCP} from 'web-vitals';
const queue = new Set();
function addToQueue(metric) {
queue.add(metric);
}
function flushQueue() {
if (queue.size > 0) {
// Replace with whatever serialization method you prefer.
// Note: JSON.stringify will likely include more data than you need.
const body = JSON.stringify([...queue]);
// Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
(navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
fetch('/analytics', {body, method: 'POST', keepalive: true});
queue.clear();
}
}
onCLS(addToQueue);
onFID(addToQueue);
onLCP(addToQueue);
// Report all available metrics whenever the page is backgrounded or unloaded.
addEventListener('visibilitychange', () => {
if (document.visibilityState === 'hidden') {
flushQueue();
}
});
// NOTE: Safari does not reliably fire the `visibilitychange` event when the
// page is being unloaded. If Safari support is needed, you should also flush
// the queue in the `pagehide` event.
addEventListener('pagehide', flushQueue);
Note: see the Page Lifecycle guide for an explanation of why visibilitychange and pagehide are recommended over events like beforeunload and unload.
The web-vitals package includes builds for the "standard", "attribution", and "base+polyfill" (deprecated) builds, as well as different formats of each to allow developers to choose the format that best meets their needs or integrates with their architecture.
The following table lists all the builds distributed with the web-vitals package on npm.
Filename (all within dist/*)
| Export | Description |
web-vitals.js | pkg.module |
An ES module bundle of all metric functions, without any attribution features. This is the "standard" build and is the simplest way to consume this library out of the box. |
web-vitals.umd.cjs | pkg.main |
A UMD version of the web-vitals.js bundle (exposed on the window.webVitals.* namespace).
|
web-vitals.iife.js | -- |
An IIFE version of the web-vitals.js bundle (exposed on the window.webVitals.* namespace).
|
web-vitals.attribution.js | -- | An ES module version of all metric functions that includes attribution features. |
web-vitals.attribution.umd.cjs | -- |
A UMD version of the web-vitals.attribution.js build (exposed on the window.webVitals.* namespace).
|
web-vitals.attribution.iife.js | -- |
An IIFE version of the web-vitals.attribution.js build (exposed on the window.webVitals.* namespace).
|
web-vitals.base.js | -- |
This build has been deprecated. An ES module bundle containing just the "base" part of the "base+polyfill" version. Use this bundle if (and only if) you've also added thepolyfill.js script to the <head> of your pages. See how to use the polyfill for more details.
|
web-vitals.base.umd.cjs | -- |
This build has been deprecated. A UMD version of the |
web-vitals.base.iife.js | -- |
This build has been deprecated. An IIFE version of the |
polyfill.js | -- |
This build has been deprecated. The "polyfill" part of the "base+polyfill" version. This script should be used with either |
Most developers will generally want to use "standard" build (via either the ES module or UMD version, depending on your bundler/build system), as it's the easiest to use out of the box and integrate into existing tools.
However, if you'd lke to collect additional debug information to help you diagnose performance bottlenecks based on real-user issues, use the "attribution" build.
For guidance on how to collect and use real-user data to debug performance issues, see Debug performance in the field.
⚠️ Warning ⚠️ the "base+polyfill" build is deprecated. See #238 for details.
The polyfill.js script adds event listeners (to track FID cross-browser), and it records initial page visibility state as well as the timestamp of the first visibility change to hidden (to improve the accuracy of CLS, FCP, LCP, and FID). It also polyfills the Navigation Timing API Level 2 in browsers that only support the original (now deprecated) Navigation Timing API.
In order for the polyfill to work properly, the script must be the first script added to the page, and it must run before the browser renders any content to the screen. This is why it needs to be added to the <head> of the document.
The "standard" build of the web-vitals library includes some of the same logic found in polyfill.js. To avoid duplicating that code when using the "base+polyfill" build, the web-vitals.base.js bundle does not include any polyfill logic, instead it coordinates with the code in polyfill.js, which is why the two scripts must be used together.
Metricinterface Metric {
/**
* The name of the metric (in acronym form).
*/
name: 'CLS' | 'FCP' | 'FID' | 'INP' | 'LCP' | 'TTFB';
/**
* The current value of the metric.
*/
value: number;
/**
* The rating as to whether the metric value is within the "good",
* "needs improvement", or "poor" thresholds of the metric.
*/
rating: 'good' | 'needs-improvement' | 'poor';
/**
* The delta between the current value and the last-reported value.
* On the first report, `delta` and `value` will always be the same.
*/
delta: number;
/**
* A unique ID representing this particular metric instance. This ID can
* be used by an analytics tool to dedupe multiple values sent for the same
* metric instance, or to group multiple deltas together and calculate a
* total. It can also be used to differentiate multiple different metric
* instances sent from the same page, which can happen if the page is
* restored from the back/forward cache (in that case new metrics object
* get created).
*/
id: string;
/**
* Any performance entries relevant to the metric value calculation.
* The array may also be empty if the metric value was not based on any
* entries (e.g. a CLS value of 0 given no layout shifts).
*/
entries: (
| PerformanceEntry
| LayoutShift
| FirstInputPolyfillEntry
| NavigationTimingPolyfillEntry
)[];
/**
* The type of navigation.
*
* This will be the value returned by the Navigation Timing API (or
* `undefined` if the browser doesn't support that API), with the following
* exceptions:
* - 'back-forward-cache': for pages that are restored from the bfcache.
* - 'prerender': for pages that were prerendered.
* - 'restore': for pages that were discarded by the browser and then
* restored by the user.
*/
navigationType:
| 'navigate'
| 'reload'
| 'back-forward'
| 'back-forward-cache'
| 'prerender'
| 'restore'
| 'soft-navigation';
/**
* The navigatonId the metric happened for. This is particularly relevent for soft navigations where
* the metric may be reported for a previous URL.
*/
navigatonId: number;
}
Metric-specific subclasses:
MetricWithAttributionSee the attribution build section for details on how to use this feature.
interface MetricWithAttribution extends Metric {
/**
* An object containing potentially-helpful debugging information that
* can be sent along with the metric value for the current page visit in
* order to help identify issues happening to real-users in the field.
*/
attribution: {[key: string]: unknown};
}
Metric-specific subclasses:
CLSMetricWithAttributionFCPMetricWithAttributionFIDMetricWithAttributionINPMetricWithAttributionLCPMetricWithAttributionTTFBMetricWithAttributionMetricRatingThresholdsThe thresholds of metric's "good", "needs improvement", and "poor" ratings.
| Metric value | Rating |
|---|---|
| ≦ [0] | "good" |
| > [0] and ≦ [1] | "needs improvement" |
| > [1] | "poor" |
export type MetricRatingThresholds = [number, number];
See also Rating Thresholds.
ReportCallbackinterface ReportCallback {
(metric: Metric): void;
}
Metric-specific subclasses:
CLSReportCallbackFCPReportCallbackFIDReportCallbackINPReportCallbackLCPReportCallbackTTFBReportCallbackReportOptsinterface ReportOpts {
reportAllChanges?: boolean;
durationThreshold?: number;
reportSoftNavs?: boolean;
}
LoadStateThe LoadState type is used in several of the metric attribution objects.
/**
* The loading state of the document. Note: this value is similar to
* `document.readyState` but it subdivides the "interactive" state into the
* time before and after the DOMContentLoaded event fires.
*
* State descriptions:
* - `loading`: the initial document response has not yet been fully downloaded
* and parsed. This is equivalent to the corresponding `readyState` value.
* - `dom-interactive`: the document has been fully loaded and parsed, but
* scripts may not have yet finished loading and executing.
* - `dom-content-loaded`: the document is fully loaded and parsed, and all
* scripts (except `async` scripts) have loaded and finished executing.
* - `complete`: the document and all of its sub-resources have finished
* loading. This is equivalent to the corresponding `readyState` value.
*/
type LoadState =
| 'loading'
| 'dom-interactive'
| 'dom-content-loaded'
| 'complete';
FirstInputPolyfillEntryIf using the "base+polyfill" build (and if the browser doesn't natively support the Event Timing API), the metric.entries reported by onFID() will contain an object that polyfills the PerformanceEventTiming entry:
type FirstInputPolyfillEntry = Omit<
PerformanceEventTiming,
'processingEnd' | 'toJSON'
>;
FirstInputPolyfillCallbackinterface FirstInputPolyfillCallback {
(entry: FirstInputPolyfillEntry): void;
}
NavigationTimingPolyfillEntryIf using the "base+polyfill" build (and if the browser doesn't support the Navigation Timing API Level 2 interface), the metric.entries reported by onTTFB() will contain an object that polyfills the PerformanceNavigationTiming entry using timings from the legacy performance.timing interface:
type NavigationTimingPolyfillEntry = Omit<
PerformanceNavigationTiming,
| 'initiatorType'
| 'nextHopProtocol'
| 'redirectCount'
| 'transferSize'
| 'encodedBodySize'
| 'decodedBodySize'
| 'type'
> & {
type: PerformanceNavigationTiming['type'];
};
WebVitalsGlobalIf using the "base+polyfill" build, the polyfill.js script creates the global webVitals namespace matching the following interface:
interface WebVitalsGlobal {
firstInputPolyfill: (onFirstInput: FirstInputPolyfillCallback) => void;
resetFirstInputPolyfill: () => void;
firstHiddenTime: number;
}
onCLS()type onCLS = (callback: CLSReportCallback, opts?: ReportOpts) => void;
Calculates the CLS value for the current page and calls the callback function once the value is ready to be reported, along with all layout-shift performance entries that were used in the metric value calculation. The reported value is a double (corresponding to a layout shift score).
If the reportAllChanges configuration option is set to true, the callback function will be called as soon as the value is initially determined as well as any time the value changes throughout the page lifespan (Note not necessarily for every layout shift).
Important: CLS should be continually monitored for changes throughout the entire lifespan of a page—including if the user returns to the page after it's been hidden/backgrounded. However, since browsers often will not fire additional callbacks once the user has backgrounded a page, callback is always called when the page's visibility state changes to hidden. As a result, the callback function might be called multiple times during the same page load (see Reporting only the delta of changes for how to manage this).
onFCP()type onFCP = (callback: FCPReportCallback, opts?: ReportOpts) => void;
Calculates the FCP value for the current page and calls the callback function once the value is ready, along with the relevant paint performance entry used to determine the value. The reported value is a DOMHighResTimeStamp.
onFID()type onFID = (callback: FIDReportCallback, opts?: ReportOpts) => void;
Calculates the FID value for the current page and calls the callback function once the value is ready, along with the relevant first-input performance entry used to determine the value. The reported value is a DOMHighResTimeStamp.
Important: since FID is only reported after the user interacts with the page, it's possible that it will not be reported for some page loads.
onINP()type onINP = (callback: INPReportCallback, opts?: ReportOpts) => void;
Calculates the INP value for the current page and calls the callback function once the value is ready, along with the event performance entries reported for that interaction. The reported value is a DOMHighResTimeStamp.
A custom durationThreshold configuration option can optionally be passed to control what event-timing entries are considered for INP reporting. The default threshold is 40, which means INP scores of less than 40 are reported as 0. Note that this will not affect your 75th percentile INP value unless that value is also less than 40 (well below the recommended good threshold).
If the reportAllChanges configuration option is set to true, the callback function will be called as soon as the value is initially determined as well as any time the value changes throughout the page lifespan (Note not necessarily for every interaction).
Important: INP should be continually monitored for changes throughout the entire lifespan of a page—including if the user returns to the page after it's been hidden/backgrounded. However, since browsers often will not fire additional callbacks once the user has backgrounded a page, callback is always called when the page's visibility state changes to hidden. As a result, the callback function might be called multiple times during the same page load (see Reporting only the delta of changes for how to manage this).
onLCP()type onLCP = (callback: LCPReportCallback, opts?: ReportOpts) => void;
Calculates the LCP value for the current page and calls the callback function once the value is ready (along with the relevant largest-contentful-paint performance entry used to determine the value). The reported value is a DOMHighResTimeStamp.
If the reportAllChanges configuration option is set to true, the callback function will be called any time a new largest-contentful-paint performance entry is dispatched, or once the final value of the metric has been determined.
onTTFB()type onTTFB = (callback: TTFBReportCallback, opts?: ReportOpts) => void;
Calculates the TTFB value for the current page and calls the callback function once the page has loaded, along with the relevant navigation performance entry used to determine the value. The reported value is a DOMHighResTimeStamp.
Note, this function waits until after the page is loaded to call callback in order to ensure all properties of the navigation entry are populated. This is useful if you want to report on other metrics exposed by the Navigation Timing API.
For example, the TTFB metric starts from the page's time origin, which means it includes time spent on DNS lookup, connection negotiation, network latency, and server processing time.
import {onTTFB} from 'web-vitals';
onTTFB((metric) => {
// Calculate the request time by subtracting from TTFB
// everything that happened prior to the request starting.
const requestTime = metric.value - metric.entries[0].requestStart;
console.log('Request time:', requestTime);
});
Note: browsers that do not support navigation entries will fall back to
using performance.timing (with the timestamps converted from epoch time to DOMHighResTimeStamp). This ensures code referencing these values (like in the example above) will work the same in all browsers.
The thresholds of each metric's "good", "needs improvement", and "poor" ratings are available as MetricRatingThresholds.
Example:
import {CLSThresholds, FIDThresholds, LCPThresholds} from 'web-vitals';
console.log(CLSThresholds); // [ 0.1, 0.25 ]
console.log(FIDThresholds); // [ 100, 300 ]
console.log(LCPThresholds); // [ 2500, 4000 ]
Note: It's typically not necessary (or recommended) to manually calculate metric value ratings using these thresholds. Use the Metric['rating'] supplied by the ReportCallback functions instead.
The following objects contain potentially-helpful debugging information that can be sent along with the metric values for the current page visit in order to help identify issues happening to real-users in the field.
See the attribution build section for details on how to use this feature.
attribution:interface CLSAttribution {
/**
* A selector identifying the first element (in document order) that
* shifted when the single largest layout shift contributing to the page's
* CLS score occurred.
*/
largestShiftTarget?: string;
/**
* The time when the single largest layout shift contributing to the page's
* CLS score occurred.
*/
largestShiftTime?: DOMHighResTimeStamp;
/**
* The layout shift score of the single largest layout shift contributing to
* the page's CLS score.
*/
largestShiftValue?: number;
/**
* The `LayoutShiftEntry` representing the single largest layout shift
* contributing to the page's CLS score. (Useful when you need more than just
* `largestShiftTarget`, `largestShiftTime`, and `largestShiftValue`).
*/
largestShiftEntry?: LayoutShift;
/**
* The first element source (in document order) among the `sources` list
* of the `largestShiftEntry` object. (Also useful when you need more than
* just `largestShiftTarget`, `largestShiftTime`, and `largestShiftValue`).
*/
largestShiftSource?: LayoutShiftAttribution;
/**
* The loading state of the document at the time when the largest layout
* shift contribution to the page's CLS score occurred (see `LoadState`
* for details).
*/
loadState?: LoadState;
}
attribution:interface FCPAttribution {
/**
* The time from when the user initiates loading the page until when the
* browser receives the first byte of the response (a.k.a. TTFB).
*/
timeToFirstByte: number;
/**
* The delta between TTFB and the first contentful paint (FCP).
*/
firstByteToFCP: number;
/**
* The loading state of the document at the time when FCP `occurred (see
* `LoadState` for details). Ideally, documents can paint before they finish
* loading (e.g. the `loading` or `dom-interactive` phases).
*/
loadState: LoadState;
/**
* The `PerformancePaintTiming` entry corresponding to FCP.
*/
fcpEntry?: PerformancePaintTiming;
/**
* The `navigation` entry of the current page, which is useful for diagnosing
* general page load issues. This can be used to access `serverTiming` for example:
* navigationEntry.serverTiming
*/
navigationEntry?: PerformanceNavigationTiming | NavigationTimingPolyfillEntry;
}
attribution:interface FIDAttribution {
/**
* A selector identifying the element that the user interacted with. This
* element will be the `target` of the `event` dispatched.
*/
eventTarget: string;
/**
* The time when the user interacted. This time will match the `timeStamp`
* value of the `event` dispatched.
*/
eventTime: number;
/**
* The `type` of the `event` dispatched from the user interaction.
*/
eventType: string;
/**
* The `PerformanceEventTiming` entry corresponding to FID (or the
* polyfill entry in browsers that don't support Event Timing).
*/
eventEntry: PerformanceEventTiming | FirstInputPolyfillEntry;
/**
* The loading state of the document at the time when the first interaction
* occurred (see `LoadState` for details). If the first interaction occurred
* while the document was loading and executing script (e.g. usually in the
* `dom-interactive` phase) it can result in long input delays.
*/
loadState: LoadState;
}
attribution:interface INPAttribution {
/**
* A selector identifying the element that the user interacted with for
* the event corresponding to INP. This element will be the `target` of the
* `event` dispatched.
*/
eventTarget?: string;
/**
* The time when the user interacted for the event corresponding to INP.
* This time will match the `timeStamp` value of the `event` dispatched.
*/
eventTime?: number;
/**
* The `type` of the `event` dispatched corresponding to INP.
*/
eventType?: string;
/**
* The `PerformanceEventTiming` entry corresponding to INP.
*/
eventEntry?: PerformanceEventTiming;
/**
* The loading state of the document at the time when the even corresponding
* to INP occurred (see `LoadState` for details). If the interaction occurred
* while the document was loading and executing script (e.g. usually in the
* `dom-interactive` phase) it can result in long delays.
*/
loadState?: LoadState;
}
attribution:interface LCPAttribution {
/**
* The element corresponding to the largest contentful paint for the page.
*/
element?: string;
/**
* The URL (if applicable) of the LCP image resource. If the LCP element
* is a text node, this value will not be set.
*/
url?: string;
/**
* The time from when the user initiates loading the page until when the
* browser receives the first byte of the response (a.k.a. TTFB). See
* [Optimize LCP](https://web.dev/articles/optimize-lcp) for details.
*/
timeToFirstByte: number;
/**
* The delta between TTFB and when the browser starts loading the LCP
* resource (if there is one, otherwise 0). See [Optimize
* LCP](https://web.dev/articles/optimize-lcp) for details.
*/
resourceLoadDelay: number;
/**
* The total time it takes to load the LCP resource itself (if there is one,
* otherwise 0). See [Optimize LCP](https://web.dev/articles/optimize-lcp) for
* details.
*/
resourceLoadTime: number;
/**
* The delta between when the LCP resource finishes loading until the LCP
* element is fully rendered. See [Optimize
* LCP](https://web.dev/articles/optimize-lcp) for details.
*/
elementRenderDelay: number;
/**
* The `navigation` entry of the current page, which is useful for diagnosing
* general page load issues. This can be used to access `serverTiming` for example:
* navigationEntry.serverTiming
*/
navigationEntry?: PerformanceNavigationTiming | NavigationTimingPolyfillEntry;
/**
* The `resource` entry for the LCP resource (if applicable), which is useful
* for diagnosing resource load issues.
*/
lcpResourceEntry?: PerformanceResourceTiming;
/**
* The `LargestContentfulPaint` entry corresponding to LCP.
*/
lcpEntry?: LargestContentfulPaint;
}
attribution:interface TTFBAttribution {
/**
* The total time from when the user initiates loading the page to when the
* DNS lookup begins. This includes redirects, service worker startup, and
* HTTP cache lookup times.
*/
waitingTime: number;
/**
* The total time to resolve the DNS for the current request.
*/
dnsTime: number;
/**
* The total time to create the connection to the requested domain.
*/
connectionTime: number;
/**
* The time time from when the request was sent until the first byte of the
* response was received. This includes network time as well as server
* processing time.
*/
requestTime: number;
/**
* The `navigation` entry of the current page, which is useful for diagnosing
* general page load issues. This can be used to access `serverTiming` for example:
* navigationEntry.serverTiming
*/
navigationEntry?: PerformanceNavigationTiming | NavigationTimingPolyfillEntry;
}
The web-vitals code has been tested and will run without error in all major browsers as well as Internet Explorer back to version 9. However, some of the APIs required to capture these metrics are currently only available in Chromium-based browsers (e.g. Chrome, Edge, Opera, Samsung Internet).
Browser support for each function is as follows:
onCLS(): ChromiumonFCP(): Chromium, Firefox, Safari 14.1+onFID(): Chromium, Firefox (with polyfill: Safari, Internet Explorer)onINP(): ChromiumonLCP(): ChromiumonTTFB(): Chromium, Firefox, Safari 15+ (with polyfill: Safari 8+, Internet Explorer)The web-vitals library is primarily a wrapper around the Web APIs that measure the Web Vitals metrics, which means the limitations of those APIs will mostly apply to this library as well. More details on these limitations is available in this blog post.
The primary limitation of these APIs is they have no visibility into <iframe> content (not even same-origin iframes), which means pages that make use of iframes will likely see a difference between the data measured by this library and the data available in the Chrome User Experience Report (which does include iframe content).
For same-origin iframes, it's possible to use the web-vitals library to measure metrics, but it's tricky because it requires the developer to add the library to every frame and postMessage() the results to the parent frame for aggregation.
Note: given the lack of iframe support, the onCLS() function technically measures DCLS (Document Cumulative Layout Shift) rather than CLS, if the page includes iframes).
The web-vitals source code is written in TypeScript. To transpile the code and build the production bundles, run the following command.
npm run build
To build the code and watch for changes, run:
npm run watch
The web-vitals code is tested in real browsers using webdriver.io. Use the following command to run the tests:
npm test
To test any of the APIs manually, you can start the test server
npm run test:server
Then navigate to http://localhost:9090/test/<view>, where <view> is the basename of one the templates under /test/views/.
You'll likely want to combine this with npm run watch to ensure any changes you make are transpiled and rebuilt.
web-vitals-reporter: JavaScript library to batch callback functions and send data with a single request.FAQs
Easily measure performance metrics in JavaScript
The npm package web-vitals receives a total of 1,748,214 weekly downloads. As such, web-vitals popularity was classified as popular.
We found that web-vitals demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.