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).
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); // []
});