Web Vitals — Measure Core Web Performance Metrics

Introduction

Web Vitals is a lightweight library by Google Chrome that provides a reliable way to measure Core Web Vitals metrics in the field. It captures the same performance data that Chrome reports to the Chrome User Experience Report and Google Search ranking signals.

What Web Vitals Does

• Measures Largest Contentful Paint (LCP), the time until the largest visible element renders
• Tracks Interaction to Next Paint (INP), measuring responsiveness to user input
• Reports Cumulative Layout Shift (CLS), quantifying unexpected layout movements
• Captures First Contentful Paint (FCP) and Time to First Byte (TTFB)
• Sends metrics via callbacks so you can report them to any analytics endpoint

Architecture Overview

The library uses the PerformanceObserver API and web platform APIs (LargestContentfulPaint, LayoutShift, Event Timing) to observe browser-reported entries. It handles edge cases like back/forward cache restores, visibility changes, and soft navigations. Each metric function registers observers, accumulates or finalizes values, and invokes your callback with a standardized metric object.

Self-Hosting & Configuration

• Install from npm: npm install web-vitals
• Import individual metric functions or the full bundle (under 2 KB gzipped)
• Use the attribution build for debugging: import from 'web-vitals/attribution'
• Call metric functions once and pass a callback to handle the result
• Works in any modern browser; gracefully no-ops in unsupported environments

Key Features

• Under 2 KB gzipped with zero dependencies
• Attribution build that explains why each metric scored the way it did
• Supports the reportAllChanges option for observing metric updates in real time
• Handles soft navigation metrics for single-page applications
• Matches Chrome's internal measurement methodology exactly

Comparison with Similar Tools

• Lighthouse — Lab-based auditing tool; Web Vitals measures real user metrics in the field
• Performance Observer API — Raw browser API; Web Vitals wraps it with correct finalization logic and edge-case handling
• Perfume.js — Similar field metrics library; Web Vitals is maintained by the Chrome team and matches CrUX methodology
• SpeedCurve / Calibre — Commercial RUM platforms; Web Vitals is a free client-side library you pair with any analytics backend

FAQ

Q: When should I use the attribution build? A: Use it during development and debugging. It adds detail about which element or interaction caused a metric score, at the cost of a slightly larger bundle.

Q: Does it work with single-page applications? A: Yes. The library supports soft navigation detection and can re-report metrics after client-side route changes.

Q: How do I send metrics to my analytics service? A: Pass a callback to each metric function and inside it send a beacon or fetch request to your analytics endpoint with the metric name, value, and ID.

Q: Is this the same data Google uses for search ranking? A: Yes. Web Vitals measures the same Core Web Vitals metrics (LCP, INP, CLS) that feed into Google's page experience ranking signals.

Sources

• https://github.com/GoogleChrome/web-vitals
• https://web.dev/articles/vitals