0
# Web Vitals
1

2
Web Vitals is a tiny (~2K, 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. It supports all Core Web Vitals and additional performance metrics, with both standard measurement and attribution builds for detailed performance debugging.
3

4
## Package Information
5

6
- **Package Name**: web-vitals
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web-vitals`
10

11
## Core Imports
12

13
```typescript
14
import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
15
```
16

17
For attribution build (includes debugging information):
18

19
```typescript
20
import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals/attribution";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { onCLS, onFCP, onINP, onLCP, onTTFB } = require("web-vitals");
27
```
28

29
Individual module imports:
30

31
```typescript
32
import { onCLS } from "web-vitals/onCLS.js";
33
import { onFCP } from "web-vitals/onFCP.js";
34
import { onINP } from "web-vitals/onINP.js";
35
import { onLCP } from "web-vitals/onLCP.js";
36
import { onTTFB } from "web-vitals/onTTFB.js";
37
```
38

39
Attribution build individual modules:
40

41
```typescript
42
import { onCLS } from "web-vitals/attribution/onCLS.js";
43
import { onFCP } from "web-vitals/attribution/onFCP.js";
44
import { onINP } from "web-vitals/attribution/onINP.js";
45
import { onLCP } from "web-vitals/attribution/onLCP.js";
46
import { onTTFB } from "web-vitals/attribution/onTTFB.js";
47
```
48

49
## Basic Usage
50

51
```typescript
52
import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
53

54
// Measure Core Web Vitals
55
onCLS((metric) => {
56
  console.log('CLS:', metric.value, metric.rating);
57
});
58

59
onINP((metric) => {
60
  console.log('INP:', metric.value, metric.rating);
61
});
62

63
onLCP((metric) => {
64
  console.log('LCP:', metric.value, metric.rating);
65
});
66

67
// Measure Other Web Vitals
68
onFCP((metric) => {
69
  console.log('FCP:', metric.value, metric.rating);
70
});
71

72
onTTFB((metric) => {
73
  console.log('TTFB:', metric.value, metric.rating);
74
});
75
```
76

77
## Architecture
78

79
Web Vitals is built around several key components:
80

81
- **Metric Functions**: Individual functions for each Web Vitals metric (`onCLS`, `onFCP`, `onINP`, `onLCP`, `onTTFB`)
82
- **Standard vs Attribution Builds**: Two versions available - standard for basic measurement, attribution for detailed debugging
83
- **Performance Observer Integration**: Uses browser APIs with buffered entries to capture complete performance data
84
- **Rating System**: Automatic classification of metrics as "good", "needs improvement", or "poor"
85
- **Delta Reporting**: Tracks changes over time with both absolute values and deltas from previous reports
86

87
## Capabilities
88

89
### Core Web Vitals Measurement
90

91
Functions to measure the three Core Web Vitals metrics that are part of Google's page experience signals.
92

93
```typescript { .api }
94
function onCLS(callback: (metric: CLSMetric) => void, opts?: ReportOpts): void;
95
function onINP(callback: (metric: INPMetric) => void, opts?: INPReportOpts): void;
96
function onLCP(callback: (metric: LCPMetric) => void, opts?: ReportOpts): void;
97
```
98

99
[Core Web Vitals](./core-web-vitals.md)
100

101
### Additional Web Vitals Measurement
102

103
Functions to measure additional Web Vitals metrics useful for performance monitoring and debugging.
104

105
```typescript { .api }
106
function onFCP(callback: (metric: FCPMetric) => void, opts?: ReportOpts): void;
107
function onTTFB(callback: (metric: TTFBMetric) => void, opts?: ReportOpts): void;
108
```
109

110
[Additional Web Vitals](./additional-web-vitals.md)
111

112
### Attribution Build
113

114
Enhanced measurement functions that include detailed attribution data for performance debugging and optimization.
115

116
```typescript { .api }
117
function onCLS(callback: (metric: CLSMetricWithAttribution) => void, opts?: AttributionReportOpts): void;
118
function onINP(callback: (metric: INPMetricWithAttribution) => void, opts?: INPAttributionReportOpts): void;
119
function onLCP(callback: (metric: LCPMetricWithAttribution) => void, opts?: AttributionReportOpts): void;
120
function onFCP(callback: (metric: FCPMetricWithAttribution) => void, opts?: AttributionReportOpts): void;
121
function onTTFB(callback: (metric: TTFBMetricWithAttribution) => void, opts?: AttributionReportOpts): void;
122
```
123

124
[Attribution Build](./attribution.md)
125

126
### Threshold Constants
127

128
Pre-defined threshold values for determining metric ratings according to Web Vitals standards.
129

130
```typescript { .api }
131
const CLSThresholds: MetricRatingThresholds;
132
const FCPThresholds: MetricRatingThresholds;
133
const INPThresholds: MetricRatingThresholds;
134
const LCPThresholds: MetricRatingThresholds;
135
const TTFBThresholds: MetricRatingThresholds;
136
```
137

138
[Thresholds](./thresholds.md)
139

140
## Core Types
141

142
```typescript { .api }
143
interface Metric {
144
  /** The name of the metric (in acronym form) */
145
  name: 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
146
  /** The current value of the metric */
147
  value: number;
148
  /** The rating as to whether the metric value is within thresholds */
149
  rating: 'good' | 'needs-improvement' | 'poor';
150
  /** The delta between current and last-reported value */
151
  delta: number;
152
  /** A unique ID representing this particular metric instance */
153
  id: string;
154
  /** Any performance entries relevant to the metric value calculation */
155
  entries: PerformanceEntry[];
156
  /** The type of navigation */
157
  navigationType: 'navigate' | 'reload' | 'back-forward' | 'back-forward-cache' | 'prerender' | 'restore';
158
}
159

160
interface ReportOpts {
161
  /** Whether to report all metric changes or just final values */
162
  reportAllChanges?: boolean;
163
}
164

165
interface INPReportOpts extends ReportOpts {
166
  /** Minimum duration threshold for INP interactions */
167
  durationThreshold?: number;
168
}
169

170
interface AttributionReportOpts extends ReportOpts {
171
  /** Custom function to generate target selectors for DOM elements */
172
  generateTarget?: (el: Node | null) => string | undefined;
173
}
174

175
interface INPAttributionReportOpts extends AttributionReportOpts {
176
  /** Minimum duration threshold for INP interactions */
177
  durationThreshold?: number;
178
}
179

180
type MetricRatingThresholds = [number, number];
181
```