web-vitals

• Overview
• Install and load the library
• From npm
• From a CDN
• Usage
• Basic usage
• Report the value on every change
• Report only the delta of changes
• Send the results to an analytics endpoint
• Send the results to Google Analytics
• Send the results to Google Tag Manager
• Send attribution data
• Batch multiple reports together
• Build options
• Which build is right for you?
• API
• Types
• Functions
• Rating Thresholds
• Attribution
• Browser Support
• Limitations
• Development
• Integrations
• License

Overview

The web-vitals library is a tiny (~2K, 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.

Core Web Vitals

• Cumulative Layout Shift (CLS)
• Interaction to Next Paint (INP)
• Largest Contentful Paint (LCP)

Other metrics

• First Contentful Paint (FCP)
• Time to First Byte (TTFB)

Install and load the library

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.

From npm

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, onINP, onCLS} from 'web-vitals';

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 1.5K, 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, onINP, onCLS} from 'web-vitals';
import {onLCP, onINP, 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 objects 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.

From a CDN

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. It is also possible to load this from jsDelivr, and cdnjs.

Important! The unpkg.com, jsDelivr, and cdnjs CDNs are shown here for example purposes only. unpkg.com, jsDelivr, and cdnjs are not affiliated with Google, and there are no guarantees that loading the library from those CDNs will continue to work in the future. Self-hosting the built files rather than loading from the CDN is better for security, reliability, and performance reasons.

Load the "standard" build (using a module script)

<script type="module">
  import {onCLS, onINP, onLCP} from 'https://unpkg.com/web-vitals@5?module';

  onCLS(console.log);
  onINP(console.log);
  onLCP(console.log);
</script>

Note: When the web-vitals code is isolated from the application code in this way, there is less need to depend on dynamic imports so this code uses a regular import line.

Load the "standard" build (using a classic script)

<script>
  (function () {
    var script = document.createElement('script');
    script.src = 'https://unpkg.com/web-vitals@5/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.onINP(console.log);
      webVitals.onLCP(console.log);
    };
    document.head.appendChild(script);
  })();
</script>

Load the "attribution" build (using a module script)

<script type="module">
  import {
    onCLS,
    onINP,
    onLCP,
  } from 'https://unpkg.com/web-vitals@5/dist/web-vitals.attribution.js?module';

  onCLS(console.log);
  onINP(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@5/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.onINP(console.log);
      webVitals.onLCP(console.log);
    };
    document.head.appendChild(script);
  })();
</script>

Usage

Basic usage

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, onINP, onLCP} from 'web-vitals';

onCLS(console.log);
onINP(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:

• INP is not reported if the user never interacts with the page.
• CLS, FCP, and LCP are not reported if the page was loaded in the background.

In other cases, a metric callback may be called more than once:

• CLS and INP should be reported any time the page's visibilityState changes to hidden.
• All metrics are reported again (with the above exceptions) after a page is restored from the back/forward cache.

[!WARNING] Do not call any of the Web Vitals functions (e.g. onCLS(), onINP(), 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.

Report the value on every change

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});

Report only the delta of changes

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, onINP, onLCP} from 'web-vitals';

function logDelta({name, id, delta}) {
  console.log(`${name} matching ID ${id} changed by ${delta}`);
}

onCLS(logDelta);
onINP(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).

Send the results to an analytics endpoint

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, which is widely available across browsers, and supports sending data as the page is being unloaded.

import {onCLS, onINP, onLCP} from 'web-vitals';

function sendToAnalytics(metric) {
  const body = JSON.stringify({
    name: metric.name,
    value: metric.value,
    id: metric.id,

    // Include additional data as needed...
  });

  // Use `navigator.sendBeacon()` to send the data, which supports
  // sending while the page is unloading.
  navigator.sendBeacon('/analytics', body);
}

onCLS(sendToAnalytics);
onINP(sendToAnalytics);
onLCP(sendToAnalytics);

Send the results to Google Analytics

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](http