web-vitals/README.md

Easily measure performance metrics in JavaScript

# `web-vitals`

- [Overview](#overview)
- [Install and load the library](#installation)
  - [From npm](#import-web-vitals-from-npm)
  - [From a CDN](#load-web-vitals-from-a-cdn)
- [Usage](#usage)
  - [Basic usage](#basic-usage)
  - [Report the value on every change](#report-the-value-on-every-change)
  - [Report only the delta of changes](#report-only-the-delta-of-changes)
  - [Send the results to an analytics endpoint](#send-the-results-to-an-analytics-endpoint)
  - [Send the results to Google Analytics](#send-the-results-to-google-analytics)
  - [Send the results to Google Tag Manager](#send-the-results-to-google-tag-manager)
  - [Send attribution data](#send-attribution-data)
  - [Batch multiple reports together](#batch-multiple-reports-together)
- [Build options](#build-options)
  - [Which build is right for you?](#which-build-is-right-for-you)
- [API](#api)
  - [Types](#types)
  - [Functions](#functions)
  - [Rating Thresholds](#rating-thresholds)
  - [Attribution](#attribution)
- [Browser Support](#browser-support)
- [Limitations](#limitations)
- [Development](#development)
- [Integrations](#integrations)
- [License](#license)

## Overview

The `web-vitals` library is a tiny (~3K, brotli'd), modular library for measuring all the [Web Vitals](https://web.dev/articles/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](https://developers.google.com/web/tools/chrome-user-experience-report), [Page Speed Insights](https://developers.google.com/speed/pagespeed/insights/), [Search Console's Speed Report](https://webmasters.googleblog.com/2019/11/search-console-speed-report.html)).

The library supports all of the [Core Web Vitals](https://web.dev/articles/vitals#core_web_vitals) as well as a number of other metrics that are useful in diagnosing [real-user](https://web.dev/articles/user-centric-performance-metrics) performance issues.

### Core Web Vitals

- [Cumulative Layout Shift (CLS)](https://web.dev/articles/cls)
- [Interaction to Next Paint (INP)](https://web.dev/articles/inp)
- [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp)

### Other metrics

- [First Contentful Paint (FCP)](https://web.dev/articles/fcp)
- [Time to First Byte (TTFB)](https://web.dev/articles/ttfb)

<a name="installation"></a>
<a name="load-the-library"></a>

## Install and load the library

<a name="import-web-vitals-from-npm"></a>

The `web-vitals` library uses the `buffered` flag for [PerformanceObserver](https://developer.mozilla.org/docs/Web/API/PerformanceObserver/observe), 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:

```sh
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](https://unpkg.com). See the [load `web-vitals` from a CDN](#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 <a href="#which-build-is-right-for-you">which build is right for you</a>.

**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):

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

<a name="attribution-build"></a>

**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`:

```diff
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](#metric) objects will contain an additional [`attribution`](#attribution) property.

See [Send attribution data](#send-attribution-data) for usage examples, and the [`attribution` reference](#attribution) for details on what values are added for each metric.

<a name="load-web-vitals-from-a-cdn"></a>

### 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](https://unpkg.com/browse/web-vitals/). It is also possible to load this from [jsDelivr](https://www.jsdelivr.com/package/npm/web-vitals), and [cdnjs](https://cdnjs.com/libraries/web-vitals).

_**Important!** The [unpkg.com](https://unpkg.com), [jsDelivr](https://www.jsdelivr.com/), and [cdnjs](https://cdnjs.com) 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)_

```html
<!-- Append the `?module` param to load the module version of `web-vitals` -->
<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)_

```html
<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)_

```html
<!-- Append the `?module` param to load the module version of `web-vitals` -->
<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)_

```html
<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.)_

```js
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](https://developer.chrome.com/docs/devtools/console/reference/#persist) 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](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden).
- All metrics are reported again (with the above exceptions) after a page is restored from the [back/forward cache](https://web.dev/articles/bfcache).

> [!WARNING]
> Avoid calling the Web Vitals functions (e.g. `onCLS()`, `onINP()`, `onLCP()`) repeatedly per page load without a good reason. 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 increased memory overhead.

### 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](#reportopts) (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.

```js
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:

```js
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).

### Report metrics for soft navigations

When originally launched, Core Web Vitals are only tracked for full page navigations, which can affect how [Single Page Applications](https://web.dev/vitals-spa-faq/) 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 have added a feature from Chrome 151 to enable [measuring these soft navigations](https://github.com/WICG/soft-navigations) and report on Core Web Vitals separately for them.

A "soft navigation" is tracked automatically when the following three things happen:

- A user interaction occurs
- The URL changes
- Something is painted to screen.

For some sites, this definition 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). However, by having the browser define the soft navigation, rather than depending on SPA frameworks to call an API when happens, allows for soft navigations to be measured for existing SPA applications and also provides a more consistent experience across frameworks.

Some important points to note:

- TTFB is reported as 0, and not the time of the first network call (if any) after the soft navigation.
- FCP and LCP are the first and largest contentful paints after the soft navigation. Elements that remain between soft navigations will not count since they are not repainted. This can lead to differences between measuring performance for a page from a soft navigation and a hard navigation.
- INP is reset to measure only interactions after the the soft navigation.
- CLS is reset to measure again separate to the first page.

The metrics can be reported for Soft Navigations using the `reportSoftNavs: true` reporting option:

```js
import {
  onCLS,
  onINP,
  onLCP,
} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';

onCLS(console.log, {reportSoftNavs: true});
onINP(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 initial URL will be finalized once the first soft nav occurs.

This will also lead to differences with browsers that support soft navigations (Chromium-based browsers on version 151+) and other browsers (that will not change reporting even with the `reportSoftNavs` flag).

To measure both you need to register two callbacks:

```js
import {
  onCLS,
  onINP,
  onLCP,
} from 'https://unpkg.com/web-vitals@soft-navs/dist/web-vitals.js?module';

onCLS(doTraditionalProcessing);
onINP(doTraditionalProcessing);
onLCP(doTraditionalProcessing);

onCLS(doSoftNavProcessing, {reportSoftNavs: true});
onINP(doSoftNavProcessing, {reportSoftNavs: true});
onLCP(doSoftNavProcessing, {reportSoftNavs: true});
```

In both cases the `navigationURL` property will provide the URL the metrics are for. This should be used rather than assuming the current URL is the page URL, since metrics may be reported after the fact.

### 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()`](https://developer.mozilla.org/docs/Web/API/Navigator/sendBeacon) method, which is widely available across browsers, and supports sending data as the page is being unloaded.

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

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

    // Override the page location for soft nav support
    page_location: navigationURL,

    // 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](https://developers.google.com/analytics/devguides/reporting/data/v1) or via [BigQuery export](https://support.google.com/analytics/answer/9358801) and then visualizing it any charting library you choose.

[Google Analytics 4](https://support.google.com/analytics/answer/10089681) 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.

```js
import {onCLS, onINP, 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.

    // Override the page location as metrics can be reported late for soft navs
    page_location: navigationURL,

    // 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);
onINP(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
```

For details on how to query this data in [BigQuery](https://cloud.google.com/bigquery), or visualise it in [Looker Studio](https://lookerstudio.google.com/), see [Measure and debug performance with Google Analytics 4 and BigQuery](https://web.dev/articles/vitals-ga4).

### Send the results to Google Tag Manager

While `web-vitals` can be called directly from Google Tag Manager, using a pre-defined custom template makes this considerably easier. Some recommended templates include:

- [Core Web Vitals](https://tagmanager.google.com/gallery/#/owners/gtm-templates-simo-ahava/templates/core-web-vitals) by [Simo Ahava](https://www.simoahava.com/). See [Track Core Web Vitals in GA4 with Google Tag Manager](https://www.simoahava.com/analytics/track-core-web-vitals-in-ga4-with-google-tag-manager/) for usage and installation instructions.
- [Web Vitals Template for Google Tag Manager](https://github.com/google-marketing-solutions/web-vitals-gtm-template) by The Google Marketing Solutions team. See the [README](https://github.com/google-marketing-solutions/web-vitals-gtm-template?tab=readme-ov-file#web-vitals-template-for-google-tag-manager) for usage and installation instructions.

### Send attribution data

When using the [attribution build](#attribution-build), you can send additional data to help you debug _why_ the metric values are the way they are.

This example sends an additional `debug_target` param to Google Analytics, corresponding to the element most associated with each metric.

```js
import {onCLS, onINP, 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.

    // Override the page location for soft nav support
    page_location: navigationURL,
  };

  switch (name) {
    case 'CLS':
      eventParams.debug_target = attribution.largestShiftTarget;
      break;
    case 'INP':
      eventParams.debug_target = attribution.interactionTarget;
      break;
    case 'LCP':
      eventParams.debug_target = attribution.target;
      break;
  }

  // Assumes the global `gtag()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/ga4
  gtag('event', name, eventParams);
}

onCLS(sendToGoogleAnalytics);
onINP(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
```

> [!NOTE]
> This example relies on custom [event parameters](https://support.google.com/analytics/answer/11396839) in Google Analytics 4.

See [Debug performance in the field](https://web.dev/articles/debug-performance-in-the-field) for more information and examples.

### Batch multiple reports together

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:

```js
import {onCLS, onINP, 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()` to send the data, which supports
    // sending while the page is unloading.
    navigator.sendBeacon('/analytics', body);

    queue.clear();
  }
}

onCLS(addToQueue);
onINP(addToQueue);
onLCP(addToQueue);

// Report all available metrics whenever the page is backgrounded or unloaded.
addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    flushQueue();
  }
});
```

> [!NOTE]
> See [the Page Lifecycle guide](https://developers.google.com/web/updates/2018/07/page-lifecycle-api#legacy-lifecycle-apis-to-avoid) for an explanation of why `visibilitychange` is recommended over events like `beforeunload` and `unload`.

<a name="bundle-versions"></a>

## Build options

The `web-vitals` package includes both "standard" and "attribution" 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.

<table>
  <tr>
    <td width="35%">
      <strong>Filename</strong> <em>(all within <code>dist/*</code>)</em>
    </td>
    <td><strong>Export</strong></td>
    <td><strong>Description</strong></td>
  </tr>
  <tr>
    <td><code>web-vitals.js</code></td>
    <td><code>pkg.module</code></td>
    <td>
      <p>An ES module bundle of all metric functions, without any attribution features.</p>
      This is the "standard" build and is the simplest way to consume this library out of the box.
    </td>
  </tr>
  <tr>
    <td><code>web-vitals.umd.cjs</code></td>
    <td><code>pkg.main</code></td>
    <td>
      A UMD version of the <code>web-vitals.js</code> bundle (exposed on the <code>self.webVitals.*</code> namespace).
    </td>
  </tr>
  <tr>
    <td><code>web-vitals.iife.js</code></td>
    <td>--</td>
    <td>
      An IIFE version of the <code>web-vitals.js</code> bundle (exposed on the <code>self.webVitals.*</code> namespace).
    </td>
  </tr>
  <tr>
    <td><code>web-vitals.attribution.js</code></td>
    <td>--</td>
    <td>
      An ES module version of all metric functions that includes <a href="#attribution-build">attribution</a> features.
    </td>
  </tr>
    <tr>
    <td><code>web-vitals.attribution.umd.cjs</code></td>
    <td>--</td>
    <td>
      A UMD version of the <code>web-vitals.attribution.js</code> build (exposed on the <code>self.webVitals.*</code> namespace).
    </td>
  </tr>
  </tr>
    <tr>
    <td><code>web-vitals.attribution.iife.js</code></td>
    <td>--</td>
    <td>
      An IIFE version of the <code>web-vitals.attribution.js</code> build (exposed on the <code>self.webVitals.*</code> namespace).
    </td>
  </tr>
</table>

<a name="which-build-is-right-for-you"></a>

### Which build is right for you?

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 like to collect additional debug information to help you diagnose performance bottlenecks based on real-user issues, use the ["attribution" build](#attribution-build).

For guidance on how to collect and use real-user data to debug performance issues, see [Debug performance in the field](https://web.dev/debug-performance-in-the-field/).

## API

### Types:

#### `Metric`

All metrics types inherit from the following base interface:

```ts
interface Metric {
  /**
   * The name of the metric (in acronym form).
   */
  name: 'CLS' | 'FCP' | '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[];

  /**
   * 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.
   * - 'back_forward' is renamed to 'back-forward' for consistency.
   * - 'prerender': for pages that were prerendered.
   * - 'restore': for pages that were discarded by the browser and then
   * restored by the user.
   * - 'soft-navigation': for soft navigations.
   */
  navigationType:
    | 'navigate'
    | 'reload'
    | 'back-forward'
    | 'back-forward-cache'
    | 'prerender'
    | 'restore'
    | 'soft-navigation';

  /**
   * The navigationId the metric happened for. This is particularly relevant for soft navigations where
   * the metric may be reported for a previous URL.
   */
  navigationId: number;

  /**
   * For metrics specific to a soft navigation, the interactionId of the
   * interaction that triggered that soft navigation.
   */
  navigationInteractionId?: number;

  /**
   * The navigation startTime the metric is based from. This is particularly
   * relevant for soft navigations where time origin is not 0.
   */
  navigationStartTime?: number;

  /**
   * The navigation URL the metric happened for. This is particularly relevant for soft navigations where
   * the metric may be reported for a previous URL.
   */
  navigationURL?: string;
}
```

Metric-specific subclasses:

##### `CLSMetric`

```ts
interface CLSMetric extends Metric {
  name: 'CLS';
  entries: LayoutShift[];
}
```

##### `FCPMetric`

```ts
interface FCPMetric extends Metric {
  name: 'FCP';
  entries: PerformancePaintTiming[];
}
```

##### `INPMetric`

```ts
interface INPMetric extends Metric {
  name: 'INP';
  entries: PerformanceEventTiming[];
}
```

##### `LCPMetric`

```ts
interface LCPMetric extends Metric {
  name: 'LCP';
  entries: LargestContentfulPaint[];
}
```

##### `TTFBMetric`

```ts
interface TTFBMetric extends Metric {
  name: 'TTFB';
  entries: (PerformanceNavigationTiming | PeformanceSoftNavigation)[];
}
```

#### `MetricRatingThresholds`

The thresholds of metric's "good", "needs improvement", and "poor" ratings.

- Metric values up to and including [0] are rated "good"
- Metric values up to and including [1] are rated "needs improvement"
- Metric values above [1] are "poor"

| Metric value    | Rating              |
| --------------- | ------------------- |
| ≦ [0]           | "good"              |
| > [0] and ≦ [1] | "needs improvement" |
| > [1]           | "poor"              |

```ts
type MetricRatingThresholds = [number, number];
```

_See also [Rating Thresholds](#rating-thresholds)._

#### `ReportOpts`

```ts
interface ReportOpts {
  reportAllChanges?: boolean;
}
```

Metric-specific subclasses:

##### `INPReportOpts`

```ts
interface INPReportOpts extends ReportOpts {
  durationThreshold?: number;
}
```

#### `AttributionReportOpts`

A subclass of `ReportOpts` used for each metric function exported in the [attribution build](#attribution).

```ts
interface AttributionReportOpts extends ReportOpts {
  generateTarget?: (el: Node | null) => string | null | undefined;
}
```

Metric-specific subclasses:

##### `INPAttributionReportOpts`

```ts
interface INPAttributionReportOpts extends AttributionReportOpts {
  durationThreshold?: number;
  includeProcessedEventEntries?: boolean;
  reportSoftNavs?: boolean;
}
```

#### `LoadState`

The `LoadState` type is used in several of the metric [attribution objects](#attribution).

```ts
/**
 * 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';
```

### Functions:

#### `onCLS()`

```ts
function onCLS(callback: (metric: CLSMetric) => void, opts?: ReportOpts): void;
```

Calculates the [CLS](https://web.dev/articles/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](https://heycam.github.io/webidl/#idl-double) (corresponding to a [layout shift score](https://web.dev/articles/cls#layout_shift_score)).

> [!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](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden), `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](#report-only-the-delta-of-changes) for how to manage this).

If the `reportAllChanges` [configuration option](#reportopts) 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 (though [not necessarily for every layout shift](#report-the-value-on-every-change)). Note that regardless of whether `reportAllChanges` is used, the final reported value will be the same.

#### `onFCP()`

```ts
function onFCP(callback: (metric: FCPMetric) => void, opts?: ReportOpts): void;
```

Calculates the [FCP](https://web.dev/articles/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`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp).

#### `onINP()`

```ts
function onINP(
  callback: (metric: INPMetric) => void,
  opts?: INPReportOpts,
): void;
```

Calculates the [INP](https://web.dev/articles/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`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp).

> [!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](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden), `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](#report-only-the-delta-of-changes) for how to manage this).

A custom `durationThreshold` [configuration option](#reportopts) can optionally be passed to control the minimum duration filter for `event-timing`. Events which are faster than this threshold are not reported. Note that the `first-input` entry is always observed, regardless of duration, to ensure you always have some INP score. The default threshold, after the library is initialized, is `40` milliseconds (the `event-timing` default of `104` milliseconds applies to all events emitted before the library is initialised). This default threshold of `40` is chosen to strike a balance between usefulness and performance. Running this callback for any interaction that spans just one or two frames is likely not worth the insight that could be gained.

If the `reportAllChanges` [configuration option](#reportopts) 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 (though [not necessarily for every interaction](#report-the-value-on-every-change)). Note that regardless of whether `reportAllChanges` is used, the final reported value will be the same.

#### `onLCP()`

```ts
function onLCP(callback: (metric: LCPMetric) => void, opts?: ReportOpts): void;
```

Calculates the [LCP](https://web.dev/articles/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`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp).

If the `reportAllChanges` [configuration option](#reportopts) 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. Note that regardless of whether `reportAllChanges` is used, the final reported value will be the same.

#### `onTTFB()`

```ts
function onTTFB(
  callback: (metric: TTFBMetric) => void,
  opts?: ReportOpts,
): void;
```

Calculates the [TTFB](https://web.dev/articles/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`](https://developer.mozilla.org/docs/Web/API/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](https://w3c.github.io/navigation-timing/).

For example, the TTFB metric starts from the page's [time origin](https://www.w3.org/TR/hr-time-2/#sec-time-origin), which means it includes time spent on DNS lookup, connection negotiation, network latency, and server processing time.

```js
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`](https://developer.mozilla.org/docs/Web/API/DOMHighResTimeStamp)). This ensures code referencing these values (like in the example above) will work the same in all browsers.

### Rating Thresholds:

The thresholds of each metric's "good", "needs improvement", and "poor" ratings are available as [`MetricRatingThresholds`](#metricratingthresholds).

Example:

```ts
import {CLSThresholds, INPThresholds, LCPThresholds} from 'web-vitals';

console.log(CLSThresholds); // [ 0.1, 0.25 ]
console.log(INPThresholds); // [ 200, 500 ]
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']`](#metric) instead.

### Attribution:

In the [attribution build](#attribution-build) each of the metric functions has two primary differences from their standard build counterparts:

1. Their callback is invoked with a `MetricWithAttribution` objects instead of a `Metric` object. Each `MetricWithAttribution` extends the `Metric` object and adds an additional `attribution` object, which contains 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.

2. They accept an `AttributionReportOpts` objects instead of a `ReportOpts` object. The `AttributionReportOpts` object supports an additional, optional, `generateTarget()` function that lets developers customize how DOM elements are stringified for reporting purposes. When passed, the return value of the `generateTarget()` function will be used for any "target" properties in the following attribution objects: [`CLSAttribution`](#CLSAttribution), [`INPAttribution`](#INPAttribution), and [`LCPAttribution`](#LCPAttribution). If `null` or `undefined` is returned by the `generateTarget()` function, or no function is given, then the default selector function will be used.

   ```ts
   interface AttributionReportOpts extends ReportOpts {
     generateTarget?: (el: Node | null) => string | null | undefined;
   }
   ```

   For example, if a web page has unique `data-name` attribute on many elements, you may prefer to use those over the built-in selector-style strings that are generated by default.

   ```js
   function customGenerateTarget(el) {
     if (el.dataset.name) {
       return el.dataset.name;
     }

     // Otherwise use default selector function
   }

   onLCP(sendToAnalytics, {generateTarget: customGenerateTarget});
   ```

3. The `onINP` `AttributionReportOpts` supports an additional, optional, `includeProcessedEventEntries` configuration option. When set to `true`, _all_ the `event` performance entries processed during the INP duration will be included in the `attribution.processedEventEntries` object. This can include a lot of events and increased memory on very interactive or event-heavy pages. The default value is `false`. Regardless of this setting, the `entries` object will include the entries with an `interactionId` (which are the entries relevant for INP), but use this setting to include all entries (whether they have an `interactionId` or not) in `attribution.processedEventEntries` if you need more attribution information to identify delays to INP events.

```ts
interface INPAttributionReportOpts extends AttributionReportOpts {
  durationThreshold?: number;
  includeProcessedEventEntries?: boolean;
}
```

The next sections document the shape of the `attribution` object for each of the metrics:

#### `CLSAttribution`

```ts
interface CLSAttribution {
  /**
   * By default, a selector identifying the first element (in document order)
   * that shifted when the single largest layout shift that contributed to the
   * page's CLS score occurred. If the `generateTarget` configuration option
   * was passed, then this will instead be the return value of that function,
   * falling back to the default if that returns null or undefined.
   */
  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;
}
```

#### `FCPAttribution`

```ts
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 | PerformanceSoftNavigation;
}
```

#### `INPAttribution`

```ts
interface INPAttribution {
  /**
   * By default, a selector identifying the element that the user first
   * interacted with as part of the frame where the INP candidate interaction
   * occurred. If this value is an empty string, that generally means the
   * element was removed from the DOM after the interaction. If the
   * `generateTarget` configuration option was passed, then this will instead
   * be the return value of that function, falling back to the default if that
   * returns null or undefined.
   * This value may not be set in cases where the event duration was less than
   * the browser minimum reporting threshold, and thus no entry was dispatched.
   */
  interactionTarget?: string;
  /**
   * The time when the user first interacted during the frame where the INP
   * candidate interaction occurred (if more than one interaction occurred
   * within the frame, only the first time is reported).
   * This value may not be set in cases where the event duration was less than
   * the browser minimum reporting threshold, and thus no entry was dispatched.
   */
  interactionTime?: DOMHighResTimeStamp;
  /**
   * The type of interaction, based on the event type of the `event` entry
   * that corresponds to the interaction (i.e. the first `event` entry
   * containing an `interactionId` dispatched in a given animation frame).
   * For "pointerdown", "pointerup", or "click" events this will be "pointer",
   * and for "keydown" or "keyup" events this will be "keyboard".
   * This value may not be set in cases where the event duration was less than
   * the browser minimum reporting threshold, and thus no entry was dispatched.
   */
  interactionType?: 'pointer' | 'keyboard';
  /**
   * The best-guess timestamp of the next paint after the interaction.
   * In general, this timestamp is the same as the `startTime + duration` of
   * the event timing entry. However, since duration values are rounded to the
   * nearest 8ms (and can be rounded down), this value is clamped to always be
   * reported after the processing times.
   * This value may not be set in cases where the event duration was less than
   * the browser minimum reporting threshold, and thus no entry was dispatched.
   */
  nextPaintTime?: DOMHighResTimeStamp;
  /**
   * An array of Event Timing entries that were processed within the same
   * animation frame as the INP candidate interaction.
   * This array can be quite large so it will be empty unless the
   * `includeProcessedEventEntries` configuration option is set to `true` to
   * conserve memory if these entries are not required.
   */
  processedEventEntries: PerformanceEventTiming[];
  /**
   * The time from when the user interacted with the page until when the
   * browser was first able to start processing event listeners for that
   * interaction. This time captures the delay before event processing can
   * begin due to the main thread being busy with other work.
   */
  inputDelay: number;
  /**
   * The time from when the first event listener started running in response to
   * the user interaction until when all event listener processing has finished.
   */
  processingDuration: number;
  /**
   * The time from when the browser finished processing all event listeners for
   * the user interaction until the next frame is presented on the screen and
   * visible to the user. This time includes work on the main thread (such as
   * `requestAnimationFrame()` callbacks, `ResizeObserver` and
   * `IntersectionObserver` callbacks, and style/layout calculation) as well
   * as off-main-thread work (such as compositor, GPU, and raster work).
   */
  presentationDelay: number;
  /**
   * The loading state of the document at the time when the interaction
   * 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;
  /**
   * If the browser supports the Long Animation Frame API, this array will
   * include any `long-animation-frame` entries that intersect with the INP
   * candidate interaction's `startTime` and the `processingEnd` time of the
   * last event processed within that animation frame. If the browser does not
   * support the Long Animation Frame API or no `long-animation-frame` entries
   * are detected, this array will be empty.
   */
  longAnimationFrameEntries: PerformanceLongAnimationFrameTiming[];
  /**
   * Summary information about the longest script entry intersecting the INP
   * duration. Note, only script entries above 5 milliseconds are reported by
   * the Long Animation Frame API.
   */
  longestScript?: INPLongestScriptSummary;
  /**
   * The total duration of Long Animation Frame scripts that intersect the INP
   * duration excluding any forced style and layout (that is included in
   * totalStyleAndLayout). Note, this is limited to scripts > 5 milliseconds.
   */
  totalScriptDuration?: number;
  /**
   * The total style and layout duration from any Long Animation Frames
   * intersecting the INP interaction. This includes any end-of-frame style and
   * layout duration + any forced style and layout duration.
   */
  totalStyleAndLayoutDuration?: number;
  /**
   * The off main-thread presentation delay from the end of the last Long
   * Animation Frame (where available) until the INP end point.
   */
  totalPaintDuration?: number;
  /**
   * The total unattributed time not included in any of the previous totals.
   * This includes scripts < 5 milliseconds and other timings not attributed
   * by Long Animation Frame (including when a frame is < 50ms and so has no
   * Long Animation Frame).
   * When no Long Animation Frames are pre