+4
日增长
+18
周增长
+38
月增长
8,685
stars
542
forks
122
watchers
410
prs
378
issues
0
releases
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 Top issues
#335Target in FID and INP is null15 comments · 2023-03-29#777Separate soft nav endpoints13 comments · 2026-08-06#689Firefox sometimes reports the wrong LCP element5 comments · 2026-02-02#823INP attribution counts ResizeObserver callbacks twice4 comments · 2026-11-05#448Allow to reset the INP calculation4 comments · 2024-03-27#310Add @types to DefinitelyTyped3 comments · 2023-01-28#673Add new `target` fallback for INP event2 comments · 2026-01-07#361consider adding user-like code that can be type checked2 comments · 2023-06-20