A simple, light-weight (~0.8K) library for measuring all the Web Vitals metrics on real users, in a way that accurately matches how they're reported by other Google tools (e.g. Chrome User Experience Report, Page Speed Insights, Lighthouse).

• Installation
• Usage
• API
  • Types
  • Functions
• Development
• Browser Support

You can install this library from npm by running:

npm install web-vitals

Each of the Web Vitals metrics are exposed through a single function that takes an onReport callback. This callback will fire as soon as:

• The final value of the metric has been determined.
• The current metric value needs to be reported right away (due to the page being unloaded or backgrounded).

The following example logs the result of each metric to the console once its value is ready to report.

import {getCLS, getFID, getLCP} from 'web-vitals';

getCLS(console.log);
getFID(console.log);
getLCP(console.log);

Note: some of these metrics will not report until the user has interacted with the page, switches tabs, or the page starts to unload. If you don't see the values logged to the console immediately, try switching tabs and then switching back.

The following example measures each of the core Web Vitals metrics and reports them to a local /analytics endpoint once known.

This code uses the navigator.sendBeacon() method (if available), but falls back to the fetch() API when not.

import {getCLS, getFID, getLCP} from 'web-vitals';

function reportMetric(body) {
  // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
      fetch('/analytics', {body, method: 'POST', keepalive: true});
}

getCLS((metric) => {
  reportMetric(JSON.stringify({cls: metric.value}));
});

getFID((metric) => {
  reportMetric(JSON.stringify({fid: metric.value}));
});

getLCP(({metric}) => {
  reportMetric(JSON.stringify({lcp: metric.value}));
});

In most cases, you only want to call onReport when the metric is ready. However, for metrics like LCP and CLS (where the value may change over time) you can pass an optional, second argument (reportAllChanges). If true then onReport will be called any time the value of the metric changes, or once the final value has been determined.

This could be useful if, for example, you want to report the current LCP candidate as the page is loading, or you want to report layout shifts (and the current CLS value) as users are interacting with the page.

import {getCLS, getFID, getLCP} from 'web-vitals';

getCLS(console.log, true);
getFID(console.log); // Does not take a `reportAllChanges` param.
getLCP(console.log, true);

Note: when using the reportAllChanges option, pay attention to the isFinal property of the reported metric, which will indicate whether or not the value might change in the future. See the API reference below for more details.

Some analytics providers allow you to update the value of a metric, even after you've already sent it to their servers. Other analytics providers, however, do not allow this, so instead of reporting the updated value, you need to report only the delta (the difference between the current value and the last-reported value).

The following example modifies the analytics code above to only report the delta of the changes:

import {getCLS, getFID, getLCP} from 'web-vitals';

function reportMetric(body) {
  // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
      fetch('/analytics', {body, method: 'POST', keepalive: true});
}

getCLS((metric) => {
  reportMetric(JSON.stringify({cls: metric.delta}));
});

getFID((metric) => {
  reportMetric(JSON.stringify({fid: metric.delta}));
});

getLCP(({metric}) => {
  reportMetric(JSON.stringify({lcp: metric.delta}));
});

Note: the first time the onReport function is called, its value and delta property will be the same.

interface Metric {
  // The value of the metric.
  value: number;

  // 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;

  // `false` if the value of the metric may change in the future.
  isFinal: boolean;

  // Any performance entries used in the metric value calculation.
  // Note, entries will be added to the array as the value changes.
  entries: PerformanceEntry[];

  // Only present using the FID polyfill.
  event?: Event
}

interface ReportHandler {
  (metric: Metric): void;
}

type getCLS = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the CLS value for the current page and calls the onReport function once the value is ready to be reported, along with all layout-shift performance entries that were used in the metric value calculation.

If the reportAllChanges param is true, the onReport function will be called any time a new layout-shift performance entry is dispatched, or once the final value of the metric has been determined.

Important: unlike other metrics, CLS continues to monitor changes for the entire lifespan of the page—including if the user returns to the page after it's been hidden/backgrounded or put in the Page Navigation Cache. However, since browsers often will not fire additional callbacks once the user has backgrounded a page, onReport is always called when the page's visibility state changes to hidden. As a result, the onReport function might be called multiple times during the same page load (see Reporting only the delta of changes for how to manage this).

type getFCP = (onReport: ReportHandler) => void

Calculates the FCP value for the current page and calls the onReport function once the value is ready, along with the relevant paint performance entry used to determine the value.

type getFID = (onReport: ReportHandler) => void

Calculates the FID value for the current page and calls the onReport function once the value is ready, along with the relevant first-input performance entry used to determine the value (and optionally the input event if using the FID polyfill).

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.

type getLCP = (onReport: ReportHandler, reportAllChanges?: boolean) => void

Calculates the LCP value for the current page and calls the onReport function once the value is ready (along with the relevant largest-contentful-paint performance entries used to determine the value).

If passed an onReport function, that function will be invoked any time a new largest-contentful-paint performance entry is dispatched, or once the final value of the metric has been determined.

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:https://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.

This code has been tested and will run without error in all major browsers as well as Internet Explorer back to version 9.

However, the APIs required to capture these metrics are currently only available in Chromium-based browsers (e.g. Chrome, Edge, Opera, Samsung Internet).

One exception to the above is that getFID() will work in all browsers if the page has included the FID polyfill.

Browsers that support the native Event Timing API will use that and report the metric value from the first-input performance entry.

Browsers that do not support the native Event Timing API will report the value reported by the polyfill, including the Event object of the first input.

For example:

import {getFID} from 'web-vitals';

getFID((metric) => {
  // When using the polyfill, the `event` property will be present.
  // The  `entries` property will also be present, but it will be empty.
  console.log(metric.event); // Event
  console.log(metric.entries);  // []
});

Apache 2.0