README

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
  - Report metrics for soft navigations
  - 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 (~3K, 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:

sh
npm install web-vitals


 [!NOTE]
 If you're not using npm, you can still load web-vitals via  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):

js
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