web-vitals Technology Intelligence

What is Web Vitals?

Web Vitals is a Google initiative and JavaScript library for measuring real user experience metrics on websites. The library provides tools to capture Core Web Vitals and other performance metrics that indicate page quality. These metrics help developers understand how users actually experience their websites beyond synthetic testing.

Core Web Vitals include Largest Contentful Paint (LCP) measuring loading performance, Interaction to Next Paint (INP) measuring interactivity, and Cumulative Layout Shift (CLS) measuring visual stability. These three metrics form the foundation of Google's page experience signals used in search ranking.

The web-vitals JavaScript library enables easy measurement of these metrics directly in production. The library uses browser Performance APIs to capture accurate timing data from real user sessions. This real user monitoring (RUM) provides insights that lab testing alone cannot capture.

Beyond Core Web Vitals, the library measures additional metrics like First Contentful Paint (FCP), First Input Delay (FID), and Time to First Byte (TTFB). These supplementary metrics provide deeper insight into specific aspects of page performance.

Detection of web-vitals on a website indicates commitment to performance monitoring and user experience optimization. Development teams using web-vitals typically prioritize page speed, monitor production performance, and optimize based on real user data.

Web Vitals Library Features

Core Web Vitals: LCP measurement for loading. INP measurement for interactivity. CLS measurement for stability. Google-defined thresholds.

Additional Metrics: FCP for first content render. FID for first interaction. TTFB for server response. Complete performance picture.

Real User Data: Production measurement. Actual user experiences. Device and network variety. Geographic distribution.

Attribution Data: Identify performance causes. Element-level attribution. Debug information included. Root cause analysis.

Lightweight: Small bundle size. No dependencies. Minimal performance impact. Efficient implementation.

Browser Support: Modern browser APIs utilized. Graceful degradation. Cross-browser compatibility. Feature detection built-in.

Easy Integration: Simple API surface. Callback-based results. Analytics integration ready. Flexible reporting options.

Web Vitals Use Cases

Performance Monitoring: Track real user performance. Monitor production metrics. Identify degradation. Measure improvements.

SEO Optimization: Core Web Vitals affect rankings. Page experience signals. Search performance improvement. Competitive advantage.

User Experience Analysis: Understand actual user experience. Identify slow experiences. Segment by device type. Geographic analysis.

Performance Budgets: Set metric thresholds. Alert on violations. Maintain performance standards. Prevent regressions.

A/B Testing: Measure performance impact of changes. Compare variant performance. Data-driven decisions. Performance validation.

Development Workflow: Pre-deployment testing. Continuous monitoring. Performance regression detection. Release confidence.

Web Vitals Integration Examples

Installation

npm install web-vitals

# Or via CDN
# https://unpkg.com/web-vitals

Basic Usage

import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';

// Measure Core Web Vitals
onCLS(console.log);  // Cumulative Layout Shift
onINP(console.log);  // Interaction to Next Paint
onLCP(console.log);  // Largest Contentful Paint

// Additional metrics
onFCP(console.log);  // First Contentful Paint
onTTFB(console.log); // Time to First Byte

// Each callback receives a metric object:
// {
//   name: 'LCP',
//   value: 2500,
//   rating: 'needs-improvement',
//   delta: 2500,
//   entries: [...],
//   id: 'v3-1234567890'
// }

Send to Analytics

import { onCLS, onINP, onLCP } from 'web-vitals';

function sendToAnalytics(metric) {
    // Google Analytics 4
    gtag('event', metric.name, {
        value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value),
        event_category: 'Web Vitals',
        event_label: metric.id,
        non_interaction: true
    });

    // Or custom endpoint
    const body = JSON.stringify({
        name: metric.name,
        value: metric.value,
        rating: metric.rating,
        delta: metric.delta,
        id: metric.id,
        page: window.location.pathname
    });

    // Use sendBeacon for reliability
    if (navigator.sendBeacon) {
        navigator.sendBeacon('/analytics/vitals', body);
    } else {
        fetch('/analytics/vitals', { body, method: 'POST', keepalive: true });
    }
}

onCLS(sendToAnalytics);
onINP(sendToAnalytics);
onLCP(sendToAnalytics);

Attribution for Debugging

import { onLCP, onCLS, onINP } from 'web-vitals/attribution';

onLCP((metric) => {
    console.log('LCP:', metric.value);
    console.log('Element:', metric.attribution.element);
    console.log('Resource URL:', metric.attribution.url);
    console.log('Time to first byte:', metric.attribution.timeToFirstByte);
    console.log('Resource load delay:', metric.attribution.resourceLoadDelay);
});

onCLS((metric) => {
    console.log('CLS:', metric.value);
    metric.attribution.largestShiftSources.forEach(source => {
        console.log('Shifted element:', source.node);
        console.log('Previous rect:', source.previousRect);
        console.log('Current rect:', source.currentRect);
    });
});

onINP((metric) => {
    console.log('INP:', metric.value);
    console.log('Interaction target:', metric.attribution.interactionTarget);
    console.log('Interaction type:', metric.attribution.interactionType);
    console.log('Input delay:', metric.attribution.inputDelay);
    console.log('Processing time:', metric.attribution.processingDuration);
    console.log('Presentation delay:', metric.attribution.presentationDelay);
});

Report All Metrics

import { onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals';

const vitalsUrl = 'https://analytics.example.com/vitals';

function sendToEndpoint({ name, delta, value, id, rating }) {
    const body = JSON.stringify({ name, delta, value, id, rating });
    (navigator.sendBeacon && navigator.sendBeacon(vitalsUrl, body)) ||
        fetch(vitalsUrl, { body, method: 'POST', keepalive: true });
}

// Report all metrics
onCLS(sendToEndpoint);
onFCP(sendToEndpoint);
onINP(sendToEndpoint);
onLCP(sendToEndpoint);
onTTFB(sendToEndpoint);

React Integration

// In Next.js: pages/_app.js
import { useEffect } from 'react';
import { onCLS, onINP, onLCP } from 'web-vitals';

export function reportWebVitals(metric) {
    switch (metric.name) {
        case 'CLS':
        case 'INP':
        case 'LCP':
            console.log(metric);
            sendToAnalytics(metric);
            break;
        default:
            break;
    }
}

// Or manual setup in any React app
function App() {
    useEffect(() => {
        onCLS(console.log);
        onINP(console.log);
        onLCP(console.log);
    }, []);

    return ;
}

Why Developers Choose Web Vitals

Google Standard: Official Google metrics. Search ranking factors. Industry-standard measurements. Consistent definitions.

Real User Data: Production measurements. Actual user experiences captured. Beyond lab testing. True performance picture.

Lightweight: Minimal bundle impact. No performance overhead. Efficient implementation. Production-safe.

Easy Integration: Simple API. Quick setup. Major frameworks supported. Analytics-ready format.

Debugging Support: Attribution build available. Element identification. Root cause data. Actionable insights.

SEO Benefits: Core Web Vitals affect rankings. Competitive advantage. User experience alignment. Business impact.

Active Maintenance: Google maintained. Regular updates. New metrics added. Evolving with web standards.