How do I send Web Vitals data to Google Analytics?

Follow the example in the README: import the library, define a callback function that uses gtag('event', ...) with metric properties like delta and id, and attach it to onCLS, onINP, and onLCP. This allows aggregating real-user performance data in GA4 for dashboards and analysis.

What's the difference between web-vitals and Lighthouse?

Web-vitals is for real-user monitoring (RUM) in production, measuring metrics on actual users' browsers, while Lighthouse is for synthetic testing in lab environments to simulate performance. Use web-vitals for field data to understand real-world experience and Lighthouse for pre-deployment optimization checks.

Which browsers support the web-vitals library?

Modern browsers generally support it, but CLS is only available in Chromium, while FCP, INP, LCP, and TTFB work in Chromium, Firefox, and Safari. Check the browser support section for specifics, as some metrics rely on underlying Web APIs that may not be universally available.

How can I debug layout shifts with web-vitals?

Use the attribution build by importing from 'web-vitals/attribution', which adds an attribution property to metric objects with details like largestShiftTarget to identify the elements causing shifts. This helps pinpoint issues for optimization in real-user scenarios.

Can I measure Web Vitals in iframes?

No, the library does not support iframe content due to browser API limitations, as stated in the limitations section. For same-origin iframes, you must add the library to each frame and aggregate data manually, which increases complexity and may not match tools like Chrome UX Report.

How to batch multiple Web Vitals reports together?

Implement a queue system as shown in the README: add metrics to a set on callback, then flush the queue on visibility change to hidden using navigator.sendBeacon. This minimizes network usage by sending batched data in a single request, ideal for analytics endpoints.

Open-Awesome

Web Vitals

Apache-2.0JavaScript

A tiny, modular JavaScript library for measuring Core Web Vitals and other essential performance metrics on real users.

Visit Website GitHub

8.7k stars537 forks0 contributors

What is Web Vitals?

Web Vitals is a JavaScript library developed by the Google Chrome team for measuring essential web performance metrics on real users. It provides functions to accurately track Core Web Vitals (CLS, INP, LCP) and other metrics like FCP and TTFB, matching how Chrome measures them. It solves the problem of understanding actual user experience and diagnosing performance issues in production.

Target Audience

Frontend developers, performance engineers, and web analytics teams who need to measure and optimize real-user performance for their websites or web applications.

Value Proposition

Developers choose Web Vitals because it's the official, lightweight library that guarantees measurement accuracy aligned with Google's tools (Chrome UX Report, PageSpeed Insights). Its modular design, attribution features for debugging, and flexible reporting options make it the most reliable way to collect performance data.

Overview

Essential metrics for a healthy site.

Use Cases

Best For

Measuring Core Web Vitals (CLS, INP, LCP) in production environments
Sending real-user performance data to analytics platforms like Google Analytics
Debugging performance issues with detailed attribution data
Integrating performance monitoring into custom analytics pipelines
Tracking performance metrics for SEO and user experience optimization
Creating performance dashboards with data from real users

Not Ideal For

Synthetic performance testing in lab environments (e.g., using Lighthouse or WebPageTest for pre-deployment checks)
Projects requiring performance metrics from within iframes, as the library has no visibility into iframe content
Websites targeting legacy browsers without support for modern Performance APIs, particularly for CLS measurement
Server-side performance monitoring, since the library only runs in the browser and cannot measure backend latency or server processing times

Pros & Cons

Pros

Official Google Accuracy

Measures Web Vitals exactly as Chrome and Google tools like PageSpeed Insights do, ensuring data consistency with industry standards for real-user experience.

Minimal Bundle Size

The standard build is tiny at ~2K brotli'd, minimizing performance overhead and making it easy to add without significant load impact.

Powerful Debugging Attribution

The optional attribution build adds detailed diagnostic data, such as element targets and timing breakdowns, to help identify root causes of poor performance in production.

Flexible Integration Options

Supports loading via npm, CDN, or classic scripts, with no need for early loading due to the buffered PerformanceObserver flag, allowing deferred integration.

Cons

Limited Cross-Browser Support

CLS measurement is only available in Chromium-based browsers, leaving gaps for users on Firefox or Safari, as noted in the browser support section.

No Iframe Measurement

Cannot capture metrics within iframes, even same-origin ones, which means data may not match comprehensive tools like Chrome User Experience Report, as admitted in the limitations.

Attribution Build Overhead

While useful for debugging, the attribution build is about 1.5K larger and adds complexity, requiring careful setup for custom analytics pipelines.

Frequently Asked Questions

Related Projects

Lighthouse

Automated auditing, performance metrics, and best practices for the web.

Stars30,924

Forks9,772

Last commit1 day ago