Philip Walton on web.dev

Our top Core Web Vitals recommendations for 2023

2023-01-10T00:00:00Z

Over the years, we at Google have made a lot of recommendations to web developers on how to improve performance.

While each of these recommendations, individually, may improve performance for many sites, the full set of recommendations is admittedly overwhelming and, realistically, there's no way any one person or site could follow all of them.

Unless web performance is your day job, it's probably not obvious which recommendations are going to have the largest positive impact on your site. For example, you might have read that implementing critical CSS can improve load performance, and you may have also heard that it's important to optimize your images. But, if you don't have time to work on both things, how would you decide which one to pick?

On the Chrome team, we've spent the last year trying to answer this question: what are the most important recommendations we can give to developers to help them improve performance for their users?

To adequately answer this question we have to consider not just the technical merits of any given recommendation, but also human and organizational factors that influence the likelihood that developers will actually be able to adopt these recommendations. In other words, some recommendations may be hugely impactful in theory, but in reality very few sites will have the time or resources to implement them. Similarly, some recommendations are critical, but most websites are already following these practices.

In short, we wanted our list of top web performance recommendations to focus on:

Recommendations we believe will have the largest real-world impact
Recommendations that are relevant and applicable to most sites
Recommendations that are realistic for most developers to implement

Over the past year we've spent a lot of time auditing the full set of performance recommendations we make, and assessing each of them (both qualitatively and quantitatively) against the above three criteria.

This post outlines our top recommendations to improve performance for each of the Core Web Vitals metrics. If you're new to web performance, or if you're trying to decide what will give you the biggest bang for your buck, we think these recommendations are the best place to start.

Largest Contentful Paint (LCP) #

Our first set of recommendations are for Largest Contentful Paint (LCP), which is a measure of load performance. Of the three Core Web Vitals metrics, LCP is the one that the largest number of sites struggle with—only about half of all sites on the web today meet the recommended threshold—so let's start there.

Ensure the LCP resource is discoverable from the HTML source #

According to the 2022 Web Almanac by HTTP Archive, 72% of mobile pages have an image as their LCP element, which means that for most sites to optimize their LCP, they'll need to ensure those images can load quickly.

What may not be obvious to many developers is that the time it takes to load an image is just one part of the challenge. Another critical part is the time before an image starts loading, and HTTP Archive data suggests that's actually where many sites get tripped up.

In fact, of the pages where the LCP element was an image, 39% of those images had source URLs that were not discoverable from the HTML document source. In other words, those URLs were not found in standard HTML attributes (such as <img src="..."> or <link rel="preload" href="...">), which would allow the browser to quickly discover them and start loading them right away.

If a page needs to wait for CSS or JavaScript files to be fully downloaded, parsed, and processed before the image can even start loading, it may already be too late.

As a general rule, if your LCP element is an image, the image's URL should always be discoverable from the HTML source. Some tips to make that possible are:

Load the image using an <img> element with the src or srcset attribute. Do not use non-standard attributes like data-src that require JavaScript in order to render, as that will always be slower. 9% of pages obscure their LCP image behind data-src.
Prefer server-side rendering (SSR) over client-side rendering (CSR), as SSR implies that the full page markup (including the image) is present in the HTML source. CSR solutions require JavaScript to run before the image can be discovered.
If your image needs to be referenced from an external CSS or JS file, you can still include it in the HTML source via a <link rel="preload"> tag. Note that images referenced by inline styles are not discoverable by the browser's preload scanner, so even though they're found in the HTML source, discovery of them might still be blocked on the loading of other resources, so preloading can help in these cases.

To help you understand if your LCP image has discoverability problems, Lighthouse will be releasing a new audit in version 10.0 (expected January 2023).

Ensuring the LCP resource is discoverable from the HTML source can lead to measurable improvements and it also unlocks additional opportunities to prioritize the resource, which is our next recommendation.

Ensure the LCP resource is prioritized #

Making sure the LCP resource can be discovered from the HTML source is a critical first step in ensuring the LCP resource can start loading early, but another important step is ensuring that the loading of that resource is prioritized and doesn't get queued behind a bunch of other, less important resources.

For example, even if your LCP image is present in the HTML source using a standard <img> tag, if your page includes a dozen <script> tags in the <head> of your document before that <img> tag, it may be a while before your image resource starts loading.

The easiest way to solve this problem is to provide a hint to the browser about what resources are the highest priority by setting the new fetchpriority="high" attribute on the <img> or <link> tag that loads your LCP image. This instructs the browser to load it earlier, rather than waiting for those scripts to complete.

According to the Web Almanac, only 0.03% of eligible pages are taking advantage of this new API, meaning there is plenty of opportunity for most sites on the web to improve LCP with very little work. While the fetchpriority attribute is currently only supported in Chromium-based browsers, this API is a progressive enhancement that other browsers just ignore, so we strongly recommend developers use it now.

For non-Chromium browsers, the only way to ensure the LCP resource is prioritized above other resources is to reference it earlier in the document. Using the example again of a site with lots of <script> tags in the <head> of the document, if you wanted to ensure your LCP resource was prioritized ahead of those script resources, you could add a <link rel="preload"> tag before any of those scripts, or you could move those scripts to below the <img> later in the <body>. While this works, it's less ergonomic than using fetchpriority, so we hope other browsers add support soon.

Another critical aspect of prioritizing the LCP resource is to ensure you don't do anything that causes it to be deprioritized, such as adding the loading="lazy" attribute. Today, 10% of pages actually set loading="lazy" on their LCP image. Beware of image optimization solutions that indiscriminately apply lazy-loading behavior to all images. If they provide a way to override that behavior, be sure to use it for the LCP image. If you're not sure which image will be the LCP, try using heuristics to pick a reasonable candidate.

Deferring non-critical resources is another way to effectively boost the relative priority of the LCP resource. For example, scripts that are not powering the user interface (like analytics scripts or social widgets) can be safely postponed until after the load event fires, which ensures they won't compete with other critical resources (such as the LCP resource) for network bandwidth.

To summarize, you should follow these best practices to ensure that the LCP resource is loaded early, and at high priority:

Add fetchpriority="high" to the <img> tag of your LCP image. If the LCP resource is loaded via a <link rel="preload"> tag, fear not because you can also set fetchpriority="high" on that!
Never set loading="lazy" on the <img> tag of your LCP image. Doing this will deprioritize your image and delay when it starts loading.
Defer non-critical resources when possible. Either by moving them to the end of your document, using native lazy-loading for images or iframes, or loading them asynchronously via JavaScript.

Use a CDN to optimize document and resource TTFB #

The previous two recommendations focused on making sure your LCP resource is discovered early and prioritized so it can start loading right away. The final piece to this puzzle is making sure the initial document response arrives as quickly as possible too.

The browser cannot start loading any subresources until it receives the first byte of the initial HTML document response, and the sooner that happens, the sooner everything else can start happening as well.

This time is known as Time to First Byte (TTFB), and the best way to reduce TTFB is to:

Serve your content as geographically close to your users as possible
Cache that content so recently-requested content can be served again quickly.

The best way to do both of these things is to use a CDN. CDNs distribute your resources to edge servers, which are spread across the globe, thus limiting the distance those resources have to travel over the wire to your users. CDNs also usually have fine-grained caching controls that can be customized and optimized for your site's needs.

Many developers are familiar with using a CDN to host static assets, but CDNs can serve and cache HTML documents as well, even those that are dynamically generated.

According to the Web Almanac, only 29% of HTML document requests were served from a CDN, which means there is significant opportunity for sites to claim additional savings.

Some tips for configuring your CDNs are:

Consider increasing how long content is cached for (for example, is it actually critical that content is always fresh? Or can it be a few minutes stale?).
Consider maybe even caching content indefinitely, and then purging the cache if/when you make an update.
Explore whether you can move dynamic logic currently running on your origin server to the edge (a feature of most modern CDNs).

In general, any time you can serve content directly from the edge (avoiding a trip to your origin server) it's a performance win. And even in cases where you do have to make the journey all the way back to your origin server, CDNs are generally optimized to do that much more quickly, so it's a win either way.

Cumulative Layout Shift (CLS) #

The next set of recommendations are for Cumulative Layout Shift (CLS), which is a measure of visual stability on web pages. While CLS has improved a lot on the web since 2020, about a quarter of websites still do not meet the recommended threshold, so there remains a big opportunity for many sites to improve their user experience.

Set explicit sizes on any content loaded from the page #

Layout shifts usually happen when existing content moves after other content finishes loading. Therefore, the primary way to mitigate this is to reserve any required space in advance as much as possible.

The most straightforward way to fix layout shifts caused by unsized images is to explicitly set width and height attributes (or equivalent CSS properties). However, according to HTTP Archive, 72% of pages have at least one unsized image. Without an explicit size, browsers will initially set a default height of 0px and may cause a noticeable layout shift when the image is finally loaded and the dimensions are discovered. This represents both a huge opportunity for the collective web—and that opportunity requires much less effort than some of the other recommendations suggested in this article.

It's also important to keep in mind that images are not the only contributors to CLS. Layout shifts may be caused by other content that typically loads in after the page is initially rendered, including third-party ads or embedded videos. The aspect-ratio property can help combat this. It's a relatively new CSS feature that allows developers to explicitly provide an aspect ratio to images as well as non-image elements. This will allow you to set a dynamic width (for example based on screen size), and have the browser automatically calculate the appropriate height, in much the same way as they do for images with dimensions.

Sometimes it's not possible to know the exact size of dynamic content since it is, by its very nature, dynamic. However, even if you don't know the exact size, you can still take steps to reduce the severity of layout shifts. Setting a sensible min-height is almost always better than allowing the browser to use the default height of 0px for an empty element. Using a min-height is also usually an easy fix as it still allows the container to grow to the final content height if needed—it has just reduced that amount of growth from the full amount to a hopefully more tolerable level.

Ensure pages are eligible for bfcache #

Browsers use a navigation mechanism called the back/forward cache—or bfcache for short—to instantly load a page from earlier or later in the browser history directly from a memory snapshot.

The bfcache is a significant browser-level performance optimization, and it entirely eliminates the layout shifts during page load, which for many sites is where most of their CLS occurs. The introduction of the bfcache caused the biggest improvement in CLS that we saw in 2022.

Despite this, a significant number of websites are ineligible for the bfcache and so are missing out on this free web performance win for a significant number of navigations. Unless your page is loading sensitive information that you don't want to be restored from memory, you'll want to make sure that your pages are eligible.

Site owners should check that their pages are eligible for the bfcache and work on any reasons why they are not. Chrome already has a bfcache tester in DevTools and this year we plan to enhance tooling here with a new Lighthouse audit performing a similar test and an API to measure this in the field.

While we have included the bfcache in the CLS section, as we saw the biggest gains there so far, the bfcache will generally also improve other Core Web Vitals too. It is one of a number of instant navigations available to drastically improve page navigations.

Avoid animations/transitions that use layout-inducing CSS properties #

Another common source of layout shifts is when elements are animated. For example, cookie banners or other notification banners that slide in from the top or bottom are often a contributor to CLS. This is particularly problematic when these banners push other content out of the way, but even when they don't, animating them can still impact CLS.

While HTTP Archive data can't conclusively connect animations to layout shifts, the data does show that pages that animate any CSS property that could affect layout are 15% less likely to have "good" CLS than pages overall. Some properties are associated with worse CLS than others. For instance, pages that animate margin or border widths have "poor" CLS at almost twice the rate that pages overall are assessed as poor.

This is perhaps not surprising, because any time you transition or animate any layout-inducing CSS property, it will result in layout shifts, and if those layout shifts are not within 500 milliseconds of a user interaction, they will impact CLS.

What may be surprising to some developers is that this is true even in cases where the element is taken outside of the normal document flow. For example, absolutely positioned elements that animate top or left will cause layout shifts, even if they aren't pushing other content around. However, if instead of animating top or left you animate transform:translateX() or transform:translateY(), it won't cause the browser to update page layout and thus won't produce any layout shifts.

Preferring animation of CSS properties that can be updated on the browser's compositor thread has long been a performance best practice because it moves that work onto the GPU and off the main thread. And in addition to it being a general performance best practice, it can also help improve CLS.

As a general rule, never animate or transition any CSS property that requires the browser to update the page layout, unless you're doing it in response to a user tap or key press (though not hover). And whenever possible, prefer transitions and animations using the CSS transform property.

The Lighthouse audit Avoid non-composited animations will warn when a page animates potentially slow CSS properties.

First Input Delay (FID) #

Our last set of recommendations are for First Input Delay (FID), which is a measure of a page's responsiveness to user interactions. While most sites on the web currently score very well on FID, we've documented shortcomings of the FID metric in the past, and we believe there is still a lot of opportunity for sites to improve their overall responsiveness to user interactions.

Our new Interaction to Next Paint (INP) metric is a possible successor to FID, and all of the recommendations below apply equally well to both FID and INP. Given that sites perform worse on INP than FID, especially on mobile, we encourage developers to seriously consider these responsiveness recommendations, despite having "good" FID.

Avoid or break up long tasks #

Tasks are any piece of discrete work that the browser does. Tasks include rendering, layout, parsing, and compiling and executing scripts. When tasks become long tasks—that is, 50 milliseconds or longer—they block the main thread from being able to respond quickly to user inputs.

Per the Web Almanac, there's plenty of evidence to suggest that developers could be doing more to avoid or break up long tasks. While breaking up long tasks may not be as low of an effort as other recommendations in this article, it's less effort than other techniques not offered in this article.

While you should always strive to do as little work as possible in JavaScript, you can help the main thread quite a bit by breaking up long tasks into smaller ones. You can accomplish this by yielding to the main thread often so that rendering updates and other user interactions can occur more quickly.

Another option is to consider using APIs such as isInputPending and the Scheduler API. isInputPending is a function that returns a boolean value that indicates whether a user input is pending. If it returns true, you can yield to the main thread so it can handle the pending user input.

The Scheduler API is a more advanced approach, which allows you to schedule work based on a system of priorities that take into account whether the work being done is user-visible or backgrounded.

By breaking up long tasks, you're giving the browser more opportunities to fit in critical user-visible work, such as dealing with interactions and any resulting rendering updates.

Avoid unnecessary JavaScript #

There's no doubt about it: websites are shipping more JavaScript than ever before, and the trend doesn't look like it's changing any time soon. When you ship too much JavaScript, you're creating an environment where tasks are competing for the main thread's attention. This can definitely affect your website's responsiveness, especially during that crucial startup period.

This is not an unsolvable problem, however. You do have some options:

Use the coverage tool in Chrome DevTools to find unused code in your website's resources. By reducing the size of the resources you need during startup, you can ensure your website spends less time parsing and compiling code, which leads to a smoother initial user experience.
Sometimes the unused code you find using the coverage tool is marked "unused" because it wasn't executed during startup, but is still necessary for some functionality in the future. This is code that you can move to a separate bundle via code splitting.
If you're using a tag manager, be sure to periodically check your tags to make sure they are optimized, or even if they're still being used. Older tags with unused code can be cleared out to make your tag manager's JavaScript smaller and more efficient.

Avoid large rendering updates #

JavaScript isn't the only thing that can affect your website's responsiveness. Rendering can be a type of expensive work in its own right—and when large rendering updates happen, they can interfere with your website's ability to respond to user inputs.

Optimizing rendering work isn't a straightforward process, and it often depends on what you're trying to achieve. Even so, there are some things you can do to ensure that your rendering updates are reasonable, and don't sprawl into long tasks:

Avoid using requestAnimationFrame() for doing any non-visual work. requestAnimationFrame() calls are handled during the rendering phase of the event loop, and when too much work is done during this step, rendering updates can be delayed. It's essential that any work you're doing with requestAnimationFrame() is reserved strictly for tasks that involve rendering updates.
Keep your DOM size small. DOM size and the intensity of layout work are correlated. When the renderer has to update the layout for a very large DOM, the work required to recalculate its layout can increase significantly.
Use CSS containment. CSS containment relies on the CSS contain property, which gives instructions to the browser about how to do layout work for the container the contain property is set on, including even isolating the scope of layout and rendering to a specific root in the DOM. It's not always an easy process, but by isolating areas containing complex layouts, you can avoid doing layout and rendering work for them that isn't necessary.

Conclusion #

Improving page performance can seem like a daunting task, especially given that there is a mountain of guidance across the web to consider. By focusing on these recommendations, however, you can approach the problem with focus and purpose, and hopefully move the needle for your website's Core Web Vitals.

While the recommendations listed here are by no means exhaustive, we do believe—based on careful analysis of the state of the web—that these recommendations are the most effective ways that sites can improve their Core Web Vitals performance in 2023.

If you'd like to go beyond the recommendations listed here, check out these optimization guides for more information:

Here's to a new year, and a faster web for all! May your sites be fast for your users in all the ways that matter most.

Photo by Devin Avery

Optimize Interaction to Next Paint

2022-12-08T00:00:00Z

Interaction to Next Paint (INP) is a pending Core Web Vital metric that assesses a page's overall responsiveness to user interactions by observing the latency of all qualifying interactions that occur throughout the lifespan of a user's visit to a page. The final INP value is the longest interaction observed (sometimes ignoring outliers).

To provide a good user experience, websites should strive to have an Interaction to Next Paint of 200 milliseconds or less. To ensure you're hitting this target for most of your users, a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.

Depending on the website, there may be few to no interactions—such as pages of mostly text and images with few to no interactive elements. Or, in the case of websites such as text editors or games, there could be hundreds—even thousands—of interactions. In either case, where there's a high INP, the user experience is at risk.

It takes time and effort to improve INP, but the reward is a better user experience. In this guide, a path to improving INP will be explored.

Figure out what's causing poor INP #

Before you can fix slow interactions, you'll need data to tell you if your website's INP is poor or needs improvement. Once you have that information, you can move into the lab to begin diagnosing slow interactions, and work your way toward a solution.

Find slow interactions in the field #

Ideally, your journey in optimizing INP will start with field data. At its best, field data from a Real User Monitoring (RUM) provider will give you not only a page's INP value, but also contextual data that highlights what specific interaction was responsible for the INP value itself, whether the interaction occurred during or after page load, the type of interaction (click, keypress, or tap), and other valuable information.

If you're not relying on a RUM provider to get field data, the INP field data guide advises using the Chrome User Experience Report (CrUX) via PageSpeed Insights to help fill in the gaps. CrUX is the official dataset of the Core Web Vitals program and provides a high-level summary of metrics for millions of websites, including INP. However, CrUX often does not provide the contextual data you'd get from a RUM provider to help you to analyze issues. Because of this, we still recommend that sites use a RUM provider when possible, or implement their own RUM solution to supplement what is available in CrUX.

Diagnose slow interactions in the lab #

Ideally, you'll want to start testing in the lab once you have field data that suggests you have slow interactions. In the absence of field data, there are some strategies for identifying slow interactions in the lab. Such strategies include following common user flows and testing interactions along the way, as well as interacting with the page during load—when the main thread is often busiest—in order to surface slow interactions during that crucial part of the user experience.

Optimize interactions #

Once you've identified a slow interaction and can reproduce it in the lab, the next step is to optimize it. Interactions can be broken down into three phases:

The input delay, which starts when the user initiates an interaction with the page, and ends when the event callbacks for the interaction begin to run.
The processing time, which consists of the time it takes for event callbacks to run to completion.
The presentation delay, which is the time it takes for the browser to present the next frame which contains the visual result of the interaction.

The sum of these three phases is the total interaction latency. Every single phase of an interaction contributes some amount of time to total interaction latency, so it's important to know how you can optimize each part of the interaction so it runs for as little time as possible.

Identify and reduce input delay #

When a user interacts with a page, the first part of that interaction is the input delay. Depending on other activity on the page, input delays can be considerable in length. This could be due to activity occurring on the main thread (perhaps due to scripts loading, parsing and compiling), fetch handling, timer functions, or even from other interactions that occur in quick succession and overlap with one another.

Whatever the source of an interaction's input delay, you'll want to reduce input delay to a minimum so that interactions can begin running event callbacks as soon as possible.

The relationship between script evaluation and long tasks during startup #

A critical aspect of interactivity in the page lifecycle is during startup. As a page loads, it will initially render, but it's important to remember that just because a page has rendered, doesn't mean that the page is finished loading. Depending on how many resources a page requires to become fully functional, it's possible that users may attempt to interact with the page while it's still loading.

One thing that can extend an interaction's input delay while a page loads is script evaluation. After a JavaScript file has been fetched from the network, the browser still has work to do before that JavaScript can run; that work includes parsing a script to ensure its syntax is valid, compiling it into bytecode, and then finally executing it.

Depending on the size of a script, this work can introduce long tasks on the main thread, which will delay the browser from responding to other user interactions. To keep your page responsive to user input during page load, it's important to understand what you can do to reduce the likelihood of long tasks during page load so the page stays snappy.

Optimize event callbacks #

The input delay is only the first part of what INP measures. You'll also need to make sure that the event callbacks that run in response to a user interaction can complete as quickly as possible.

Yield to the main thread often #

The best general advice in optimizing event callbacks is to do as little work as possible in them. However, your interaction logic may be complex, and you may only be able to marginally reduce the work they do.

If you find this is the case for your website, the next thing you can try is to break up the work in event callbacks into separate tasks. This prevents the collective work from becoming a long task that blocks the main thread, which allows other interactions that otherwise would be waiting on the main thread to run sooner.

setTimeout is one way to break up tasks, because the callback passed to it runs in a new task. You can use setTimeout by itself or abstract its use into a separate function for more ergonomic yielding.

Yielding indiscriminately is better than not yielding at all—however, there is a more nuanced way of yielding to the main thread, and that involves only yielding immediately after an event callback that updates the user interface so rendering logic can run sooner.

Yield to allow rendering work to occur sooner #

A more advanced yielding technique involves structuring the code in your event callbacks to limit what gets run to just the logic required to apply visual updates for the next frame. Everything else can be deferred to a subsequent task. This not only keeps callbacks light and nimble, but it also improves rendering time for interactions by not allowing visual updates to block on event callback code.

For example, imagine a rich text editor that formats text as you type, but also updates other aspects of the UI in response to what you've written (such as word count, highlighting spelling mistakes, and other important visual feedback). In addition, the application may also need to save what you've written so that if you leave and return, you haven't lost any work.

In this example, the following four things need to happen in response to characters typed by the user. However, only the first item needs to be done before the next frame is presented.

Update the text box with what the user typed and apply any required formatting.
Update the part of the UI that displays the current word count.
Run logic to check for spelling mistakes.
Save the most recent changes (either locally or to a remote database).

The code to do this might look something like the following:

textBox.addEventListener('input', (inputEvent) => {
  // Update the UI immediately, so the changes the user made
  // are visible as soon as the next frame is presented.
  updateTextBox(inputEvent);

  // Use `setTimeout` to defer all other work until at least the next
  // frame by queuing a task in a `requestAnimationFrame()` callback.
  requestAnimationFrame(() => {
    setTimeout(() => {
      const text = textBox.textContent;
      updateWordCount(text);
      checkSpelling(text);
      saveChanges(text);
    }, 0);
  });
});

The following visualization shows how deferring any non-critical updates until after the next frame can reduce the processing time and thus the overall interaction latency.

Click the above figure to see a high-resolution version.

While the use of setTimeout() inside a requestAnimationFrame() call in the previous code example is admittedly a bit esoteric, it is an effective method that works in all browsers to ensure that the non-critical code does not block the next frame.

Avoid layout thrashing #

Layout thrashing—sometimes called forced synchronous layout—is a rendering performance problem where layout occurs synchronously. It occurs when you update styles in JavaScript, and then read them in the same task—and there are many properties in JavaScript that can cause layout thrashing.

An example of layout thrashing, as shown in the performance panel of Chrome DevTools. Rendering tasks that involve layout thrashing will be noted with a red triangle at the upper right corner of the portion of the call stack, often labeled Recalculate Style or Layout.

Layout thrashing is a performance bottleneck because by updating styles and then immediately requesting the values of those styles in JavaScript, the browser is forced to do synchronous layout work it otherwise could have waited to perform asynchronously later on after event callbacks have finished running.

Minimize presentation delay #

The presentation delay of an interaction marks spans from when an interaction's event callbacks have finished running, up to the point at which the browser is able to paint the next frame that shows the resulting visual changes.

Minimize DOM size #

When a page's DOM is small, rendering work usually finishes quickly. However, when DOMs get very large, rendering work tends to scale with increasing DOM size. The relationship between rendering work and DOM size isn't a linear one, but large DOMs do require more work to render than small DOMs. A large DOM is problematic in two cases:

During the initial page render, where a large DOM requires a lot of work to render the page's initial state.
In response to a user interaction, where a large DOM can cause rendering updates to be very expensive, and therefore increase the time it takes for the browser to present the next frame.

Bear in mind that there are instances in which large DOMs can't be significantly reduced. While there are approaches you can take to reduce DOM size, such as flattening your DOM or add to the DOM during user interactions to keep your initial DOM size small, those techniques may only go so far.

Use `content-visibility` to lazily render off-screen elements #

One way you can limit the amount of both rendering work during page load and rendering work in response to user interactions is to lean on the CSS content-visibility property, which effectively amounts to lazily rendering elements as they approach the viewport. While content-visibility can take some practice to use effectively, it's worth investigating if the result is lower rendering time that can improve your page's INP.

Be aware of performance costs when rendering HTML using JavaScript #

Where there's HTML, there's HTML parsing, and after the browser has finished parsing HTML into a DOM, it must apply styles to it, perform layout calculations, and subsequently render that layout. This is an unavoidable cost, but how you go about rendering HTML matters.

When the server sends HTML, it arrives in the browser as a stream. Streaming means that the HTML response from the server is arriving in chunks. The browser optimizes how it handles a stream by incrementally parsing chunks of that stream as they arrive, and rendering them bit by bit. This is a performance optimization in that the browser implicitly yields periodically and automatically during page load, and you get that for free.

While the first visit to any website will always involve some amount of HTML, a common approach starts with a minimal initial bit of HTML, and then JavaScript is used to populate the content area. Subsequent updates to that content area also occur as the result of user interactions. This is usually called the single-page application (SPA) model. One drawback of this pattern is that, by rendering HTML with JavaScript on the client, you not only get the cost of the JavaScript processing to create that HTML, but also the browser will not yield until it has finished parsing that HTML, and rendering it.

It's vital to remember though, that even websites that aren't SPAs will probably involve some amount of HTML rendering through JavaScript as the result of interactions. This is generally fine, so long as you're not rendering large amounts of HTML on the client, which can delay presentation of the next frame. However, it's important to understand the performance implications of this approach to rendering HTML in the browser, and how it can impact the responsiveness of your website to user input if you are rendering a lot of HTML via JavaScript.

Conclusion #

Improving your site's INP is an iterative process. When you fix a slow interaction in the field, the chances are good that—especially if your website provides lots of interactivity—you'll start to find other slow interactions, and you'll need to optimize them too.

The key to improving INP is persistence. In time, you can get your page's responsiveness to a place where users are happy with the experience you're providing them. The chances are also good that as you develop new features for your users, you may need to go through the same process in optimizing interactions specific to them. It will take time and effort, but it's time and effort well spent.

Hero image from Unsplash, by David Pisnoy and modified in accordance with the Unsplash license.

How SPA architectures affect Core Web Vitals

2021-09-14T00:00:00Z

Since first introducing the Web Vitals initiative in May of 2020, we on the Chrome team have received a lot of great questions and feedback about the program.

Perhaps the topic we've received the most questions about, which is also probably the hardest question to answer, is how to measure Core Web Vitals in a single-page application (SPA), as well as how SPA architectures affect Core Web Vitals scores.

These questions are hard to answer because the problem is quite nuanced, so in this post we're going to do our best to answer the most common questions, providing as much detail and context as we can.

Before getting into specifics, though, it's important to state that Google does not have any preference as to what architecture or technology is used to build a site. We believe that SPAs and multi-page applications (MPAs) are both capable of delivering high quality experiences to users, and our intention with the Web Vitals initiative is to provide metrics that measure the experience independent of the technology. While this is not possible in every case today (due to limitations in the web platform), we are actively working on closing those gaps.

Frequently asked questions #

Do Core Web Vitals metrics include SPA route transitions? #

No. Each of the Core Web Vitals metrics is measured relative to the current, top-level page navigation. If a page dynamically loads new content and updates the URL of the page in the address bar, it will have no effect on how the Core Web Vitals metrics are measured. Metric values are not reset, and the URL associated with each metric measurement is the URL the user navigated to that initiated the page load.

Can the Core Web Vitals metrics treat SPA route changes the same as traditional page loads? #

Unfortunately, no. Not yet anyway.

There is no standardized way of building an SPA today, and even among the popular SPA and routing libraries, the user experience can be quite different from app to app:

Some SPAs update the URL only when loading new "full page" content, whereas other sites update the URL for tiny content changes or even just UI state changes.
Some SPAs update the URL using the History API, whereas others use hash changes in order to support older browsers (and others do not update the URL at all).
Some SPAs load content and then update the URL, whereas others update the URL before loading content.
Some SPAs load content all at once, synchronously, in a single JavaScript task, whereas others transition content in, asynchronously, across multiple tasks (with no clear transition end event).
Some SPAs always load content from the network, whereas others preload all content upfront so that route changes load instantly from memory.

These differences make defining and identifying what constitutes an SPA route change, or even an SPA itself, very difficult to do at scale.

In some cases an SPA route change is logically identical to an MPA page load, and in such cases it would be great if the existing Core Web Vitals metrics could be applied.

However, without solid heuristics to reliably identify "real" route changes from all other URL changes—as well as clear signals marking the beginning and end of such transitions—reporting Core Web Vitals metrics in these cases would muddy the data and make it less useful or representative of the real user experience on the site.

Is it harder for SPAs to do well on Core Web Vitals than MPAs? #

There is nothing inherent in the SPA architecture that would prevent a page in an SPA from loading just as quickly—and scoring just as well on all of the Core Web Vitals metrics—as a similar page in an MPA.

However, properly optimized MPAs do have some advantages in meeting the Core Web Vitals thresholds that SPAs currently do not. The reason is because with the MPA architecture, each "page" is loaded as a full-page navigation (rather than dynamically fetching content and inserting it into the existing page), which means users who visit an MPA are more likely to load more than one page from the site, which in turn means that a larger percentage of the distribution of all page loads for an MPA will involve some or all of the sub-resources being cached.

Granted, for an MPA to perform better on the Core Web Vitals metrics than an SPA requires a few things to be true:

The MPA needs to have optimized sub-resource caching in order to ensure same-origin page loads are indeed faster than cross-origin page loads at the 75th percentile.
Users who visit MPAs need to visit multiple pages in order for the site to receive the caching benefits that result in faster page loads.

Since Core Web Vitals assessments consider the 75th percentile of page visits, having more, well-performing page visits in the dataset will increase the likelihood that the visit at the 75th percentile of the distribution will be within the recommended thresholds.

Note that an important thing to consider when comparing Core Web Vitals scores is how the data is aggregated—that is, whether the dataset in the distribution includes all pages from your site or origin, or just page loads for a particular page URL.

When aggregating the scores of all pages in an origin, individual fast pages can improve the 75th percentile for the origin as a whole. However, when aggregating by individual pages, the scores of one page will not affect the scores of the next. In other words, when aggregating the scores of an MPA by page, fast cache loads seen on the checkout page will not improve the scores of slow initial loads experienced on the site's landing page.

You can check your site's score for different aggregation methods using PageSpeed Insights or the Chrome User Experience Report API, which reports scores for both individual page URLs and the entire origin.

Another way the SPA architecture can affect Core Web Vitals scores is for metrics that consider the full lifespan of a page. Since users visiting SPAs tend to stay on the same "page" for the entire session, metrics that accumulate over time can be harsher on SPAs than MPAs.

In April 2021, we announced changes to the CLS metric that partially addressed this problem. Previously CLS would accumulate over the entire page lifespan, whereas now it only accumulates over a specific window of time—essentially the worst burst of layout shifts on a given page.

However, even with the new CLS definition, SPAs are still at a disadvantage because the CLS value doesn't "reset" after a route transitions like it does with full page loads in an MPA. This can also lead to confusion because layout shifts that occur after a route transition will be attributed to the URL of the page when it was loaded, not the URL in the address bar at the time of the shift (more details below).

If SPA architectures improve the user experience, shouldn't that improvement be reflected in the metrics? #

Yes, it should. Though as mentioned previously, quantifying just how much the experience has improved is difficult to do at scale, given all the different ways SPAs are implemented on the web today.

The truth is the web performance industry (Google included) has historically not invested nearly as much time and effort into developing user-centric metrics for the post-load performance of a page as it has for the page load itself. This isn't because post-load performance isn't important, it's because post-load UX and interactions are so much more varied and less well-defined—making it hard to design metrics for them.

But even if we did have well defined post-load metrics to measure SPA performance, we wouldn't want to ignore the load experience just because the post load experience got better.

One of the goals of the Web Vitals initiative is to promote and incentivize good user experiences across as many aspects of loading and using a web page as possible. We don't want to encourage scenarios where bad experiences are justified if you can have enough good experiences to make up for them. Users want pages to load fast and transition to new content fast, and we've tried to design metrics that favor those types of experiences.

So while it's true that an MPA version of a site may fare better on the Core Web Vitals metrics at the 75th percentile than an SPA version of the exact same site, the SPA version should still strive to meet the "good" threshold. If the SPA version doesn't meet the "good" threshold for most users, then the initial load experience is probably still not perceived as good—even if the subsequent, in-page navigation experience is excellent.

In the future we plan to develop metrics that encourage great, post-load experiences, and we believe this is the best path to incentivize high-quality SPAs in a way that doesn't compromise the initial load experience. We have already delivered a new metric named Interaction to Next Paint (INP) that measures interaction latency throughout the entire page lifecycle, and we're actively working on other post-load metrics as well, including metrics that measure SPA route transitions (see below).

We switched our site from an MPA to an SPA and our scores regressed. Is that expected? #

It depends. There are a number of reasons why your scores could change after a major architecture migration, but a decrease in the number of warm cache loads could account for some of the change.

A quick way to check would be to test both an MPA and SPA version of one of your landing pages with Lighthouse. If the Lighthouse score is lower on any of the Core Web Vitals metric for the SPA version, then it's likely that the load experience did get worse after the update.

Should I switch my site from an SPA to an MPA to score better on Core Web Vitals? #

Probably not. You should only switch from an SPA to an MPA if you are not happy with your SPA stack and you have reason to believe an MPA will provide a better user experience.

Over time, as the Core Web Vitals metrics improve and cover more of the full browsing experience, teams with well-built SPAs that provide great UX should expect to see their Core Web Vitals scores reflect that.

If Core Web Vitals scores are only reported for an SPA's landing pages, how can I debug issues that occur on "pages" after a route transition? #

Google tools that report field data for the Core Web Vitals metric (like Search Console and PageSpeed Insights) get their data from the Chrome User Experience Report (CrUX). And CrUX aggregates data either by origin or by page URL (that is, the page URL at load time).

For all the reasons already listed above, CrUX is not able to aggregate data by SPA route. However, as a site owner who is familiar with your own architecture, it is possible to measure this yourself, and many analytics tools allow you to signal when an SPA route change is occurring and they update your measurement data accordingly.

When measuring Web Vitals metrics with an analytics tool, make sure you're measuring both the current route URL as well as the original page URL. This will allow you to both debug individual issues that occur throughout the page lifecycle as well as aggregate by original page URL in order to match how Google tools measure and report on the metrics.

For more details and best practices on this topic, see: Debug performance in the field.

What is Google doing to ensure MPAs do not have an unfair advantage compared to SPAs? #

As mentioned above, a properly-optimized MPA can, in some cases, report better Web Vitals scores at the 75th percentile due to the fact that it will likely have a higher percentage of cached page visits. Conversely, real improvements to the user experience in properly-optimized SPAs are not currently being captured by any of the Core Web Vitals metrics.

At Google, we recognize that this creates incentives that do not fully align with the goals of the Web Vitals initiative, and we are actively looking at ways to fix this. Currently, we're exploring two potential solutions, one short term and one longer term:

Assess cross-origin and same-origin page visits separately.
Design new APIs that enable better SPA measurement.

Assess cross-origin and same-origin page visits separately #

Today the Core Web Vitals metrics aggregate all page visits into a single bucket—they do not differentiate between new versus returning visits or landing pages versus checkout pages or any other aggregation type where cache state could have an effect on performance.

One way to normalize the differences between SPA and MPA performance would be to apply different weighting to different types of visits, potentially even with completely different threshold recommendations.

While we definitely do want to reward effective cache implementations, we don't want fast intra-site navigations to be able to cover up for slow landing page loads. We also don't want to incentivize sites to break up long pages into a collection of shorter pages just for the sake of improving metric scores.

By separately assessing cross-origin and same-origin page visits we can help ensure that both types of experiences are important without letting the relative popularity of one type on a given site skew the distribution of any particular metric.

Design new APIs that enable better SPA measurement #

Another solution that is actively being worked on (in parallel to the above) is a new App History API, which would help standardize current SPA patterns and make it easier to measure and understand SPA usage at scale.

The App History API introduces a new navigate event, which has two key features specific to SPA measurement:

A userInitiated flag, which will only be set to true if the navigation was initiated via a link click, form submission, or the browser's back or forward UI.
A transitionWhile() method, which takes a promise allowing the developer to signal when the work they've initiated to perform the navigation is complete.

The userInitiated flag can be used to determine a semantic starting point for an SPA route transition, indicating clear user intent. The transitionWhile() promise resolving can help the browser correlate paints with the specific route transition, such that it may be able to determine the largest contentful paint related to that transition.

Building on top of the idea presented in the previous section, it might even be possible to aggregate SPA route transition time into the same bucket as same-origin page loads in an MPA. This is exciting because it would allow a site migrating from an MPA to an SPA to actually compare the performance before and after.

Of course, more research is needed before we'll know whether we can accurately make these determinations. If you have suggestions or feedback on these proposals, please email web-vitals-feedback@googlegroups.com.

Final thoughts #

Google is deeply committed to improving the Web Vitals metrics, and ensuring they measure and incentivize high-quality experiences that are important to users. That being said, we do acknowledge that measurement gaps exist today. The metrics do not currently cover every aspect of user experience, but we are actively working to close these gaps.

Despite the current limitations, we believe the areas the existing metrics do capture are critical to the health and success of the web, and to the extent that sites (regardless of architecture) do not meet the recommended thresholds, we believe there is room for improvement.

I hope this post has helped shed some light on this complex and nuanced subject. As always, if you have feedback on the current or future Web Vitals metrics, please email web-vitals-feedback@googlegroups.com.

Why lab and field data can be different (and what to do about it)

2021-08-17T00:00:00Z

Google provides a number of tools to help site owners monitor their Core Web Vitals scores. These tools fall into two main categories:

Tools that report lab data—data collected in a controlled environment with predefined device and network settings.
Tools that report field data—data collected from the real users visiting your site.

The problem is that sometimes the data reported by lab tools can be quite a bit different from the data reported by field tools! Your lab data might indicate that your site performs great, but your field data suggests it needs improvement. Alternatively, your field data may say all your pages are good, but your lab data may report a very low score.

The following real example of a PageSpeed Insights report from web.dev shows that in some cases lab and field data can be different across all of the Core Web Vitals metrics:

Differences between tools is an understandable source of confusion for developers. This post explains the main reasons these differences could exist—with specific examples covering each of the Core Web Vitals metrics—and what to do when you find differences on your pages.

Lab data versus field data #

To understand why lab and field tools might report different values—even for the exact same web page—you need to understand the difference between lab and field data.

Lab data #

Lab data is determined by loading a web page in a controlled environment with a predefined set of network and device conditions. These conditions are known as a lab environment, sometimes also referred to as a synthetic environment.

Chrome tools that report lab data are generally running Lighthouse.

The purpose of a lab test is to control for as many factors as you can, so the results are (as much as possible) consistent and reproducible from run to run.

Field data #

Field data is determined by monitoring all users who visit a page and measuring a given set of performance metrics for each one of those users' individual experiences. Because field data is based on real-user visits, it reflects the actual devices, network conditions, and geographic locations of your users.

Field data is also commonly known as Real User Monitoring (RUM) data; the two terms are interchangeable.

Chrome tools that report field data generally get that data from the Chrome User Experience Report (CrUX). It's also common (and recommended) for site owners to collect field data themselves because it can provide more actionable insights than just using CrUX alone.

The most important thing to understand about field data is that it is not just one number, it's a distribution of numbers. That is, for some people who visit your site, it may load very quickly, while for others it may load very slowly. The field data for your site is the complete set of all performance data collected from your users.

As an example, CrUX reports show a distribution of performance metrics from real Chrome users over a 28-day period. If you look at almost any CrUX report you can see that some users who visit a site might have a very good experience while others might have a very poor experience.

If a tool does report a single number for a given metric, it will generally represent a specific point in the distribution. Tools that report Core Web Vitals field scores do so using the 75th percentile.

Looking at LCP from the field data in the screenshot above, you can see a distribution where:

88% of visits saw an LCP of 2.5 seconds or less (good).
8% of visits saw an LCP between 2.5 and 4 seconds (needs improvement).
4% of visits saw an LCP greater than 4 seconds (poor).

At the 75th percentile, LCP was 1.8 seconds:

Lab data from the same page shows an LCP value of 3.0 second. While this value is greater than the 1.8 seconds shown in the field data, it's still a valid LCP value for this page—it's one of many values that make up the full distribution of load experiences.

Why lab and field data are different #

As the above section explains, lab data and field data actually measure very different things.

Field data includes a wide variety of network and device conditions as well as a myriad of different types of user behavior. It also includes any other factors that affect the user experience, such as browser optimizations like the back/forward cache (bfcache), or platform optimizations like the AMP cache.

By contrast, lab data intentionally limits the number of variables involved. A lab test consists of:

A single device…
connected to a single network…
run from a single geographic location.

The particulars of any given lab test may or may not accurately represent the 75th percentile of field data for a given page or site.

The controlled environment of the lab is useful when debugging issues or testing features before deploying to production, but when you control for these factors you are explicitly not representing the variance that you see in the real world across all types of networks, device capabilities, or geographic locations. You are also generally not capturing the performance impact of real-user behavior, such as scrolling, selecting text, or tapping elements on the page.

In addition to the possible disconnect between lab conditions and the conditions of most real-world users, there are also a number of more subtle differences that are important to understand in order to make the most sense out of your lab and field data, as well as any differences you may find.

The next few sections go into detail highlighting the most common reasons there could be differences between lab data and field data for each of the Core Web Vitals metrics:

LCP #

Different LCP elements #

The LCP element identified in a lab test may not be the same LCP element users see when visiting your page.

If you run a Lighthouse report for a given page, it's going to return the same LCP element every single time. But if you look at field data for the same page, you'll usually find a variety of different LCP elements, which depend on a number of circumstances specific to each page visit.

For example, the following factors could all contribute to a different LCP element being determined for the same page:

Different device screen sizes result in different elements being visible within the viewport.
If the user is logged in, or if personalized content is being shown in some way, the LCP element could be very different from user to user.
Similar to the previous point, if an A/B test is running on the page it could result in very different elements being displayed.
The set of fonts installed on the user's system can affect the size of text on the page (and thus which element is the LCP element).
Lab tests are usually run on a page's "base" URL—without any query parameters or hash fragments added. But in the real world, users often share URLs containing a fragment identifier or text fragment, so the LCP element may actually be from the middle or bottom of the page (rather than "above the fold").

Since LCP in the field is calculated as the 75th percentile of all user visits to a page, if a large percentage of those users had an LCP element that loaded very quickly—for example a paragraph of text rendered with a system font—then even if some of those users had a large, slow-loading image as their LCP element, it might not affect that page's score if that happens to less than 25% of visitors.

Alternatively, the opposite could be true. A lab test might identify a block of text as the LCP element because it's emulating a Moto G4 phone which has a relatively small viewport and your page's hero image is initially rendered off-screen. Your field data, though, may include mostly Pixel XL users with larger screens, so for them the slow-loading hero image is their LCP element.

Effects of cache state on LCP #

Lab tests typically load a page with a cold cache, but when real users visit that page they may already have some of its resources cached.

The first time a user loads a page it may load slowly, but if the page has proper caching configured, the next time that user returns the page might load right away.

While some lab tools do support multiple runs of the same page (to simulate the experience for returning visitors), it's not possible for a lab tool to know what percentage of real-world visits occur from new versus returning users.

Sites with well-optimized cache configurations and lots of repeat visitors may discover that their real-world LCP is much faster than their lab data indicates.

AMP or Signed Exchange optimizations #

Sites built with AMP or that use Signed Exchanges (SXG) can be preloaded by content aggregators like Google Search. This can result in significantly better load performance for users visiting your pages from those platforms.

In addition to cross-origin preloading, sites themselves can preload content for subsequent pages on their site, which could improve LCP for those pages as well.

Lab tools do not simulate the gains seen from these optimizations, and even if they did, they could not know what percentage of your traffic comes from platforms like Google Search compared to other sources.

Effects of bfcache on LCP #

When pages are restored from the bfcache, the load experience is near instantaneous, and these experiences are included in your field data.

Lab tests do not consider bfcache, so if your pages are bfcache-friendly, it will likely result in faster LCP scores reported in the field.

Effects of user interaction on LCP #

LCP identifies the render time of the largest image or text block in the viewport, but that largest element can change as the page is loaded or if new content gets dynamically added to the viewport.

In the lab, the browser will wait until the page is fully loaded before determining what the LCP element was. But in the field, the browser will stop monitoring for larger elements after the user scrolls or interacts with the page.

This makes sense (and is necessary) because users typically will wait to interact with a page until it "appears" loaded, which is exactly what the LCP metric aims to detect. It also wouldn't make sense to consider elements added to the viewport after a user interacts because those elements might have only been loaded because of something the user did.

The implication of this, though, is that field data for a page may report faster LCP times, depending on how users behave on that page.

FID #

FID requires real-user interaction #

The FID metric measures how responsive a page is to user interactions, at the time when users actually chose to interact with it.

The second part of that sentence is critical because lab tests, even those that support script user behavior, cannot accurately predict when users will choose to interact with a page, and thus cannot accurately measure FID.

TBT and TTI do not consider user behavior #

Lab metrics such as Total Blocking Time (TBT) and Time to Interactive (TTI) are intended to help diagnose issues with FID because they quantify how much the main thread is blocked during page load.

The idea is that pages with lots of synchronous JavaScript or other intensive rendering tasks are more likely to have a blocked main thread when the user first interacts. However, if users wait to interact with the page until after the JavaScript finishes executing, FID may be very low.

When users will choose to interact with a page depends largely on whether or not it looks interactive, and this cannot be measured with TBT or TTI.

TBT and TTI do not consider tap delay #

If a site is not optimized for mobile viewing, browsers will add a 300 ms delay after any tap before running event handlers. They do this because they need to determine whether the user is trying to double-tap to zoom before they can fire mouse or click events.

This delay counts toward a page's FID because it contributes to the real input latency that users experience. But since this delay is not technically a Long Task, it doesn't affect a page's TBT or TTI. This means a page may have poor FID despite having very good TBT and TTI scores.

Effects of cache state and bfcache on FID #

In the same way that proper caching can improve LCP in the field, it can also improve FID.

In the real world, a user might have the JavaScript for a site already in their cache, so processing it could take less time and result in smaller delays.

The same is also true for pages restored from bfcache. In those cases the JavaScript is restored from memory, so there could be little or no processing time at all.

CLS #

Effects of user interaction on CLS #

CLS measured in the lab only considers layout shifts that occur above the fold and during load, but this is only a subset of what CLS actually measures.

In the field, CLS considers all unexpected layout shifts that occur throughout the lifespan of the page, including content that shifts as the user scrolls or in response to slow network requests after user interaction.

For example, it's quite common for pages to lazy-load images or iframes without dimensions, and that can cause layout shifts when a user scrolls to those sections of the page. But those shifts may only happen if the user scrolls down, which often won't be caught in a lab test.

Personalized content #

Personalized content—including targeted ads and A/B tests—affects what elements are loaded on a page. It also affects how they are loaded since personalized content is often loaded later and inserted into a page's main content, causing layout shifts.

In the lab, a page is usually loaded either without personalized content, or with content for a generic "test user", which may or may not trigger the shifts real users are seeing.

Since field data includes the experiences of all users, the amount (and degree) of layout shifts experienced on any given page is very dependent on what content is loaded.

Effects of cache state and bfcache on CLS #

Two of the most common causes of layout shifts during load are images and iframes without dimensions (as mentioned above) and slow loading web fonts, and both of these issues are more likely to affect the experience the first time a user visits a site, when their cache is empty.

If a page's resources are cached, or if the page itself is restored from bfcache, the browser can usually render images and fonts right away, without waiting for them to download. This can result in lower CLS values in the field than what a lab tool may report.

What to do when the results are different #

As a general rule, if you have both field data and lab data for a given page, field data is what you should use to prioritize your efforts. Since field data represents what real users are experiencing, it's the most accurate way to really understand what your users are struggling with and what needs to be improved.

On the flip side, if your field data shows good scores across the board, but your lab data suggests there's still room for improvement, it's worth understanding what further optimizations can be made.

In addition, while field data does capture real-user experiences, it only does so for users who are successfully able to load your site. Lab data can sometimes help identify opportunities to expand your site's reach and make it more accessible to users with slower networks or lower-end devices.

Overall, both lab data and field data are important parts of effective performance measurement. They both have their strengths and limitations, and if you're only using one you may be missing an opportunity to improve the experience for your users.

Measure and debug performance with Google Analytics 4 and BigQuery

2021-05-18T00:00:00Z

Google provides a number of tools—Search Console, PageSpeed Insights (PSI), and the Chrome User Experience Report (CrUX)—that let developers see how their sites perform against the Core Web Vitals metrics for their real users in the field.

These tools are great in that they give you a high-level view of your site's real-user performance, and they require absolutely no setup to start using.

However, there are a few critical reasons why you don't want to rely on these tools alone to measure your site's performance:

CrUX-based tools report data by either monthly or previous 28-day periods. This means you'll have to wait a long time after making any changes before you can see the results.
CrUX-based tools can only be segment by a limited number of dimensions, such as country, connection type, and device category (desktop or mobile). You can't slice the data by dimensions specific to your business (for example: engaged users, users in a particular experiment group, etc.).
CrUX-based tools can tell you what your performance is, but they can't tell you why. With analytics tools you can send additional data to help you track down and debug issues.

For these reasons, we recommend all site owners monitor Core Web Vitals metrics using their existing analytics tool. This post explains how you can use free tools offered by Google to do just that.

Once you have everything set up, you'll be able to create dashboards like these:

And If you want a visual overview of all the steps outlined here, check out our talk from Google I/O '21:

Measure #

Measuring performance has always been possible with Google Analytics using custom metrics, but there are a few new features in Google Analytics 4 (GA4) that developers in particular should be excited about.

Zero-config, custom event parameters
Free BigQuery export, so you can query your data using SQL

While the Google Analytics web interface does have powerful analysis tools, it's hard to beat the power and flexibility of raw event data access using a query language you likely already know.

To get started measuring Core Web Vitals using Google Analytics 4 and BigQuery, you need to do three things:

Create a Google Analytics 4 property and a BigQuery project.
Enable BigQuery export in your Google Analytics property config, so all data you receive will be automatically populated in your BigQuery project tables.
Add the web-vitals JavaScript library to your site, so you can measure the Core Web Vitals metrics and send the data to Google Analytics 4.

Analyze #

Once you're all set up, you should see event data populating in the BigQuery interface, and you should be able to query the data like this:

SELECT * FROM `my_project_id.analytics_XXXXX.events_*`
WHERE event_name IN ('LCP', 'FID', 'CLS')

Here's a preview of the results from that query:

Query Web Vitals data #

Before you start querying your Web Vitals event data, it's important to understand how the data is aggregated.

The most important thing to understand is that, in some cases, multiple events may be received for the same metric, on the same page. This can happen if the metric value changes and an updated value is reported (a common occurrence with CLS).

For Web Vitals events, the last value sent is always the most accurate one, so before performing any analysis, it's important to filter for just those values. The code snippet provided by the web-vitals JavaScript library to send data to Google Analytics 4 includes sending a unique ID per metric, so you can use the following query to limit your results to just the last-received value for each metric ID:

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)

Note that all other queries referenced in this post will start with this subquery.

The next few sections show a few examples of common Web Vitals queries you might want to run.

Example queries #

LCP, FID, and CLS at the 75% percentile (p75) across the whole site #

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)
# Main query logic
SELECT
  metric_name,
  APPROX_QUANTILES(metric_value, 100)[OFFSET(75)] AS p75,
  COUNT(1) as count
FROM (
  SELECT
    metric_name,
    ROUND((SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = "metric_value"), 3) AS metric_value,
  FROM web_vitals_events
)
GROUP BY 1

All individual LCP values from highest to lowest #

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)
# Main query logic
SELECT
  ROUND((SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = "metric_value"), 3) AS metric_value,
FROM web_vitals_events
WHERE metric_name = 'LCP'
ORDER BY metric_value DESC

LCP scores (p75) of the 10 most popular pages #

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)
# Main query logic
SELECT
  page_path,
  APPROX_QUANTILES(metric_value, 100)[OFFSET(75)] AS LCP,
  COUNT(1) as count
FROM (
  SELECT
    REGEXP_SUBSTR((SELECT value.string_value FROM UNNEST(event_params) WHERE key = "page_location"), r'\.com(\/[^?]*)') AS page_path,
    ROUND((SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = "metric_value"), 3) AS metric_value,
  FROM web_vitals_events
  WHERE metric_name = 'LCP'
)
GROUP BY 1
ORDER BY count DESC
LIMIT 10

Top 10 pages with the worst CLS (p75) #

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)
# Main query logic
SELECT
  page_path,
  APPROX_QUANTILES(metric_value, 100)[OFFSET(75)] AS CLS,
  COUNT(1) as count
FROM (
  SELECT
    REGEXP_SUBSTR((SELECT value.string_value FROM UNNEST(event_params) WHERE key = "page_location"), r'\.com(\/[^?]*)') AS page_path,
    ROUND((SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = "metric_value"), 3) AS metric_value,
  FROM web_vitals_events
  WHERE metric_name = 'CLS'
)
GROUP BY 1
HAVING count > 50 # Limit to relatively popular pages
ORDER BY CLS DESC
LIMIT 10

Debug #

The above queries show how to query the Web Vitals metric data, which is helpful for understanding your current performance and how it's trending over time. But what can you do if your performance is worse than expected but you're not sure why?

Knowing what your scores are is not helpful if you're not able to take action and fix the problems.

Debug performance in the field explains how you can send additional debug information with your analytics data. If you follow the instructions detailed in that post, you should see that debug information appear in BigQuery as well.

The following queries show how to use the debug_target event parameter to help identify the root cause of performance issues.

Example queries #

Top elements contributing to CLS #

The debug_target is a CSS selector string that corresponds to the element on the page that is most relevant to the metric value.

With CLS, the debug_target represents the largest element from the largest layout shift that contributed to the CLS value. If no elements shifted then the debug_target value will be null.

The following query will list pages from worst to best by their CLS at the 75th percentile, grouped by debug_target:

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)
# Main query logic
SELECT
  page_path,
  debug_target,
  APPROX_QUANTILES(metric_value, 100)[OFFSET(75)] AS CLS,
  COUNT(1) as count
FROM (
  SELECT
    REGEXP_SUBSTR((SELECT value.string_value FROM UNNEST(event_params) WHERE key = "page_location"), r'\.com(\/[^?]*)') AS page_path,
    (SELECT value.string_value FROM UNNEST(event_params) WHERE key = "debug_target") as debug_target,
    ROUND((SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = "metric_value"), 3) AS metric_value,
    *
  FROM web_vitals_events
  WHERE metric_name = 'CLS'
)
GROUP BY 1, 2
HAVING count > 50 # Limit to relatively popular pages
ORDER BY CLS DESC

Knowing what elements on the page are shifting should make it much easier to identify and fix the root cause of the problem.

Keep in mind that the elements reported here might not be the same elements that you see shifting when you're debugging your pages locally, which is why it's so important to capture this data in the first place. It's very hard to fix things that you don't realize are problems!

Debug other metrics #

The above query shows the results for the CLS metric, but the exact same technique can be used to report on the debug targets for LCP and FID. Just replace the where clause with the relevant metric to debug:

WHERE metric_name = 'CLS'
WHERE metric_name = 'LCP'

Again, you can refer to Debug performance in the field for instructions on how to collect and send debug information for each of the Core Web Vitals metrics.

Visualize #

It can be challenging to get insights just by looking at the query results alone. For example, the following query lists daily 75th percentile values for LCP in the dataset.

# Subquery all Web Vitals events from the last 28 days
WITH web_vitals_events AS (
  SELECT event_name as metric_name, * EXCEPT(event_name, is_last_received_value) FROM (
    SELECT *, IF (ROW_NUMBER() OVER (
      PARTITION BY (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
      ORDER BY (SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value') DESC
    ) = 1, true, false) AS is_last_received_value
    FROM `bigquery_project_id.analytics_XXXXX.events_*`
    WHERE event_name in ('CLS', 'FID', 'LCP') AND
      _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 28 DAY)) AND FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY))
  ) WHERE is_last_received_value
)
# Main query logic
SELECT
  event_date,
  metric_name,
  APPROX_QUANTILES(ROUND(metric_value, 2), 100)[OFFSET(75)] AS p75
FROM
  (
    SELECT
      event_date,
      metric_name,
      ROUND((SELECT COALESCE(value.double_value, value.int_value) FROM UNNEST(event_params) WHERE key = 'metric_value'), 3) AS metric_value
    FROM web_vitals_events
    WHERE
      metric_name = 'LCP'
  )
GROUP BY
  1, 2
ORDER BY event_date

From these query results, it's difficult to identify trends or outliers just by looking at the data.

In such cases, visualizing the data can help you derive insights more quickly.

Visualize query results in Looker Studio #

BigQuery provides a quick way to visualize any query results through Data Studio. Looker Studio is a data visualization and dashboarding tool that is free to use. To visualize your query results, after running your query in the BigQuery UI, click the Explore Data button and select Explore with Looker Studio.

This will create a direct link from BigQuery into Looker Studio in the explore view. In this view, you can select the fields you want to visualize, choose chart types, setup filters, and create ad hoc charts for quick visual analysis. From the above query results, you can create this line chart to see the trend of LCP values over time:

With this direct link between BigQuery and Looker Studio, you can create quick charts from any of your queries and do visual analysis. However, if you want to do additional analysis, you might want to look at several charts in an interactive dashboard to get a more holistic view or to be able to drill down into the data. Having a handy dashboard means you don't have to write queries and generate charts manually every time you want to analyze your metrics.

You can create a dashboard in Looker Studio using the native BigQuery connector. To do so, navigate to datastudio.google.com, create a new data source, select the BigQuery connector, and choose the dataset you want to work with:

Materialize Web Vitals data #

When creating dashboards of the Web Vitals event data as described above, it's not efficient to use the Google Analytics 4 export dataset directly. Due to the structure of the GA4 data and the preprocessing required for the Web Vitals metrics, parts of your query will end up running multiple times. This creates two problems: dashboard performance and BigQuery costs.

You can use the BigQuery sandbox mode for free. With BigQuery's free usage tier, the first 1 TB of query data processed per month is free. For the analysis methods discussed in this post, unless you are using a significantly large dataset or are heavily querying the dataset regularly, you should be able to stay within this free limit every month. But if you have a high traffic website and want to regularly monitor different metrics using a fast interactive dashboard, we suggest preprocessing and materializing your web vitals data while making use of BigQuery efficiency features like partitioning, clustering, and caching.

The following script will preprocess your BigQuery data (source table) and create a materialized table (target table). When using this query for your own dataset, you might also want to define a date range for the source table to lower the amount of data processed.

# Materialize Web Vitals metrics from GA4 event export data

# Replace target table name
CREATE OR REPLACE TABLE bigquery_project_id.ga4_demo_dev.web_vitals_summary
  PARTITION BY DATE(event_timestamp)
  CLUSTER BY metric_name
AS
SELECT
  ga_session_id,
  IF(
    EXISTS(SELECT 1 FROM UNNEST(events) AS e WHERE e.event_name = 'first_visit'),
    'New user',
    'Returning user') AS user_type,
  IF(
    (SELECT MAX(session_engaged) FROM UNNEST(events)) > 0, 'Engaged', 'Not engaged')
    AS session_engagement,
  evt.* EXCEPT (session_engaged, event_name),
  event_name AS metric_name,
  FORMAT_TIMESTAMP('%Y%m%d', event_timestamp) AS event_date
FROM
  (
    SELECT
      ga_session_id,
      ARRAY_AGG(custom_event) AS events
    FROM
      (
        SELECT
          ga_session_id,
          STRUCT(
            country,
            device_category,
            device_os,
            traffic_medium,
            traffic_name,
            traffic_source,
            page_path,
            debug_target,
            event_timestamp,
            event_name,
            metric_id,
            IF(event_name = 'LCP', metric_value / 1000, metric_value) AS metric_value,
            user_pseudo_id,
            session_engaged,
            session_revenue) AS custom_event
        FROM
          (
            SELECT
              (SELECT value.int_value FROM UNNEST(event_params) WHERE key = 'ga_session_id')
                AS ga_session_id,
              (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'metric_id')
                AS metric_id,
              ANY_VALUE(device.category) AS device_category,
              ANY_VALUE(device.operating_system) AS device_os,
              ANY_VALUE(traffic_source.medium) AS traffic_medium,
              ANY_VALUE(traffic_source.name) AS traffic_name,
              ANY_VALUE(traffic_source.source) AS traffic_source,
              ANY_VALUE(
                REGEXP_SUBSTR(
                  (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'page_location'),
                  r'^[^?]+')) AS page_path,
              ANY_VALUE(
                (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'debug_target'))
                AS debug_target,
              ANY_VALUE(user_pseudo_id) AS user_pseudo_id,
              ANY_VALUE(geo.country) AS country,
              ANY_VALUE(event_name) AS event_name,
              SUM(ecommerce.purchase_revenue) AS session_revenue,
              MAX(
                (
                  SELECT
                    COALESCE(
                      value.double_value, value.int_value, CAST(value.string_value AS NUMERIC))
                  FROM UNNEST(event_params)
                  WHERE key = 'session_engaged'
                )) AS session_engaged,
              TIMESTAMP_MICROS(MAX(event_timestamp)) AS event_timestamp,
              MAX(
                (
                  SELECT COALESCE(value.double_value, value.int_value)
                  FROM UNNEST(event_params)
                  WHERE key = 'metric_value'
                )) AS metric_value,
            FROM
              # Replace source table name
              `bigquery_project_id.analytics_XXXXX.events_*`
            WHERE
              event_name IN ('LCP', 'FID', 'CLS', 'first_visit', 'purchase')
            GROUP BY
              1, 2
          )
      )
    WHERE
      ga_session_id IS NOT NULL
    GROUP BY ga_session_id
  )
CROSS JOIN UNNEST(events) AS evt
WHERE evt.event_name NOT IN ('first_visit', 'purchase');

This materialized dataset has several advantages:

The data structure is flattened and easier to query.
It retains only the Web Vitals events from the original GA4 dataset.
Session ID, user type (new vs returning), and session engagement information is directly available in columns.
The table is partitioned by date and clustered by metric name. This usually reduces the amount of data processed for each query.
Since you don't need to use wildcards to query this table, query results can get cached for upto 24 hours. This reduces costs from repeating the same query.
If you use the BigQuery BI engine, you can run optimized SQL functions and operators on this table.

You can directly query this materialized table from within BigQuery UI or use it in Looker Studio using the BigQuery connector.

Using the Web Vitals Connector #

Since making a dashboard from scratch is time consuming, we developed a packaged solution that will create a template dashboard for you. First make sure that you have materialized your Web Vitals table using the above query. Then access the Web Vitals connector for Looker Studio using this link: goo.gle/web-vitals-connector

After providing a one time authorization, you should see the following configuration screen:

Provide the materialized BigQuery table ID (i.e. the target table) and your BigQuery billing project ID. After clicking connect, Looker Studio will create a new templated dashboard and associate your data with it. You can edit, modify, and share the dashboard as you like. If you create a dashboard once, you don't have to visit the connector link again, unless you want to create multiple dashboards from different datasets.

Navigate the dashboard #

As you navigate the dashboard, you can see the daily trends of the Web Vitals metrics and some usage information for your website like users and sessions, in the Summary tab.

In the User Analysis tab, you can select a metric and then get a breakdown of the metrics percentile as well as user count by different usage and business metrics.

The Page Path Analysis tab will help you to identify problem areas on your website. Here, You can pick a metric to see the overview. But you also see the scatter-map of all the page paths with the percentile value on y axis and record count on x axis. The scatter map can help to identify pages which have lower than expected metric values. Once you select the pages either via the scatter chart of the Page path table, you can further drill down the problem area by viewing the Debug Target table.

The Revenue Analysis tab is an example of how you can monitor your business and performance metrics in the same place. This section plots all sessions where the user made a purchase. You can compare the revenue earned vs user experience during a specific session .

Advanced usage #

As you become more familiar with the dataset, you can edit the dashboard and add your own charts for richer and targeted analysis. To make the dashboard more useful, you can take the following steps:

Setup scheduled query in BigQuery to get updated data. The materialization query we ran above only takes a snapshot of your data at that moment. If you want to keep your dashboard updated with new data, you can run a scheduled query that will run every day and append your materialized table with the new data.
Join first party data (e.g. CRM) for business insights. In the materialized table, you can add user_id as a separate column. This will let you join your first party data. If your first party data is not already in BigQuery, you can either load the data or use a federated data source.
Report your site or app version as a parameter in the data you send to Google Analytics and add it as a column in the materialized table. Then you can add that version data as a dimension in your charts to make it easier to see version changes affect performance.
If you are expecting significantly heavy usage of the dataset through direct query or the dashboard, you can try using the paid version of BigQuery BI Engine.

Summary #

This post covered the basics of how to use Google Analytics 4 and BigQuery to measure and debug performance with real-user data collected in the field. It also explained how to build automated reports and dashboards using Looker Studio and the Web Vitals Connector to make visualizing the data as easy as possible.

Some key takeaways from this post:

Measuring performance with real user data is critical for understanding, debugging, and optimizing your site.
You can get deeper insights when your performance metrics and your business metrics are in the same system. Google Analytics and BigQuery make this possible.
BigQuery export of raw Google Analytics data gives you unlimited potential for in-depth, custom analysis using a query language you likely already know.
Google has a number of APIs and visualization tools like Looker Studio that give you the freedom to build your reports exactly the way you want them to be built.

Debug performance in the field

2021-04-01T00:00:00Z

Google currently provides two categories of tools to measure and debug performance:

Lab tools: Tools such as Lighthouse, where your page is loaded in a simulated environment that can mimic various conditions (for example, a slow network and a low-end mobile device).
Field tools: Tools such as Chrome User Experience Report (CrUX), which is based on aggregate, real-user data from Chrome. (Note that the field data reported by tools such as PageSpeed Insights and Search Console is sourced from CrUX data.)

While field tools offer more accurate data—data which actually represents what real users experience—lab tools are often better at helping you identify and fix issues.

CrUX data is more representative of your page's real performance, but knowing your CrUX scores is unlikely to help you figure out how to improve your performance.

Lighthouse, on the other hand, will identify issues and make specific suggestions for how to improve. However, Lighthouse will only make suggestions for performance issues it discovers at page load time. It does not detect issues that only manifest as a result of user interaction such as scrolling or clicking buttons on the page.

This raises an important question: how can you capture debug information for Core Web Vitals or other performance metrics from real users in the field?

This post will explain in detail what APIs you can use to collect additional debugging information for each of the current Core Web Vitals metrics and give you ideas for how to capture this data in your existing analytics tool.

APIs for attribution and debugging #

CLS #

Of all the Core Web Vitals metrics, CLS is perhaps the one for which collecting debug information in the field is the most important. CLS is measured throughout the entire lifespan of the page, so the way a user interacts with the page—how far they scroll, what they click on, and so on—can have a significant impact on whether there are layout shifts and which elements are shifting.

Consider the following report from PageSpeed Insights for the URL: web.dev/measure

The value reported for CLS from the lab (Lighthouse) compared to the CLS from the field (CrUX data) are quite different, and this makes sense if you consider that the web.dev/measure page has a lot of interactive content that is not being used when tested in Lighthouse.

But even if you understand that user interaction affects field data, you still need to know what elements on the page are shifting to result in a score of 0.45 at the 75th percentile.

The LayoutShiftAttribution interface makes that possible.

Get layout shift attribution #

The LayoutShiftAttribution interface is exposed on each layout-shift entry that Layout Instability API emits.

For a detailed explanation of both of these interfaces, see Debug layout shifts. For the purposes of this post, the main thing you need to know is that, as a developer, you are able to observe every layout shift that happens on the page as well as what elements are shifting.

Here's some example code that logs each layout shift as well as the elements that shifted:

new PerformanceObserver((list) => {
  for (const {value, startTime, sources} of list.getEntries()) {
    // Log the shift amount and other entry info.
    console.log('Layout shift:', {value, startTime});
    if (sources) {
      for (const {node, curRect, prevRect} of sources) {
        // Log the elements that shifted.
        console.log('  Shift source:', node, {curRect, prevRect});
      }
    }
  }
}).observe({type: 'layout-shift', buffered: true});

It's probably not practical to measure and send data to your analytics tool for every single layout shift that occurs; however, by monitoring all shifts, you can keep track of the worst shifts and just report information about those.

The goal isn't to identify and fix every single layout shift that occurs for every user; the goal is to identify the shifts that affect the largest number of users and thus contribute the most to your page's CLS at the 75th percentile.

Also, you don't need to compute the largest source element every time there's a shift, you only need to do so when you're ready to send the CLS value to your analytics tool.

The following code takes a list of layout-shift entries that have contributed to CLS and returns the largest source element from the largest shift:

function getCLSDebugTarget(entries) {
  const largestEntry = entries.reduce((a, b) => {
    return a && a.value > b.value ? a : b;
  });
  if (largestEntry && largestEntry.sources && largestEntry.sources.length) {
    const largestSource = largestEntry.sources.reduce((a, b) => {
      return a.node && a.previousRect.width * a.previousRect.height >
          b.previousRect.width * b.previousRect.height ? a : b;
    });
    if (largestSource) {
      return largestSource.node;
    }
  }
}

Once you've identified the largest element contributing to the largest shift, you can report that to your analytics tool.

The element contributing the most to CLS for a given page will likely vary from user to user, but if you aggregate those elements across all users, you'll be able to generate a list of shifting elements affecting the most number of users.

After you've identified and fixed the root cause of the shifts for those elements, your analytics code will start reporting smaller shifts as the "worst" shifts for your pages. Eventually, all reported shifts will be small enough that your pages are well within the "good" threshold of 0.1!

Some other metadata that may be useful to capture along with the largest shift source element is:

The time of the largest shift
The URL path at the time of the largest shift (for sites that dynamically update the URL, such as Single Page Applications).

LCP #

To debug LCP in the field, the primary information you need is which particular element was the largest element (the LCP candidate element) for that particular page load.

Note that it's entirely possible—in fact, it's quite common—that the LCP candidate element will be different from user to user, even for the exact same page.

This can happen for several reasons:

User devices have different screen resolutions, which results in different page layouts and thus different elements being visible within the viewport.
Users don't always load pages scrolled to the very top. Oftentimes links will contain fragment identifiers or even text fragments, which means it's possible for your pages to be loaded and displayed at any scroll position on the page.
Content may be personalized for the current user, so the LCP candidate element could vary wildly from user to user.

This means you cannot make assumptions about which element or set of elements will be the most common LCP candidate element for a particular page. You have to measure it based on real-user behavior.

Identify the LCP candidate element #

To determine the LCP candidate element in JavaScript you can use the Largest Contentful Paint API, the same API you use to determine the LCP time value.

When observing largest-contentful-paint entries, you can determine the current LCP candidate element by looking at the element property of the last entry:

new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1];

  console.log('LCP element:', lastEntry.element);
}).observe({type: 'largest-contentful-paint', buffered: true});

Once you know the LCP candidate element, you can send it to your analytics tool along with the metric value. As with CLS, this will help you identify which elements are most important to optimize first.

In addition to the LCP candidate element, it may also be useful to measure the LCP sub-part times, which can be useful in determining what specific optimization steps are relevant for your site.

FID #

To debug FID in the field, it's important to remember that FID measures only the delay portion of the overall first input event latency. That means that what the user interacted with is not really as important as what else was happening on the main thread at the time they interacted.

For example, many JavaScript applications that support server-side rendering (SSR) will deliver static HTML that can be rendered to the screen before it's interactive to user input—that is, before the JavaScript required to make the content interactive has finished loading.

For these types of applications, it can be very important to know whether the first input occurred before or after hydration. If it turns out that many people are attempting to interact with the page before hydration completes, consider rendering your pages in a disabled or loading state rather than in a state that looks interactive.

If your application framework exposes the hydration timestamp, you can easily compare that with the timestamp of the first-input entry to determine whether the first input happened before or after hydration. If your framework doesn't expose that timestamp, or doesn't use hydration at all, another useful signal may be whether input occurred before or after JavaScript finished loading.

The DOMContentLoaded event fires after the page's HTML has completely loaded and parsed, which includes waiting for any synchronous, deferred, or module scripts (including all statically imported modules) to load. So you can use the timing of that event and compare it to when FID occurred.

The following code observes first-input entries and logs whether or not the first input occurred prior to the end of the DOMContentLoaded event:

new PerformanceObserver((list) => {
  const fidEntry = list.getEntries()[0];
  const navEntry = performance.getEntriesByType('navigation')[0];
  const wasFIDBeforeDCL =
    fidEntry.startTime < navEntry.domContentLoadedEventStart;

  console.log('FID occurred before DOMContentLoaded:', wasFIDBeforeDCL);
}).observe({type: 'first-input', buffered: true});

Identify the FID target element and event type #

Additional potentially-useful debug signals are the element that was interacted with as well as the type of interaction it was (such as mousedown, keydown, pointerdown). While the interaction with the element itself does not contribute to FID (remember FID is just the delay portion of the total event latency), knowing which elements your users are interacting with may be useful in determining how best to improve FID.

For example, if the vast majority of your user's first interactions are with a particular element, consider inlining the JavaScript code needed for that element in the HTML, and lazy loading the rest.

To get the interaction type and element associated with the first input event, you can reference the first-input entry's target and name properties:

new PerformanceObserver((list) => {
  const fidEntry = list.getEntries()[0];

  console.log('FID target element:', fidEntry.target);
  console.log('FID interaction type:', fidEntry.name);
}).observe({type: 'first-input', buffered: true});

INP #

INP is very similar to FID in that the most useful bits of information to capture in the field are:

What element was interacted with
Why type of interaction it was
When that interaction took place

Like FID, a major cause of slow interactions is a blocked main thread, which can be common while JavaScript is loading. Knowing whether most slow interactions occur during page load is helpful in determining what needs to be done to fix the problem.

Unlike FID, the INP metric considers the full latency of an interaction—including the time it takes to run any registered event listeners as well as the time it takes to paint the next frame after all events listeners have run. This means that for INP it's even more useful to know which target elements tend to result in slow interactions, and what types of interactions those are.

Since INP and FID are both based on the Event Timing API, the way you determine this information in JavaScript is very similar to the previous example. The following code logs the target element and time (relative to DOMContentLoaded) of the INP entry.

function logINPDebugInfo(inpEntry) {
  console.log('INP target element:', inpEntry.target);
  console.log('INP interaction type:', inpEntry.name);

  const navEntry = performance.getEntriesByType('navigation')[0];
  const wasINPBeforeDCL =
    inpEntry.startTime < navEntry.domContentLoadedEventStart;

  console.log('INP occurred before DCL:', wasINPBeforeDCL);
}

Note that this code doesn't show how to determine which event entry is the INP entry, as that logic is more involved. However, the following section explains how to get this information using the web-vitals JavaScript library.

Usage with the web-vitals JavaScript library #

The sections above offer some general suggestions and code examples to capture debug info to include in the data you send to your analytics tool.

Since version 3, the web-vitals JavaScript library includes an attribution build that surfaces all of this information, and a few additional signals as well.

The following code example shows how you could set an additional event parameter (or custom dimension) containing a debug string useful for helping to identify the root cause of performance issues.

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

function sendToGoogleAnalytics({name, value, id, attribution}) {
  const eventParams = {
    metric_value: value,
    metric_id: id,
  }

  switch (name) {
    case 'CLS':
      eventParams.debug_string = attribution.largestShiftTarget;
      break;
    case 'LCP':
      eventParams.debug_string = attribution.element;
      break;
    case 'FID':
    case 'INP':
      eventParams.debug_string = attribution.eventTarget;
      break;
  }

  // Assumes the global `gtag()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/ga4
  gtag('event', name, eventParams);
}

onCLS(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
onFID(sendToGoogleAnalytics);
onINP(sendToGoogleAnalytics);

This code is specific to Google Analytics, but the general idea should easily translate to other analytics tools as well.

This code also just shows how to report on a single debug signal, but it may be useful to be able to collect and report on multiple different signals per metric. For example, to debug INP you might want to collect the interaction type, time, and also the element being interacted with. The web-vitals attribution build exposes all of this information, as show in the following example:

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

function sendToGoogleAnalytics({name, value, id, attribution}) {
  const eventParams = {
    metric_value: value,
    metric_id: id,
  }

  switch (name) {
    case 'INP':
      eventParams.inp_target = attribution.eventTarget;
      eventParams.inp_type = attribution.eventType;
      eventParams.inp_time = attribution.eventTime;
      eventParams.inp_load_state = attribution.loadState;
      break;

    // Additional metric logic...
  }

  // Assumes the global `gtag()` function exists, see:
  // https://developers.google.com/analytics/devguides/collection/ga4
  gtag('event', name, eventParams);
}

onCLS(sendToGoogleAnalytics);
onLCP(sendToGoogleAnalytics);
onFID(sendToGoogleAnalytics);
onINP(sendToGoogleAnalytics);

Refer to the web-vitals attribution documentation for the complete list of debug signals exposed.

Report and visualize the data #

Once you've started collecting debug information along with the metric values, the next step is aggregating the data across all your users to start looking for patterns and trends.

As mentioned above, you don't necessarily need to address every single issue your users are encountering, you want to address—especially at first—the issues that are affecting the largest number of users, which should also be the issues that have the largest negative impact on your Core Web Vitals scores.

The Web Vitals Report tool #

If you're using the Web Vitals Report tool, it allows you to additionally report on a single debug dimension for each of the Core Web Vitals metrics.

Here's a screenshot from the Web Vitals Report debug info section, showing data for the Web Vitals Report tool website itself:

Using the data above, you can see that whatever is causing the section.Intro element to shift is contributing the most to CLS on this page, so identifying and fixing the cause of that shift will yield the greatest improvement to the score.

Summary #

Hopefully this post has helped outline the specific ways you can use the existing performance APIs and the web-vitals library to get debug information to help diagnose performance based on real users visits in the field. While this guide is focused on the Core Web Vitals, the concepts also apply to debugging any performance metric that's measurable in JavaScript.

If you're just getting started measuring performance, and you're already a Google Analytics user, the Web Vitals Report tool may be a good place to start because it already supports reporting debug information for the Core Web Vitals metrics.

If you're an analytics vendor and you're looking to improve your products and provide more debugging information to your users, consider some of the techniques described here but don't limit yourself to just the ideas presented here. This post is intended to be generally applicable to all analytics tools; however, individual analytics tools likely can (and should) capture and report even more debug information.

Lastly, if you feel there are gaps in your ability to debug these metrics due to missing features or information in the APIs themselves send your feedback to web-vitals-feedback@googlegroups.com.

Back/forward cache

2020-11-10T00:00:00Z

Back/forward cache (or bfcache) is a browser optimization that enables instant back and forward navigation. It significantly improves the browsing experience for users—especially those with slower networks or devices.

As web developers, it's critical to understand how to optimize your pages for bfcache across all browsers, so your users can reap the benefits.

Browser compatibility #

bfcache has been supported in both Firefox and Safari for many years, across desktop and mobile.

Starting in version 86, Chrome enabled bfcache for cross-site navigations on Android for a small percentage of users. In subsequent releases, additional support slowly rolled out. Since version 96, bfcache is enabled for all Chrome users across desktop and mobile.

bfcache basics #

bfcache is an in-memory cache that stores a complete snapshot of a page (including the JavaScript heap) as the user is navigating away. With the entire page in memory, the browser can quickly and easily restore it if the user decides to return.

How many times have you visited a website and clicked a link to go to another page, only to realize it's not what you wanted and click the back button? In that moment, bfcache can make a big difference in how fast the previous page loads:

Without bfcache enabled	A new request is initiated to load the previous page, and, depending on how well that page has been optimized for repeat visits, the browser might have to re-download, re-parse, and re-execute some (or all) of resources it just downloaded.
With bfcache enabled	Loading the previous page is essentially instant, because the entire page can be restored from memory, without having to go to the network at all

Check out this video of bfcache in action to understand the speed up it can bring to navigations:

In the video above, the example with bfcache is quite a bit faster than the example without it.

bfcache not only speeds up navigation, it also reduces data usage, since resources do not have to be downloaded again.

Chrome usage data shows that 1 in 10 navigations on desktop and 1 in 5 on mobile are either back or forward. With bfcache enabled, browsers could eliminate the data transfer and time spent loading for billions of web pages every single day!

How the "cache" works #

The "cache" used by bfcache is different from the HTTP cache (which is also useful in speeding up repeat navigations). The bfcache is a snapshot of the entire page in memory (including the JavaScript heap), whereas the HTTP cache contains only the responses for previously made requests. Since it's quite rare that all requests required to load a page can be fulfilled from the HTTP cache, repeat visits using bfcache restores are always faster than even the most well-optimized non-bfcache navigations.

Creating a snapshot of a page in memory, however, involves some complexity in terms of how best to preserve in-progress code. For example, how do you handle setTimeout() calls where the timeout is reached while the page is in the bfcache?

The answer is that browsers pause running any pending timers or unresolved promises—essentially all pending tasks in the JavaScript task queues—and resume processing tasks when (or if) the page is restored from the bfcache.

In some cases this is fairly low-risk (for example, timeouts or promises), but in other cases it might lead to very confusing or unexpected behavior. For example, if the browser pauses a task that's required as part of an IndexedDB transaction, it can affect other open tabs in the same origin (since the same IndexedDB databases can be accessed by multiple tabs simultaneously). As a result, browsers will generally not attempt to cache pages in the middle of an IndexedDB transaction or using APIs that might affect other pages.

For more details on how various API usage affects a page's bfcache eligibility, see Optimize your pages for bfcache below.

APIs to observe bfcache #

While bfcache is an optimization that browsers do automatically, it's still important for developers to know when it's happening so they can optimize their pages for it and adjust any metrics or performance measurement accordingly.

The primary events used to observe bfcache are the page transition events—pageshow and pagehide—which have been around as long as bfcache has and are supported in pretty much all browsers in use today.

The newer Page Lifecycle events—freeze and resume—are also dispatched when pages go in or out of the bfcache, as well as in some other situations. For example when a background tab gets frozen to minimize CPU usage. Note, the Page Lifecycle events are currently only supported in Chromium-based browsers.

Observe when a page is restored from bfcache #

The pageshow event fires right after the load event when the page is initially loading and any time the page is restored from bfcache. The pageshow event has a persisted property which will be true if the page was restored from bfcache (and false if not). You can use the persisted property to distinguish regular page loads from bfcache restores. For example:

window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    console.log('This page was restored from the bfcache.');
  } else {
    console.log('This page was loaded normally.');
  }
});

In browsers that support the Page Lifecycle API, the resume event will also fire when pages are restored from bfcache (immediately before the pageshow event), though it will also fire when a user revisits a frozen background tab. If you want to restore a page's state after it's frozen (which includes pages in the bfcache), you can use the resume event, but if you want to measure your site's bfcache hit rate, you'd need to use the pageshow event. In some cases, you might need to use both.

Observe when a page is entering bfcache #

The pagehide event is the counterpart to the pageshow event. The pageshow event fires when a page is either loaded normally or restored from the bfcache. The pagehide event fires when the page is either unloaded normally or when the browser attempts to put it into the bfcache.

The pagehide event also has a persisted property, and if it's false then you can be confident a page is not about to enter the bfcache. However, if the persisted property is true, it doesn't guarantee that a page will be cached. It means that the browser intends to cache the page, but there may be factors that make it impossible to cache.

window.addEventListener('pagehide', (event) => {
  if (event.persisted) {
    console.log('This page *might* be entering the bfcache.');
  } else {
    console.log('This page will unload normally and be discarded.');
  }
});

Similarly, the freeze event will fire immediately after the pagehide event (if the event's persisted property is true), but again that only means the browser intends to cache the page. It may still have to discard it for a number of reasons explained below.

Optimize your pages for bfcache #

Not all pages get stored in bfcache, and even when a page does get stored there, it won't stay there indefinitely. It's critical that developers understand what makes pages eligible (and ineligible) for bfcache to maximize their cache-hit rates.

The following sections outline the best practices to make it as likely as possible that the browser can cache your pages.

Never use the `unload` event #

The most important way to optimize for bfcache in all browsers is to never use the unload event. Ever!

The unload event is problematic for browsers because it predates bfcache and many pages on the internet operate under the (reasonable) assumption that a page will not continue to exist after the unload event has fired. This presents a challenge because many of those pages were also built with the assumption that the unload event would fire any time a user is navigating away, which is no longer true (and hasn't been true for a long time).

So browsers are faced with a dilemma, they have to choose between something that can improve the user experience—but might also risk breaking the page.

On desktop, Chrome and Firefox have chosen to make pages ineligible for bfcache if they add an unload listener, which is less risky but also disqualifies a lot of pages. Safari will attempt to cache some pages with an unload event listener, but to reduce potential breakage it will not run the unload event when a user is navigating away, which makes the event very unreliable.

On mobile, Chrome and Safari will attempt to cache pages with an unload event listener since the risk of breakage is lower due to the fact that the unload event has always been extremely unreliable on mobile. Firefox treats pages that use unload as ineligible for the bfcache, except on iOS, which requires all browsers to use the WebKit rendering engine, and so it behaves like Safari.

Instead of using the unload event, use the pagehide event. The pagehide event fires in all cases where the unload event currently fires, and it also fires when a page is put in the bfcache.

In fact, Lighthouse has a no-unload-listeners audit, which will warn developers if any JavaScript on their pages (including that from third-party libraries) adds an unload event listener.

Only add `beforeunload` listeners conditionally #

The beforeunload event will not make your pages ineligible for bfcache in Chrome or Safari, but it will make them ineligible in Firefox, so avoid using it unless absolutely necessary.

Unlike the unload event, however, there are legitimate uses for beforeunload. For example, when you want to warn the user that they have unsaved changes they'll lose if they leave the page. In this case, it's recommended that you only add beforeunload listeners when a user has unsaved changes and then remove them immediately after the unsaved changes are saved.

Don't

window.addEventListener('beforeunload', (event) => {
  if (pageHasUnsavedChanges()) {
    event.preventDefault();
    return event.returnValue = 'Are you sure you want to exit?';
  }
});

The code above adds a beforeunload listener unconditionally.

function beforeUnloadListener(event) {
  event.preventDefault();
  return event.returnValue = 'Are you sure you want to exit?';
};

// A function that invokes a callback when the page has unsaved changes.
onPageHasUnsavedChanges(() => {
  window.addEventListener('beforeunload', beforeUnloadListener);
});

// A function that invokes a callback when the page's unsaved changes are resolved.
onAllChangesSaved(() => {
  window.removeEventListener('beforeunload', beforeUnloadListener);
});

The code above only adds the beforeunload listener when it's needed (and removes it when it's not).

Minimize use of `Cache-Control: no-store` #

Cache-Control: no-store is an HTTP header web servers can set on responses that instructs the browser not to store the response in any HTTP cache. This should be used for resources containing sensitive user information, for example pages behind a login.

Though bfcache is not an HTTP cache, historically, when Cache-Control: no-store is set on the page resource itself (as opposed to any subresource), browsers have chosen not to store the page in bfcache. There is work currently underway to change this behavior for Chrome in a privacy-preserving manner, but at present any pages using Cache-Control: no-store will not be eligible for bfcache.

Since Cache-Control: no-store restricts a page's eligibility for bfcache, it should only be set on pages that contain sensitive information where caching of any sort is never appropriate.

For pages that wish to always serve up-to-date content—and that content does not contain sensitive information—use Cache-Control: no-cache or Cache-Control: max-age=0. These directives instruct the browser to revalidate the content before serving it, and they do not affect a page's bfcache eligibility.

Note that when a page is restored from bfcache, it is restored from memory, not from the HTTP cache. As a result, directives like Cache-Control: no-cache or Cache-Control: max-age=0 are not taken into account, and no revalidation occurs before the content is displayed to the user.

This is still likely a better user experience, however, as bfcache restores are instant and—since pages do not stay in the bfcache for very long—it's unlikely that the content is out of date. However, if your content does change minute-by-minute, you can fetch any updates using the pageshow event, as outlined in the next section.

Update stale or sensitive data after bfcache restore #

If your site keeps user state—especially any sensitive user information—that data needs to be updated or cleared after a page is restored from bfcache.

For example, if a user navigates to a checkout page and then updates their shopping cart, a back navigation could potentially expose out-of-date information if a stale page is restored from bfcache.

Another, more critical example is if a user signs out of a site on a public computer and the next user clicks the back button. This could potentially expose private data that the user assumed was cleared when they logged out.

To avoid situations like this, it's good to always update the page after a pageshow event if event.persisted is true.

The following code checks for the presence of a site-specific cookie in the pageshow event and reloads if the cookie is not found:

window.addEventListener('pageshow', (event) => {
  if (event.persisted && !document.cookie.match(/my-cookie/)) {
    // Force a reload if the user has logged out.
    location.reload();
  }
});

Avoid `window.opener` references #

In some browsers (including Chromium-based browsers) if a page was opened using window.open() or (in Chromium-based browsers prior to version 88) from a link with target=_blank—without specifying rel="noopener"—then the opening page will have a reference to the window object of the opened page.

In addition to being a security risk, a page with a non-null window.opener reference cannot safely be put into the bfcache because that could break any pages attempting to access it.

As a result, it's best to avoid creating window.opener references. You can do this by using rel="noopener" whenever possible. If your site requires opening a window and controlling it through window.postMessage() or directly referencing the window object, neither the opened window nor the opener will be eligible for the bfcache.

Always close open connections before the user navigates away #

As mentioned above, when a page is put into the bfcache all scheduled JavaScript tasks are paused and then resumed when the page is taken out of the cache.

If these scheduled JavaScript tasks are only accessing DOM APIs—or other APIs isolated to just the current page—then pausing these tasks while the page is not visible to the user is not going to cause any problems.

However, if these tasks are connected to APIs that are also accessible from other pages in the same origin (for example: IndexedDB, Web Locks, WebSockets, etc.) this can be problematic because pausing these tasks may prevent code in other tabs from running.

As a result, some browsers will not attempt to put a page in bfcache in the following scenarios:

Pages with an open IndexedDB connection
Pages with in-progress fetch() or XMLHttpRequest
Pages with an open WebSocket or WebRTC connection

If your page is using any of these APIs, it's best to always close connections and remove or disconnect observers during the pagehide or freeze event. That will allow the browser to safely cache the page without the risk of it affecting other open tabs.

Then, if the page is restored from the bfcache, you can re-open or re-connect to those APIs (in the pageshow or resume event).

The following example shows how to ensure your pages are eligible for bfcache when using IndexedDB by closing an open connection in the pagehide event listener:

let dbPromise;
function openDB() {
  if (!dbPromise) {
    dbPromise = new Promise((resolve, reject) => {
      const req = indexedDB.open('my-db', 1);
      req.onupgradeneeded = () => req.result.createObjectStore('keyval');
      req.onerror = () => reject(req.error);
      req.onsuccess = () => resolve(req.result);
    });
  }
  return dbPromise;
}

// Close the connection to the database when the user is leaving.
window.addEventListener('pagehide', () => {
  if (dbPromise) {
    dbPromise.then(db => db.close());
    dbPromise = null;
  }
});

// Open the connection when the page is loaded or restored from bfcache.
window.addEventListener('pageshow', () => openDB());

Test to ensure your pages are cacheable #

Chrome DevTools can help you test your pages to ensure they're optimized for bfcache, and identify any issues that may be preventing them from being eligible.

To test a particular page, navigate to it in Chrome and then in DevTools go to Application > Back-forward Cache. Next click the Run Test button and DevTools will attempt to navigate away and back to determine whether the page could be restored from bfcache.

If successful, the panel will report "Restored from back-forward cache":

If unsuccessful, the panel will indicate the page was not restored and list the reason why. If the reason is something you as a developer can address, that will also be indicated:

In the screenshot above, the use of an unload event listener is preventing the page from being eligible for bfcache. You can fix that by switching from unload to using pagehide instead:

Don't

window.addEventListener('unload', ...);

window.addEventListener('pagehide', ...);

Lighthouse 10.0 also added a bfcache audit, which performs a similar test to the one DevTools does, and also provides reasons why the page is ineligible if the audit fails. Take a look at the bfcache audit's docs for more information.

How bfcache affects analytics and performance measurement #

If you track visits to your site with an analytics tool, you will likely notice a decrease in the total number of pageviews reported as Chrome continues to enable bfcache for more users.

In fact, you're likely already underreporting pageviews from other browsers that implement bfcache since most of the popular analytics libraries do not track bfcache restores as new pageviews.

If you don't want your pageview counts to go down due to Chrome enabling bfcache, you can report bfcache restores as pageviews (recommended) by listening to the pageshow event and checking the persisted property.

The following example shows how to do this with Google Analytics; the logic should be similar for other analytics tools:

// Send a pageview when the page is first loaded.
gtag('event', 'page_view');

window.addEventListener('pageshow', (event) => {
  // Send another pageview if the page is restored from bfcache.
  if (event.persisted) {
    gtag('event', 'page_view');
  }
});

Measuring your bfcache hit ratio #

You may also wish to track whether the bfcache was used, to help identify pages that are not utilizing the bfcache. For example, with an event:

window.addEventListener('pageshow', (event) => {
  // You can measure bfcache hit rate by tracking all bfcache restores and
  // other back/forward navigations via a separate event.
  const navigationType = performance.getEntriesByType('navigation')[0].type;
  if (event.persisted || navigationType == 'back_forward' ) {
    gtag('event', 'back_forward_navigation', {
      'isBFCache': event.persisted,
    });
  }
});

It is important to realize that there are a number of scenarios, outside of the site owners control, when a Back/Forward navigation will not use the bfcache, including:

when the user quits the browser and starts it again
when the user duplicates a tab
when the user closes a tab and uncloses it

Even without those exclusions the bfcache will be discarded after a period to conserve memory.

So, website owners should not be expecting a 100% bfcache hit ratio for all back_forward navigations. However, measuring their ratio can be useful to identify pages where the page itself is preventing bfcache usage for a high proportion of back and forward navigations.

The Chrome team is working on a NotRestoredReasons API to help expose the reasons why the bfcache was not used to help developers understand the reasoning the cache was not used and if this is something they can work on to improve for their sites.

Performance measurement #

bfcache can also negatively affect performance metrics collected in the field, specifically metrics that measure page load times.

Since bfcache navigations restore an existing page rather than initiate a new page load, the total number of page loads collected will decrease when bfcache is enabled. What's critical, though, is that the page loads being replaced by bfcache restores would likely have been some of the fastest page loads in your dataset. This is because back and forward navigations, by definition, are repeat visits, and repeat page loads are generally faster than page loads from first time visitors (due to HTTP caching, as mentioned earlier).

The result is fewer fast page loads in your dataset, which will likely skew the distribution slower—despite the fact that the performance experienced by the user has probably improved!

There are a few ways to deal with this issue. One is to annotate all page load metrics with their respective navigation type: navigate, reload, back_forward, or prerender. This will allow you to continue to monitor your performance within these navigation types—even if the overall distribution skews negative. This approach is recommended for non-user-centric page load metrics like Time to First Byte (TTFB).

For user-centric metrics like the Core Web Vitals, a better option is to report a value that more accurately represents what the user experiences.

Impact on Core Web Vitals #

Core Web Vitals measure the user's experience of a web page across a variety of dimensions (loading speed, interactivity, visual stability), and since users experience bfcache restores as faster navigations than traditional page loads, it's important that the Core Web Vitals metrics reflect this. After all, a user doesn't care whether or not bfcache was enabled, they just care that the navigation was fast!

Tools like the Chrome User Experience Report, that collect and report on the Core Web Vitals metrics treat bfcache restores as separate page visits in their dataset.

And while there aren't (yet) dedicated web performance APIs for measuring these metrics after bfcache restores, their values can be approximated using existing web APIs.

For Largest Contentful Paint (LCP), you can use the delta between the pageshow event's timestamp and the timestamp of the next painted frame (since all elements in the frame will be painted at the same time). Note that in the case of a bfcache restore, LCP and FCP will be the same.
For First Input Delay (FID), you can re-add the event listeners (the same ones used by the FID polyfill) in the pageshow event, and report FID as the delay of the first input after the bfcache restore.
For Cumulative Layout Shift (CLS), you can continue to keep using your existing Performance Observer; all you have to do is reset the current CLS value to 0.

For more details on how bfcache affects each metric, refer to the individual Core Web Vitals metric guides pages. And for a specific example of how to implement bfcache versions of these metrics in code, refer to the PR adding them to the web-vitals JS library.

Additional Resources #

Firefox Caching (bfcache in Firefox)
Page Cache (bfcache in Safari)
Back/forward cache: web exposed behavior (bfcache differences across browsers)
bfcache tester (test how different APIs and events affect bfcache in browsers)
Performance Game Changer: Browser Back/Forward Cache (a case study from Smashing Magazine showing dramatic Core Web Vitals improvements by enabling bfcache)

Best practices for measuring Web Vitals in the field

2020-05-27T00:00:00Z

Having the ability to measure and report on the real-world performance of your pages is critical for diagnosing and improving performance over time. Without field data, it's impossible to know for sure whether the changes you're making to your site are actually achieving their desired results.

Many popular Real User Monitoring (RUM) analytics providers already support the Core Web Vitals metrics in their tools (as well as many other Web Vitals). If you're currently using one of these RUM analytics tools, you're in great shape to assess how well the pages on your site meet the recommended Core Web Vitals thresholds and prevent regressions in the future.

While we do recommend using an analytics tool that supports the Core Web Vitals metrics, if the analytics tool you're currently using does not support them, you don't necessarily need to switch. Almost all analytics tools offer a way to define and measure custom metrics or events, which means you can likely use your current analytics provider to measure the Core Web Vitals metrics and add them to your existing analytics reports and dashboards.

This guide discusses best practices for measuring Core Web Vitals metrics (or any custom metrics) with a third-party or in-house analytics tool. It can also serve as a guide for analytics vendors wishing to add Core Web Vitals support to their service.

Use custom metrics or events #

As mentioned above, most analytics tools let you measure custom data. If your analytics tool supports this, you should be able to measure each of the Core Web Vitals metrics using this mechanism.

Measuring custom metrics or events in an analytics tool is generally a three-step process:

Define or register the custom metric in your tool's admin (if required). (Note: not all analytics providers require custom metrics to be defined ahead of time.)
Compute the value of the metric in your frontend JavaScript code.
Send the metric value to your analytics backend, ensuring the name or ID matches what was defined in step 1 (again, if required).

For steps 1 and 3, you can refer to your analytics tool's documentation for instructions. For step 2 you can use the web-vitals JavaScript library to compute the value of each of the Core Web Vitals metrics.

The following code sample shows how easy it can be to track these metrics in code and send them to an analytics service.

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

function sendToAnalytics({name, value, id}) {
  const body = JSON.stringify({name, value, id});
  // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
      fetch('/analytics', {body, method: 'POST', keepalive: true});
}

onCLS(sendToAnalytics);
onFID(sendToAnalytics);
onLCP(sendToAnalytics);

Avoid averages #

It's tempting to sum up a range of values for a performance metric by calculating an average. Averages seem convenient at first glance, as they're a tidy summary of a large quantity of data, but you should resist the urge to rely on them to interpret page performance.

Averages are problematic because they don't represent any single user's session. Outliers at either range of the distribution may skew the average in ways that are misleading.

For example, a small group of users may be on extremely slow networks or devices that are toward the maximum range of values, but don't account for enough user sessions to impact the average in a way that suggests there's a problem.

Whenever possible, rely on percentiles instead of averages. Percentiles across a distribution for a given performance metric better describe the full range of user experiences for your website. This allows you to focus on subsets of actual experiences, which will give you more insight than a single value ever could.

Ensure you can report a distribution #

Once you've computed the values for each of the Core Web Vitals metrics and sent them to your analytics service using a custom metric or event, the next step is to build a report or dashboard displaying the values that have been collected.

To ensure you're meeting the recommended Core Web Vitals thresholds, you'll need your report to display the value of each metric at the 75th percentile.

If your analytics tool does not offer quantile reporting as a built-in feature, you can probably still get this data manually by generating a report that lists every metric value sorted in ascending order. Once this report is generated, the result that is 75% of the way through the full, sorted list of all values in that report will be the 75th percentile for that metric—and this will be the case no matter how you segment your data (by device type, connection type, country, etc.).

If your analytic tool does not give you metric-level reporting granularity by default, you can probably achieve the same result if your analytics tool supports custom dimensions. By setting a unique, custom dimension value for each individual metric instance you track, you should be able to generate a report, broken down by individual metric instances, if you include the custom dimension in the report configuration. Since each instance will have a unique dimension value, no grouping will occur.

The Web Vitals Report is an example of this technique that uses Google Analytics. The code for the report is open source, so developers can reference it as an example of the techniques outlined in this section.

Send your data at the right time #

Some performance metrics can be calculated once the page has finished loading, while others (like CLS) consider the entire lifespan of the page—and are only final once the page has started unloading.

This can be problematic, however, since both the beforeunload and unload events are not reliable (especially on mobile) and their use is not recommended (since they can prevent a page from being eligible for the Back-Forward Cache).

For metrics that track the entire lifespan of a page, it's best to send whatever the metric's current value is during the visibilitychange event, whenever the page's visibility state changes to hidden. This is because—once the page's visibility state changes to hidden—there's no guarantee that any script on that page will be able to run again. This is especially true on mobile operating systems where the browser app itself can be closed without any page callbacks being fired.

Note that mobile operating systems do generally fire the visibilitychange event when switching tabs, switching apps, or closing the browser app itself. They also fire the visibilitychange event when closing a tab or navigating to a new page. This makes the visibilitychange event far more reliable than the unload or beforeunload events.

Monitor performance over time #

Once you've updated your analytics implementation to both track and report on the Core Web Vitals metrics, the next step is to track how changes to your site affect performance over time.

Version your changes #

A naive (and ultimately unreliable) approach to tracking changes is to deploy changes to production and then assume that all metrics received after the deployment date correspond to the new site and all metrics received before the deployment date correspond to the old site. However, any number of factors (including caching at the HTTP, service worker, or CDN layer) can prevent this from working.

A much better approach is to create a unique version for each deployed change and then track that version in your analytics tool. Most analytics tools support setting a version. If yours does not, you can create a custom dimension and set that dimension to your deployed version.

Run experiments #

You can take versioning one step further by tracking multiple versions (or experiments) at the same time.

If your analytics tool lets you define experiment groups, use that feature. Otherwise, you can use custom dimensions to ensure each of your metric values can be associated with a particular experiment group in your reports.

With experimentation in place in your analytics, you can roll out an experimental change to a subset of your users and compare the performance of that change to the performance of users in the control group. Once you have confidence that a change does indeed improve performance, you can roll it out to all users.

Ensure measurement doesn't affect performance #

When measuring performance on real users, it's absolutely critical that any performance measurement code you're running does not negatively impact the performance of your page. If it does, then any conclusions you attempt to draw on how your performance affects your business will be unreliable, as you'll never know if the presence of the analytics code itself is having the largest negative impact.

Always follow these principles when deploying RUM analytics code on your production site:

Defer your analytics #

Analytics code should always be loaded in an asynchronous, non-blocking way, and generally it should be loaded last. If you load your analytics code in a blocking way, it can negatively affect LCP.

All of the APIs used to measure the Core Web Vitals metrics were specifically designed to support asynchronous and deferred script loading (via the buffered flag), so there's no need to rush to get your scripts loaded early.

In the event that you're measuring a metric that cannot be computed later in the page load timeline, you should inline only the code that needs to run early into the <head> of your document (so it's not a render-blocking request) and defer the rest. Do not load all your analytics early just because a single metric requires it.

Do not create long tasks #

Analytics code often runs in response to user input, but if your analytics code is conducting a lot of DOM measurements or using other processor-intensive APIs the analytics code itself can cause poor input responsiveness. In addition, if the JavaScript file containing your analytics code is large, executing that file can block the main thread and negatively affect First Input Delay (FID) or Interaction to Next Paint (INP).

Use non-blocking APIs #

APIs like sendBeacon() and requestIdleCallback() are specifically designed for running non-critical tasks in a way that doesn't block user-critical tasks.

These APIs are great tools to use in a RUM analytics library.

In general, all analytics beacons should be sent using the sendBeacon() API (if available), and all passive analytics measurement code should be run during idle periods.

Don't track more than what you need #

The browser exposes a lot of performance data, but just because the data is available does not necessarily mean you should record it and send it to your analytics servers.

For example, the Resource Timing API provides detailed timing data for every single resource loaded on your page. However, it's unlikely that all of that data will be necessarily or useful in improving resource load performance.

In short, don't just track data because it's there, ensure the data will be used before consuming resources tracking it.

Optimize Largest Contentful Paint

2020-05-05T00:00:00Z

Largest Contentful Paint (LCP) is one of the three Core Web Vitals metrics, and it represents how quickly the main content of a web page is loaded. Specifically, LCP measures the time from when the user initiates loading the page until the largest image or text block is rendered within the viewport.

To provide a good user experience, sites should strive to have an LCP of 2.5 seconds or less for at least 75% of page visits.

There are a number of factors that can affect how quickly the browser is able to load and render a web page, and delays across any of them can have a significant impact on LCP.

It's rare that a quick fix to a single part of a page will result in a meaningful improvement to LCP. To improve LCP you have to look at the entire loading process and make sure every step along the way is optimized.

Understanding your LCP metric #

Before optimizing LCP, developers should seek to understand if they even have an LCP issue, and the extent of any such issue.

LCP can be measured in a number of tools and not all of these measure LCP in the same way. To understand LCP of real users, we should look at what real users are experiencing, rather than what a lab-based tool like Lighthouse or local testing shows. These lab-based tools can give a wealth of information to explain and help you improve LCP, but be aware that lab tests alone may not be entirely representative of what your actual users experience.

LCP data based on real users can be surfaced from Real User Monitoring (RUM) tools installed on a site, or via the Chrome User Experience Report (CrUX) which collect anonymous data from real Chrome users for millions of websites.

Using PageSpeed Insights CrUX LCP data #

PageSpeed Insights provides access to CrUX data in the top section labeled Discover what your real users are experiencing. More detailed lab-based data is available in the bottom section labeled Diagnose performance issues. If CrUX data is available for your website, always concentrate on the real user data first.

PageSpeed Insights shows up to four different CrUX data:

Mobile data for This URL
Desktop data for This URL
Mobile data for the whole Origin
Desktop data for the whole Origin

These can be toggled in the controls at the top, and top right-hand side of this section. Be aware that where a URL does not have sufficient data to be shown at the URL level—but does have data for the origin—PageSpeed Insights will automatically show this.

The LCP for the whole origin may be very different to an individual page's LCP depending on how the LCP is loaded on that page compared to other pages on that origin. It can also be affected by how visitors navigate to these pages. Home pages tend to be visted by new users and so may often be loaded "cold", without any cached content and so are often the slowest pages on a website.

Looking at the four different categories of CrUX data can help you understand whether an LCP issue is specific to this page, or a more general site-wide issue. Similarly, it can show which device types have LCP issues.

Using PageSpeed Insights CrUX supplementary metrics #

Those looking to optimize LCP should also use the First Contentful Paint (FCP) and Time to First Byte (TTFB) timings, which are good diagnostic metrics that can provide valuable insights into LCP.

TTFB is the time when the visitor starting to navigate to a page (for example, clicking on a link), until the first bytes of the HTML document are received. A high TTFB can make achieving a 2.5 second LCP challenging, or even impossible.

A high TTFB can be due to mutiple server redirects, visitors located far away from the nearest site server, visitors on poor network conditions, or an inability to use cached content due to query parameters.

Once a page starts rendering, there may be an initial paint (for example, the background color), followed by some content appearing (for example, the site header). The appearance of the initial content is measured by FCP. The delta between FCP and other metrics can be very telling.

A large delta between TTFB and FCP could indicate that the browser needs to download a lot of render-blocking assets. It can also be a sign it must complete a lot of work to render any meaningful content—a classic sign of a site that relies heavily on client-side rendering.

A large delta between FCP and LCP indicates that the LCP resource is either not immediately available for the browser to prioritize (for example, text or images that are managed by JavaScript rather than being available in the initial HTML), or that the browser is completing other work before it can display the LCP content.

Using PageSpeed Insights Lighthouse data #

The Lighthouse section of PageSpeed Insights offers some guidance to improving LCP, but first you should check if the LCP given is broadly inline with real user data provided by CrUX.

If Lighthouse is showing no LCP issue, but the CrUX data is, then any Lighthouse suggestions may not be relevant. The opposite is also true—if Lighthouse is showing a really poor LCP time, but CrUX data is showing your users mostly have a good LCP, then you may wish to consider the priority of optimizing LCP further, or if time is better spent on other performance improvements. Also be sure to check that the CrUX data is for this page and not for the full origin as detailed above.

If both sources of data are showing an LCP that should be improved than the Lighthouse section can provide valuable guidance on ways to improve LCP. Use the LCP filter to only show audits relevant to LCP:

As well as the Opportunities to improve, there is Diagnostic information that may provide more information to help diagnose the issue. The Largest Contentful Paint element diagnostic shows a useful breakdown of the various timings that made up the LCP:

We will delve into these sub-parts next.

LCP breakdown #

Optimizing for LCP can be a more complex task when PageSpeed Insights does not give you the answer on how to improve this metric. With complex tasks it's generally better to break them down into smaller, more manageable tasks and address each separately. This guide will present a methodology for how to break down LCP into its most critical sub-parts and then present specific recommendations and best practices for how to optimize each part.

Most page loads typically include a number of network requests, but for the purposes of identifying opportunities to improve LCP, you should start by looking at just two:

The initial HTML document
The LCP resource (if applicable)

While other requests on the page can affect LCP, these two requests—specifically the times when the LCP resource begins and ends—reveal whether or not your page is optimized for LCP.

To identify the LCP resource, you can use developer tools (such as PageSpeed Insights discussed above, Chrome DevTools, or WebPageTest) to determine the LCP element. From there, you can match the URL (again, if applicable) loaded by the element on a network waterfall of all resources loaded by the page.

For example, the following visualization shows these resources highlighted on a network waterfall diagram from a typical page load, where the LCP element requires an image request to render.

For a well-optimized page, you want your LCP resource request to start loading as early as it can, and you want the LCP element to render as quickly as possible after the LCP resource finishes loading. To help visualize whether or not a particular page is following this principle, you can break down the total LCP time into the following sub-parts:

This table explains each of these LCP sub-parts in more detail:

* If the LCP element does not require a resource load to render (for example, if the element is a text node rendered with a system font), this time will be 0.
LCP sub-part	Description
Time to first byte (TTFB)	The time from when the user initiates loading the page until when the browser receives the first byte of the HTML document response. (See the TTFB metric doc for more details.)
Resource load delay	The delta between TTFB and when the browser starts loading the LCP resource. *
Resource load time	The time it takes to load the LCP resource itself. *
Element render delay	The delta between when the LCP resource finishes loading until the LCP element is fully rendered.

Every single page can have its LCP value broken down into these four sub-parts. There is no overlap or gap between them, and collectively they add up to the full LCP time.

When optimizing LCP, it's helpful to try to optimize these sub-parts individually. But it's also important to keep in mind that you need to optimize all of them. In some cases, an optimization applied to one part will not improve LCP, it will just shift the time saved to another part.

For example, in the earlier network waterfall, if you reduced the file size of our image by compressing it more or switching to a more optimal format (such as AVIF or WebP), that would reduce the resource load time, but it would not actually improve LCP because the time would just shift to the element render delay sub-part:

The reason this happens is because, on this page, the LCP element is hidden until the JavaScript code finishes loading, and then everything is revealed at once.

This example helps illustrate the point that you need to optimize all of these sub-parts in order to achieve the best LCP outcomes.

Optimal sub-part times #

In order to optimize each sub-part of LCP, it's important to understand what the ideal breakdown of these sub-parts is on a well-optimized page.

Of the four sub-parts, two have the word "delay" in their names. That is a clue that you want to get these times as close to zero as possible. The other two parts involve network requests, which by their very nature take time.

LCP sub-part	% of LCP
Time to first byte (TTFB)	~40%
Resource load delay	<10%
Resource load time	~40%
Element render delay	<10%
TOTAL	100%

Note that these time breakdowns are not strict rules, they're guidelines. If the LCP times on your pages are consistently within 2.5 seconds, then it doesn't really matter what the relative proportions are. But if you're spending a lot of unnecessary time in either of the "delay" portions, then it will be very difficult to constantly hit the 2.5 second target.

A good way to think about the breakdown of LCP time is:

The vast majority of the LCP time should be spent loading the HTML document and LCP source.
Any time before LCP where one of these two resources is not loading is an opportunity to improve.

How to optimize each part #

Now that you understand how each of the LCP sub-part times should break down on a well-optimized page, you can start optimizing your own pages.

The next four sections will present recommendations and best practices for how to optimize each part. They're presented in order, starting with the optimizations that are likely to have the biggest impact.

1. Eliminate resource load delay #

The goal in this step is to ensure the LCP resource starts loading as early as possible. While in theory the earliest a resource could start loading is immediately after TTFB, in practice there is always some delay before browsers actually start loading resources.

A good rule of thumb is that your LCP resource should start loading at the same time as the first resource loaded by that page. Or, to put that another way, if the LCP resource starts loading later than the first resource, then there's opportunity for improvement.

Generally speaking, there are two factors that affect how quickly an LCP resource can be loading:

When the resource is discovered.
What priority the resource is given.

Optimize when the resource is discovered #

To ensure your LCP resource starts loading as early as possible, it's critical that the resource is discoverable in the initial HTML document response by the browser's preload scanner. For example, in the following cases, the browser can discover the LCP resource by scanning the HTML document response:

The LCP element is an <img> element, and its src or srcset attributes are present in the initial HTML markup.
The LCP element requires a CSS background image, but that image is preloaded via <link rel="preload"> in the HTML markup (or via a Link header).
The LCP element is a text node that requires a web font to render, and the font is loaded via <link rel="preload"> in the HTML markup (or via a Link header).

Here are some examples where the LCP resource cannot be discovered from scanning the HTML document response:

The LCP element is an <img> that is dynamically added to the page via JavaScript.
The LCP element is lazily loaded with a JavaScript library that hides its src or srcset attributes (often as data-src or data-srcset).
The LCP element requires a CSS background image.

In each of these cases, the browser needs to run the script or apply the stylesheet—which usually involves waiting for network requests to finish—before it can discover the LCP resource and could start loading it. This is never optimal.

To eliminate unnecessary resource load delay, your LCP resource should always be discoverable from the HTML source. In cases where the resource is only referenced from an external CSS or JavaScript file, then the LCP resource should be preloaded, with a high fetch priority (more on fetch priority in the next section); for example:

<!-- Load the stylesheet that will reference the LCP image. -->
<link rel="stylesheet" href="/path/to/styles.css">

<!-- Preload the LCP image with a high fetchpriority so it starts loading with the stylesheet. -->
<link rel="preload" fetchpriority="high" as="image" href="/path/to/hero-image.webp" type="image/webp">

Optimize the priority the resource is given #

Even if the LCP resource is discoverable from the HTML markup, it still may not start loading as early as the first resource. This can happen if the browser preload scanner's priority heuristics do not recognize that the resource is important, or if it determines that other resources are more important.

For example, you can delay your LCP image via HTML if you set loading="lazy" on your <img> element. Using lazy loading means that the resource will not be loaded until after layout confirms the image is in the viewport and so may begin loading later than it otherwise would.

Even without lazy loading, images are not initially loaded with the highest priority by browsers as they are not render-blocking resources. You can hint to the browser as to which resources are most important via the fetchpriority attribute for resources that could benefit from a higher priority:

<img fetchpriority="high" src="/path/to/hero-image.webp">

It's a good idea to set fetchpriority="high" on an <img> element if you think it's likely to be your page's LCP element—but limit this to just one or two images (based on common desktop and mobile viewport sizes), otherwise the signal becomes meaningless. You can also lower the priority of images that may be early in the document response, but isn't visible due to styling, such as images in carousel slides that are not visible at startup:

<img fetchpriority="low" src="/path/to/carousel-slide-3.webp">

Deprioritizing certain resources can afford more bandwidth to resources that need it more—but be careful. Always check resource priority in DevTools and test changes with lab and field tools.

After you have optimized your LCP resource priority and discovery time, your network waterfall should look like this (with the LCP resource starting at the same time as the first resource):

2. Eliminate element render delay #

The goal in this step is to ensure the LCP element can render immediately after its resource has finished loading, no matter when that happens.

The primary reason the LCP element wouldn't be able to render immediately after its resource finishes loading is if rendering is blocked for some other reason:

Rendering of the entire page is blocked due to stylesheets or synchronous scripts in the <head> that are still loading.
The LCP resource has finished loading, but the LCP element has not yet been added to the DOM (it's waiting for some JavaScript code to load).
The element is being hidden by some other code, such as an A/B testing library that's still determining what experiment the user should be in.
The main thread is blocked due to long tasks, and rendering work needs to wait until those long tasks complete.

The following sections explain how to address the most common causes of unnecessary element render delay.

Reduce or inline render-blocking stylesheets #

Stylesheets loaded from the HTML markup will block rendering of all content that follows them, which is good, since you generally do not want to render unstyled HTML. However, if the stylesheet is so large that it takes significantly longer to load than the LCP resource, then it will prevent the LCP element from rendering—even after its resource has finished loading, as shown in this example:

To fix this, your options are to either:

inline the stylesheet into the HTML to avoid the additional network request; or,
reduce the size of the stylesheet.

In general, inlining your stylesheet is only recommended if your stylesheet is small since inlined content in the HTML cannot benefit from caching in subsequent page loads. If a stylesheet is so large that it takes longer to load than the LCP resource, then it's unlikely to be a good candidate for inlining.

In most cases, the best way to ensure the stylesheet does not block rendering of the LCP element is to reduce its size so that it's smaller than the LCP resource. This should ensure it's not a bottleneck for most visits.

Some recommendations to reduce the size of the stylesheet are:

Remove unused CSS: use Chrome DevTools to find CSS rules that aren't being used and can potentially be removed (or deferred).
Defer non-critical CSS: split your stylesheet out into styles that are required for initial page load and then styles that can be loaded lazily.
Minify and compress CSS: for styles that are critical, make sure you're reducing their transfer size as much as possible.

Defer or inline render-blocking JavaScript #

It is almost never necessary to add synchronous scripts (scripts without the async or defer attributes) to the <head> of your pages, and doing so will almost always have a negative impact on performance.

In cases where JavaScript code needs to run as early as possible in the page load, it's best to inline it so rendering isn't delayed waiting on another network request. As with stylesheets, though, you should only inline scripts if they're very small.

Don't

<head>
  <script src="/path/to/main.js"></script>
</head>

<head>
  <script>
    // Inline script contents directly in the HTML.
    // IMPORTANT: only do this for very small scripts.
  </script>
</head>

Use server-side rendering #

Server-side rendering (SSR) is the process of running your client-side application logic on the server and responding to HTML document requests with the full HTML markup.

From the perspective of optimizing LCP, there are two primary advantage of SSR:

Your image resources will be discoverable from the HTML source (as discussed in step 1 earlier).
Your page content will not require additional JavaScript requests to finish before it can render.

The main downside of SSR is it requires additional server processing time, which can slow down your TTFB. This trade-off is usually worth it though because server processing times are within your control, whereas the network and device capabilities of your users are not.

A similar option to SSR is called static site generation (SSG) or prerendering. This is the process of generating your HTML pages in a build step rather than on-demand. If prerendering is possible with your architecture, it's generally a better choice for performance.

Break up long tasks #

Even if you've followed the above advice, and your JavaScript code is not render-blocking nor is it responsible for rendering your elements, it can still delay LCP.

The most common reason this happens is when pages load large JavaScript files, which need to be parsed and executed on the browser's main thread. This means that, even if your image resource is fully downloaded, it may still have to wait until an unrelated script finishes executing before it can render.

All browsers today render images on the main thread, which means anything that blocks the main thread can also lead to unnecessary element render delay.

3. Reduce resource load time #

The goal of this step is to reduce the time spent transferring the bytes of the resource over the network to the user's device. In general, there are three ways to do that:

Reduce the size of the resource.
Reduce the distance the resource has to travel.
Reduce contention for network bandwidth.
Eliminate the network time entirely.

Reduce the size of the resource #

The LCP resource of a page (if it has one) will either be an image or a web font. The following guides go into great detail about how to reduce the size of both:

Reduce the distance the resource has to travel #

In addition to reducing the size of a resource, you can also reduce the load times by getting your servers as geographically close to your users as possible. And the best way to do that is to use a content delivery network (CDN).

In fact, image CDNs in particular are a great choice because they not only reduce the distance the resource has to travel, but they also generally reduce the size of the resource—automatically implementing all of the size-reduction recommendations from earlier for you.

Reduce contention for network bandwidth #

Even if you've reduced the size of your resource and the distance it has to travel, a resource can still take a long time to load if you're loading many other resources at the same time. This problem is known as network contention.

If you've given your LCP resource a high fetchpriority and started loading it as soon as possible then the browser will do its best to prevent lower-priority resources from competing with it. However, if you're loading many resources with high fetchpriority, or if you're just loading a lot of resources in general, then it could affect how quickly the LCP resource loads.

Eliminate the network time entirely #

The best way to reduce resource load times is to eliminate the network entirely from the process. If you serve your resources with an efficient cache-control policy, then visitors who request those resources a second time will have them served from the cache—bringing the resource load time to essentially zero!

And if your LCP resource is a web font, in addition to reducing web font size, you should also consider whether you need to block rendering on the web font resource load. If you set a font-display value of anything other than auto or block, then text will always be visible during load, and LCP will not be blocked on an additional network request.

Finally, if your LCP resource is small, it may make sense to inline the resources as a data URL, which will also eliminate the additional network request. However, using data URLs comes with caveats because then the resources cannot be cached and in some cases can lead to longer render delays because of the additional decode cost.

4. Reduce time to first byte #

The goal of this step is to deliver the initial HTML as quickly as possible. This step is listed last because it's often the one developers have the least control over. However, it's also one of the most important steps because it directly affects every step that comes after it. Nothing can happen on the frontend until the backend delivers that first byte of content, so anything you can do to speed up your TTFB will improve every other load metric as well.

A common cause of a slow TTFB for an otherwise fast site is making visitors wade through several redirects before finally arriving at the final URL. This can happen when you have visitors from advertisements, or via URL shorteners. Always try to minimize the number of redirects a visitor must wait through.

Another common cause is when cached content cannot be used from a CDN edge server, and all requests must be directed all the way back to the origin server. This can happen if unique URL parameters are used by visitors for analytics—even if they do not result in different pages.

For specific guidance on this topic, see Optimize TTFB.

Monitor LCP breakdown in JavaScript #

The timing information for all of the LCP sub-parts discussed above is available to you in JavaScript through a combination of the following performance APIs:

The benefit to computing these timing values in JavaScript is it allows you to send them to an analytics provider or log them to your developer tools to help with debugging and optimizing.

For example, the following screenshot uses the performance.measure() method from the User Timing API to add bars to the Timings track in the Chrome DevTools Performance panel.

Visualizations in the timings track are particularly helpful when looked at alongside the Network and Main thread tracks, because you can see at a glance what else is happening on the page during these timespans.

In addition to visualizing the LCP sub-parts in the timings track, you can also use JavaScript to compute what percentage each sub-part is of the total LCP time. With that information, you can determine whether your pages are meeting the recommended percentage breakdowns described earlier.

This screenshot shows an example that logs the total time of each LCP sub-part, as well as its percentage of the total LCP time to the console.

Both of these visualizations were created with the following code:

const LCP_SUB_PARTS = [
  'Time to first byte',
  'Resource load delay',
  'Resource load time',
  'Element render delay',
];

new PerformanceObserver((list) => {
  const lcpEntry = list.getEntries().at(-1);
  const navEntry = performance.getEntriesByType('navigation')[0];
  const lcpResEntry = performance
    .getEntriesByType('resource')
    .filter((e) => e.name === lcpEntry.url)[0];

  // Ignore LCP entries that aren't images to reduce DevTools noise.
  // Comment this line out if you want to include text entries.
  if (!lcpEntry.url) return;

  // Compute the start and end times of each LCP sub-part.
  // WARNING! If your LCP resource is loaded cross-origin, make sure to add
  // the `Timing-Allow-Origin` (TAO) header to get the most accurate results.
  const ttfb = navEntry.responseStart;
  const lcpRequestStart = Math.max(
    ttfb,
    // Prefer `requestStart` (if TOA is set), otherwise use `startTime`.
    lcpResEntry ? lcpResEntry.requestStart || lcpResEntry.startTime : 0
  );
  const lcpResponseEnd = Math.max(
    lcpRequestStart,
    lcpResEntry ? lcpResEntry.responseEnd : 0
  );
  const lcpRenderTime = Math.max(
    lcpResponseEnd,
    // Use LCP startTime (which is the final LCP time) as sometimes
    // slight differences between loadTime/renderTime and startTime
    // due to rounding precision.
    lcpEntry ? lcpEntry.startTime : 0
  );

  // Clear previous measures before making new ones.
  // Note: due to a bug this does not work in Chrome DevTools.
  LCP_SUB_PARTS.forEach((part) => performance.clearMeasures(part));

  // Create measures for each LCP sub-part for easier
  // visualization in the Chrome DevTools Performance panel.
  const lcpSubPartMeasures = [
    performance.measure(LCP_SUB_PARTS[0], {
      start: 0,
      end: ttfb,
    }),
    performance.measure(LCP_SUB_PARTS[1], {
      start: ttfb,
      end: lcpRequestStart,
    }),
    performance.measure(LCP_SUB_PARTS[2], {
      start: lcpRequestStart,
      end: lcpResponseEnd,
    }),
    performance.measure(LCP_SUB_PARTS[3], {
      start: lcpResponseEnd,
      end: lcpRenderTime,
    }),
  ];

  // Log helpful debug information to the console.
  console.log('LCP value: ', lcpRenderTime);
  console.log('LCP element: ', lcpEntry.element, lcpEntry.url);
  console.table(
    lcpSubPartMeasures.map((measure) => ({
      'LCP sub-part': measure.name,
      'Time (ms)': measure.duration,
      '% of LCP': `${
        Math.round((1000 * measure.duration) / lcpRenderTime) / 10
      }%`,
    }))
  );
}).observe({type: 'largest-contentful-paint', buffered: true});

You can use this code as-is for local debugging, or modify it to send this data to an analytics provider so you can get a better understanding of what the breakdown of LCP is on your pages for real users.

Monitor LCP breakdown via the Web Vitals extension #

The Web Vitals extension will log the LCP time, LCP element, and these four sub-parts in the console logging, to easily allow you to see this breakdown.

Summary #

LCP is complex, and its timing can be affected by a number of factors. But if you consider that optimizing LCP is primarily about optimizing the load of the LCP resource, it can significantly simplify things.

At a high level, optimizing LCP can be summarized in four steps:

Ensure the LCP resource starts loading as early as possible.
Ensure the LCP element can render as soon as its resource finishes loading.
Reduce the load time of the LCP resource as much as you can without sacrificing quality.
Deliver the initial HTML document as fast as possible.

If you’re able to follow these steps on your pages, then you should feel confident that you’re delivering an optimal loading experience to your users, and you should see that reflected in your real-world LCP scores.

Web Vitals

2020-04-30T00:00:00Z

Optimizing for quality of user experience is key to the long-term success of any site on the web. Whether you're a business owner, marketer, or developer, Web Vitals can help you quantify the experience of your site and identify opportunities to improve.

Overview #

Web Vitals is an initiative by Google to provide unified guidance for quality signals that are essential to delivering a great user experience on the web.

Google has provided a number of tools over the years to measure and report on performance. Some developers are experts at using these tools, while others have found the abundance of both tools and metrics challenging to keep up with.

Site owners should not have to be performance experts to understand the quality of experience they are delivering to their users. The Web Vitals initiative aims to simplify the landscape, and help sites focus on the metrics that matter most, the Core Web Vitals.

Core Web Vitals #

Core Web Vitals are the subset of Web Vitals that apply to all web pages, should be measured by all site owners, and will be surfaced across all Google tools. Each of the Core Web Vitals represents a distinct facet of the user experience, is measurable in the field, and reflects the real-world experience of a critical user-centric outcome.

The metrics that make up Core Web Vitals will evolve over time. The current set for 2020 focuses on three aspects of the user experience—loading, interactivity, and visual stability—and includes the following metrics (and their respective thresholds):

Largest Contentful Paint (LCP): measures loading performance. To provide a good user experience, LCP should occur within 2.5 seconds of when the page first starts loading.
First Input Delay (FID): measures interactivity. To provide a good user experience, pages should have a FID of 100 milliseconds or less.
Cumulative Layout Shift (CLS): measures visual stability. To provide a good user experience, pages should maintain a CLS of 0.1. or less.

For each of the above metrics, to ensure you're hitting the recommended target for most of your users, a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.

Tools that assess Core Web Vitals compliance should consider a page passing if it meets the recommended targets at the 75th percentile for all of the above three metrics.

Lifecycle #

Metrics on the Core Web Vitals track go through a lifecycle consisting of three phases: experimental, pending, and stable.

The table below reflects where all Core Web Vitals currently are in their lifecycle:

Experimental	Pending	Stable
	INP	LCP CLS FID

Each phase is designed to signal to developers how they should think about each metric:

Experimental metrics are prospective Core Web Vitals that may still be undergoing significant changes depending on testing and community feedback.
Pending metrics are future Core Web Vitals that have passed the testing and feedback stage and have a well-defined timeline to becoming stable.
Stable metrics are the current set of Core Web Vitals that Chrome considers essential for great user experiences.

Experimental #

When a metric is initially developed and enters the ecosystem, it is considered an experimental metric.

The purpose of the experimental phase is to assess a metric's fitness, first by exploring the problem to be solved, and possibly iterate on what previous metrics may have failed to address. For example, Interaction to Next Paint (INP) was initially developed as an experimental metric to address the runtime performance issues present on the web more comprehensively than First Input Delay (FID).

The experimental phase of Core Web Vitals lifecycle is also intended to give flexibility in a metric's development by identifying bugs and even exploring changes to its initial definition. It's also the phase in which community feedback is most important.

Pending #

When the Chrome team determines that an experimental metric has received sufficient feedback and proven its efficacy, it becomes a pending metric. Pending metrics are held in this phase for a minimum of six months to give the ecosystem time to adapt. The only remaining hurdle for a metric to advance beyond the pending phase is to wait out the transition period. Community feedback remains an important aspect of this phase, as more developers begin to use the metric.

Stable #

When a Core Web Vital candidate metric is finalized, it becomes a stable metric—for metrics that are on the Core Web Vitals track, this means the metric becomes a Core Web Vital.

Stable metrics are actively supported, and may be subject to bug fixes and definition changes. Stable Core Web Vitals metrics won't change more than once per year. Any change to a Core Web Vital will be clearly communicated in the metric's official documentation, as well as in the metric's CHANGELOG. Core Web Vitals are also included in any assessments.

Tools to measure and report Core Web Vitals #

Google believes that the Core Web Vitals are critical to all web experiences. As a result, it is committed to surfacing these metrics in all of its popular tools. The following sections details which tools support the Core Web Vitals.

Field tools to measure Core Web Vitals #

The Chrome User Experience Report collects anonymized, real user measurement data for each Core Web Vital. This data enables site owners to quickly assess their performance without requiring them to manually instrument analytics on their pages, and powers tools like PageSpeed Insights, and Search Console's Core Web Vitals report.

	LCP	FID	CLS
Chrome User Experience Report	✔	✔	✔
PageSpeed Insights	✔	✔	✔
Search Console (Core Web Vitals report)	✔	✔	✔

The data provided by Chrome User Experience Report offers a quick way to assess the performance of sites, but it does not provide the detailed, per-pageview telemetry that is often necessary to accurately diagnose, monitor, and quickly react to regressions. As a result, we strongly recommend that sites set up their own real-user monitoring.

Measure Core Web Vitals in JavaScript #

Each of the Core Web Vitals can be measured in JavaScript using standard web APIs.

The easiest way to measure all the Core Web Vitals is to use the web-vitals JavaScript library, a small, production-ready wrapper around the underlying web APIs that measures each metric in a way that accurately matches how they're reported by all the Google tools listed above.

With the web-vitals library, measuring each metric is as simple as calling a single function (see the documentation for complete usage and API details):

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

function sendToAnalytics(metric) {
  const body = JSON.stringify(metric);
  // Use `navigator.sendBeacon()` if available, falling back to `fetch()`.
  (navigator.sendBeacon && navigator.sendBeacon('/analytics', body)) ||
    fetch('/analytics', {body, method: 'POST', keepalive: true});
}

onCLS(sendToAnalytics);
onFID(sendToAnalytics);
onLCP(sendToAnalytics);

Once you've configured your site to use the web-vitals library to measure and send your Core Web Vitals data to an analytics endpoint, the next step is to aggregate and report on that data to see if your pages are meeting the recommended thresholds for at least 75% of page visits.

While some analytics providers have built-in support for Core Web Vitals metrics, even those that don't should include basic custom metric features that allow you to measure Core Web Vitals in their tool.

One example of this is the Web Vitals Report, which allows site owners to measure their Core Web Vitals using Google Analytics. For guidance on measuring Core Web Vitals using other analytics tools, see Best practices for measuring Web Vitals in the field.

You can also report on each of the Core Web Vitals without writing any code using the Web Vitals Chrome Extension. This extension uses the web-vitals library to measure each of these metrics and display them to users as they browse the web.

This extension can be helpful in understanding the performance of your own sites, your competitor's sites, and the web at large.

	LCP	FID	CLS
web-vitals	✔	✔	✔
Web Vitals Extension	✔	✔	✔

Alternatively, developers who prefer to measure these metrics directly via the underlying web APIs can refer to these metric guides for implementation details:

Lab tools to measure Core Web Vitals #

While all of the Core Web Vitals are, first and foremost, field metrics, many of them are also measurable in the lab.

Lab measurement is the best way to test the performance of features during development—before they've been released to users. It's also the best way to catch performance regressions before they happen.

The following tools can be used to measure the Core Web Vitals in a lab environment:

	LCP	FID	CLS
Chrome DevTools	✔	✘ (use TBT instead)	✔
Lighthouse	✔	✘ (use TBT instead)	✔

While lab measurement is an essential part of delivering great experiences, it is not a substitute for field measurement.

The performance of a site can vary dramatically based on a user's device capabilities, their network conditions, what other processes may be running on the device, and how they're interacting with the page. In fact, each of the Core Web Vitals metrics can have its score affected by user interaction. Only field measurement can accurately capture the complete picture.

Recommendations for improving your scores #

Once you've measured the Core Web Vitals and identified areas for improvement, the next step is to optimize. The following guides offer specific recommendations for how to optimize your pages for each of the Core Web Vitals:

Other Web Vitals #

While the Core Web Vitals are the critical metrics for understanding and delivering a great user experience, there are other vital metrics as well.

These other Web Vitals often serve as proxy or supplemental metrics for the Core Web Vitals, to help capture a larger part of the experience or to aid in diagnosing a specific issue.

For example, the metrics Time to First Byte (TTFB) and First Contentful Paint (FCP) are both vital aspects of the loading experience, and are both useful in diagnosing issues with LCP (slow server response times or render-blocking resources, respectively).

Similarly, metrics like Total Blocking Time (TBT) and Time to Interactive (TTI) are lab metrics that are vital in catching and diagnosing potential interactivity issues that will impact FID. However, they are not part of the Core Web Vitals set because they are not field-measurable, nor do they reflect a user-centric outcome.

Evolving Web Vitals #

Web Vitals and Core Web Vitals represent the best available signals developers have today to measure quality of experience across the web, but these signals are not perfect and future improvements or additions should be expected.

The Core Web Vitals are relevant to all web pages and featured across relevant Google tools. Changes to these metrics will have wide-reaching impact; as such, developers should expect the definitions and thresholds of the Core Web Vitals to be stable, and updates to have prior notice and a predictable, annual cadence.

The other Web Vitals are often context or tool specific, and may be more experimental than the Core Web Vitals. As such, their definitions and thresholds may change with greater frequency.

For all Web Vitals, changes will be clearly documented in this public CHANGELOG.

User-centric performance metrics

2019-11-08T00:00:00Z

We've all heard how important performance is. But when we talk about performance—and about making websites "fast"—what specifically do we mean?

The truth is performance is relative:

A site might be fast for one user (on a fast network with a powerful device) but slow for another user (on a slow network with a low-end device).
Two sites may finish loading in the exact same amount of time, yet one may seem to load faster (if it loads content progressively rather than waiting until the end to display anything).
A site might appear to load quickly but then respond slowly (or not at all) to user interaction.

So when talking about performance, it's important to be precise and to refer to performance in terms of objective criteria that can be quantitatively measured. These criteria are known as metrics.

But just because a metric is based on objective criteria and can be quantitatively measured, it doesn't necessarily mean those measurements are useful.

Defining metrics #

Historically, web performance has been measured with the load event. However, even though load is a well-defined moment in a page's lifecycle, that moment doesn't necessarily correspond with anything the user cares about.

For example, a server could respond with a minimal page that "loads" immediately but then defers fetching content and displaying anything on the page until several seconds after the load event fires. While such a page might technically have a fast load time, that time would not correspond to how a user actually experiences the page loading.

Over the past few years, members of the Chrome team—in collaboration with the W3C Web Performance Working Group—have been working to standardize a set of new APIs and metrics that more accurately measure how users experience the performance of a web page.

To help ensure the metrics are relevant to users, we frame them around a few key questions:

Is it happening?	Did the navigation start successfully? Has the server responded?
Is it useful?	Has enough content rendered that users can engage with it?
Is it usable?	Can users interact with the page, or is it busy?
Is it delightful?	Are the interactions smooth and natural, free of lag and jank?

How metrics are measured #

Performance metrics are generally measured in one of two ways:

In the lab: using tools to simulate a page load in a consistent, controlled environment
In the field: on real users actually loading and interacting with the page

Neither of these options is necessarily better or worse than the other—in fact you generally want to use both to ensure good performance.

In the lab #

Testing performance in the lab is essential when developing new features. Before features are released in production, it's impossible to measure their performance characteristics on real users, so testing them in the lab before the feature is released is the best way to prevent performance regressions.

In the field #

On the other hand, while testing in the lab is a reasonable proxy for performance, it isn't necessarily reflective of how all users experience your site in the wild.

The performance of a site can vary dramatically based on a user's device capabilities and their network conditions. It can also vary based on whether (or how) a user is interacting with the page.

Moreover, page loads may not be deterministic. For example, sites that load personalized content or ads may experience vastly different performance characteristics from user to user. A lab test will not capture those differences.

The only way to truly know how your site performs for your users is to actually measure its performance as those users are loading and interacting with it. This type of measurement is commonly referred to as Real User Monitoring—or RUM for short.

Types of metrics #

There are several other types of metrics that are relevant to how users perceive performance.

Perceived load speed: how quickly a page can load and render all of its visual elements to the screen.
Load responsiveness: how quickly a page can load and execute any required JavaScript code in order for components to respond quickly to user interaction
Runtime responsiveness: after page load, how quickly can the page respond to user interaction.
Visual stability: do elements on the page shift in ways that users don't expect and potentially interfere with their interactions?
Smoothness: do transitions and animations render at a consistent frame rate and flow fluidly from one state to the next?

Given all the above types of performance metrics, it's hopefully clear that no single metric is sufficient to capture all the performance characteristics of a page.

Important metrics to measure #

First Contentful Paint (FCP): measures the time from when the page starts loading to when any part of the page's content is rendered on the screen. (lab, field)
Largest Contentful Paint (LCP): measures the time from when the page starts loading to when the largest text block or image element is rendered on the screen. (lab, field)
First Input Delay (FID): measures the time from when a user first interacts with your site (when they click a link, tap a button, or use a custom, JavaScript-powered control) to the time when the browser is actually able to respond to that interaction. (field)
Interaction to Next Paint (INP): measures the latency of every tap, click, or keyboard interaction made with the page, and—based on the number of interactions—selects the worst interaction latency of the page (or close to the highest) as a single, representative value to describe a page's overall responsiveness. (lab, field)
Time to Interactive (TTI): measures the time from when the page starts loading to when it's visually rendered, its initial scripts (if any) have loaded, and it's capable of reliably responding to user input quickly. (lab)
Total Blocking Time (TBT): measures the total amount of time between FCP and TTI where the main thread was blocked for long enough to prevent input responsiveness. (lab)
Cumulative Layout Shift (CLS): measures the cumulative score of all unexpected layout shifts that occur between when the page starts loading and when its lifecycle state changes to hidden. (lab, field)
Time to First Byte (TTFB): measures the time it takes for the network to respond to a user request with the first byte of a resource. (lab, field)

While this list includes metrics measuring many of the various aspects of performance relevant to users, it does not include everything. For example, runtime responsiveness and smoothness are not currently covered.

In some cases, new metrics will be introduced to cover missing areas, but in other cases the best metrics are ones specifically tailored to your site.

Custom metrics #

The performance metrics listed above are good for getting a general understanding of the performance characteristics of most sites on the web. They're also good for having a common set of metrics for sites to compare their performance against their competitors.

However, there may be times when a specific site is unique in some way that requires additional metrics to capture the full performance picture. For example, the LCP metric is intended to measure when a page's main content has finished loading, but there could be cases where the largest element is not part of the page's main content and thus LCP may not be relevant.

To address such cases, the Web Performance Working Group has also standardized lower-level APIs that can be useful for implementing your own custom metrics:

Refer to the guide on Custom Metrics to learn how to use these APIs to measure performance characteristics specific to your site.

Custom metrics

2019-11-08T00:00:00Z

There's a lot of value in having user-centric metrics that you can measure, universally, on any given website. These metrics allow you to:

Understand how real users experience the web as a whole
Easily compare your site to a competitor's
Track useful and actionable data in your analytics tools without needing to write custom code

Universal metrics offer a good baseline, but in many cases you need to measure more than just these metrics in order to capture the full experience for your particular site.

Custom metrics allow you to measure aspects of your site's experience that may only apply to your site, such as:

How long it takes for a single page app (SPA) to transition from one "page" to another
How long it takes for a page to display data fetched from a database for logged-in users
How long it takes for a server-side-rendered (SSR) app to hydrate
The cache hit rate for resources loaded by returning visitors
The event latency of click or keyboard events in a game

APIs to measure custom metrics #

Historically web developers haven't had many low-level APIs to measure performance, and as a result they've had to resort to hacks in order to measure whether a site was performing well.

For example, it's possible to determine whether the main thread is blocked due to long-running JavaScript tasks by running a requestAnimationFrame loop and calculating the delta between each frame. If the delta is significantly longer than the display's framerate, you can report that as a long task. Such hacks are not recommended, though, because they actually affect performance themselves (by draining battery, for example).

The first rule of effective performance measurement is to make sure your performance measurement techniques aren't causing performance issues themselves. So for any custom metrics you measure on your site, it's best to use one of the following APIs if possible.

Performance Observer #

Browser support

Chrome 52, Supported 52
Firefox 57, Supported 57
Edge 79, Supported 79
Safari 11, Supported 11

Source

Understanding the PerformanceObserver API is critical to creating custom performance metrics because it's the mechanism by which you get data from all other performance APIs discussed in this article.

With PerformanceObserver you can subscribe passively to performance-related events, which means these APIs generally will not interfere with the performance of the page, as their callbacks are generally fired during idle periods.

You create a PerformanceObserver by passing it a callback to be run whenever new performance entries are dispatched. Then you tell the observer what types of entries to listen for via the observe() method:

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // Log the entry and all associated details.
      console.log(entry.toJSON());
    }
  });

  po.observe({type: 'some-entry-type'});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

The sections below list all the various entry types available for observing, but in newer browsers you can inspect what entry types are available via the static PerformanceObserver.supportedEntryTypes property.

Observing entries that already happened #

By default, PerformanceObserver objects can only observe entries as they occur. This can be problematic if you want to load your performance analytics code lazily (to not block higher-priority resources).

To get historical entries (after they've occurred), set the buffered flag to true when you call observe(). The browser will include historical entries from its performance entry buffer the first time that your PerformanceObserver callback is called.

po.observe({
  type: 'some-entry-type',
  buffered: true,
});

Legacy performance APIs to avoid #

Prior to the Performance Observer API, developers could access performance entries using the following three methods defined on the performance object:

While these APIs are still supported, their usage is not recommended because they don't allow you to listen for when new entries are emitted. In addition, many new APIs (such as Long Tasks) are not exposed via the performance object, they're only exposed via PerformanceObserver.

Unless you specifically need Internet Explorer compatibility, it's best to avoid these methods in your code and use PerformanceObserver going forward.

User Timing API #

The User Timing API is your general purpose measurement API for time-based metrics. It allows you to arbitrarily mark points in time and then later measure the duration between those marks.

// Record the time immediately before running a task.
performance.mark('myTask:start');
await doMyTask();
// Record the time immediately after running a task.
performance.mark('myTask:end');

// Measure the delta between the start and end of the task
performance.measure('myTask', 'myTask:start', 'myTask:end');

While APIs like Date.now() or performance.now() give you similar abilities, the benefit of using the User Timing API is it integrates well with performance tooling. For example, Chrome DevTools visualizes User Timing measurements in the Performance panel, and many analytics providers will also automatically track any measurements you make and send the duration data to their analytics back end.

To report User Timing measurements, you can use PerformanceObserver and register to observe entries of type measure:

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // Log the entry and all associated details.
      console.log(entry.toJSON());
    }
  });
  // Start listening for `measure` entries to be dispatched.
  po.observe({type: 'measure', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

Long Tasks API #

Browser support

Chrome 58, Supported 58
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

The Long Tasks API is useful for knowing when the browser's main thread is blocked for long enough to affect frame rate or input latency. Currently the API will report any tasks that execute for longer than 50 milliseconds (ms).

Anytime you need to run expensive code (or load and execute large scripts) it's useful to track whether or not that code blocked the main thread. In fact, many higher-level metrics are built on top of the Long Tasks API themselves (such as Time to Interactive (TTI) and Total Blocking Time (TBT)).

To determine when long tasks happen, you can use PerformanceObserver and register to observe entries of type longtask:

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // Log the entry and all associated details.
      console.log(entry.toJSON());
    }
  });
  // Start listening for `longtask` entries to be dispatched.
  po.observe({type: 'longtask', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

Element Timing API #

Browser support

Chrome 77, Supported 77
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

The Largest Contentful Paint (LCP) metric is useful for knowing when the largest image or text block was painted to the screen, but in some cases you want to measure the render time of a different element.

For these cases, you can use the Element Timing API. In fact, the Largest Contentful Paint API is actually built on top of the Element Timing API and adds automatic reporting of the largest contentful element, but you can report on additional elements by explicitly adding the elementtiming attribute to them, and registering a PerformanceObserver to observe the element entry type.

<img elementtiming="hero-image" />
<p elementtiming="important-paragraph">This is text I care about.</p>
...
<script>
// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((entryList) => {
    for (const entry of entryList.getEntries()) {
      // Log the entry and all associated details.
      console.log(entry.toJSON());
    }
  });
  // Start listening for `element` entries to be dispatched.
  po.observe({type: 'element', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}
</script>

Event Timing API #

The First Input Delay (FID) metric measures the time from when a user first interacts with a page to the time when the browser is actually able to begin processing event handlers in response to that interaction. However, in some cases it may also be useful to measure the event processing time itself as well as the time until the next frame can be rendered.

This is possible with the Event Timing API (which is used to measure FID) as it exposes a number of timestamps in the event lifecycle, including:

startTime: the time when the browser receives the event.
processingStart: the time when the browser is able to begin processing event handlers for the event.
processingEnd: time when the browser finishes executing all synchronous code initiated from event handlers for this event.
duration: the time (rounded to 8ms for security reasons) between when the browser receives the event until it's able to paint the next frame after finishing executing all synchronous code initiated from the event handlers.

The following example shows how to use these these values to create custom measurements:

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  const po = new PerformanceObserver((entryList) => {
    const firstInput = entryList.getEntries()[0];

    // Measure First Input Delay (FID).
    const firstInputDelay = firstInput.processingStart - firstInput.startTime;

    // Measure the time it takes to run all event handlers
    // Note: this does not include work scheduled asynchronously using
    // methods like `requestAnimationFrame()` or `setTimeout()`.
    const firstInputProcessingTime = firstInput.processingEnd - firstInput.processingStart;

    // Measure the entire duration of the event, from when input is received by
    // the browser until the next frame can be painted after processing all
    // event handlers.
    // Note: similar to above, this value does not include work scheduled
    // asynchronously using `requestAnimationFrame()` or `setTimeout()`.
    // And for security reasons, this value is rounded to the nearest 8ms.
    const firstInputDuration = firstInput.duration;

    // Log these values the console.
    console.log({
      firstInputDelay,
      firstInputProcessingTime,
      firstInputDuration,
    });
  });

  po.observe({type: 'first-input', buffered: true});
} catch (error) {
  // Do nothing if the browser doesn't support this API.
}

Resource Timing API #

The Resource Timing API gives developers detailed insight into how resources for a particular page were loaded. Despite the name of the API, the information it provides is not just limited to timing data (though there's plenty of that). Other data you can access includes:

initiatorType: how the resource was fetched: such as from a <script> or <link> tag, or from fetch()
nextHopProtocol: the protocol used to fetch the resource, such as h2 or quic
encodedBodySize/decodedBodySize]: the size of the resource in its encoded or decoded form (respectively)
transferSize: the size of the resource that was actually transferred over the network. When resources are fulfilled via the cache, this value can be much smaller than the encodedBodySize, and in some cases it can be zero (if no cache revalidation is required).

Note, you can use the transferSize property of resource timing entries to measure a cache hit rate metric or perhaps even a total cached resource size metric, which may be useful in understanding how your resource caching strategy affects performance for repeat visitors.

The following example logs all resources requested by the page and indicates whether or not each resource was fulfilled via the cache.

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // If transferSize is 0, the resource was fulfilled via the cache.
      console.log(entry.name, entry.transferSize === 0);
    }
  });
  // Start listening for `resource` entries to be dispatched.
  po.observe({type: 'resource', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

Browser support

Chrome 57, Supported 57
Firefox 58, Supported 58
Edge 12, Supported 12
Safari 15, Supported 15

Source

The Navigation Timing API is similar to the Resource Timing API, but it reports only navigation requests. The navigation entry type is also similar to the resource entry type, but it contains some additional information specific to only navigation requests (such as when the DOMContentLoaded and load events fire).

One metric many developers track to understand server response time (Time to First Byte) is available via the Navigation Timing API—specifically it's entry's responseStart timestamp.

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // If transferSize is 0, the resource was fulfilled via the cache.
      console.log('Time to first byte', entry.responseStart);
    }
  });
  // Start listening for `navigation` entries to be dispatched.
  po.observe({type: 'navigation', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

Another metric developers who use service worker may care about is the service worker startup time for navigation requests. This is the amount of time it takes the browser to start the service worker thread before it can start intercepting fetch events.

The service worker startup time for a particular navigation request can be determined from the delta between entry.responseStart and entry.workerStart.

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      console.log('Service Worker startup time:',
          entry.responseStart - entry.workerStart);
    }
  });
  // Start listening for `navigation` entries to be dispatched.
  po.observe({type: 'navigation', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

Server Timing API #

The Server Timing API allows you to pass request-specific timing data from your server to the browser via response headers. For example, you can indicate how long it took to lookup data in a database for a particular request—which can be useful in debugging performance issues caused by slowness on the server.

For developers who use third-party analytics providers, the Server Timing API is the only way to correlate server performance data with other business metrics that these analytics tools may be measuring.

To specify server timing data in your responses, you can use the Server-Timing response header. Here's an example.

HTTP/1.1 200 OK

Server-Timing: miss, db;dur=53, app;dur=47.2

Then, from your pages, you can read this data on both resource or navigation entries from the Resource Timing and Navigation Timing APIs.

// Catch errors since some browsers throw when using the new `type` option.
// https://bugs.webkit.org/show_bug.cgi?id=209216
try {
  // Create the performance observer.
  const po = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      // Logs all server timing data for this response
      console.log('Server Timing', entry.serverTiming);
    }
  });
  // Start listening for `navigation` entries to be dispatched.
  po.observe({type: 'navigation', buffered: true});
} catch (e) {
  // Do nothing if the browser doesn't support this API.
}

First Input Delay (FID)

2019-11-07T00:00:00Z

Browser support

Chrome 76, Supported 76
Firefox 89, Supported 89
Edge 79, Supported 79
Safari, Not supported

Source

We all know how important it is to make a good first impression. It's important when meeting new people, and it's also important when building experiences on the web.

On the web, a good first impression can make the difference between someone becoming a loyal user or them leaving and never coming back. The question is, what makes for a good impression, and how do you measure what kind of impression you're likely making on your users?

On the web, first impressions can take a lot of different forms—we have first impressions of a site's design and visual appeal as well as first impressions of its speed and responsiveness.

While it is hard to measure how much users like a site's design with web APIs, measuring its speed and responsiveness is not!

The first impression users have of how fast your site loads can be measured with First Contentful Paint (FCP). But how fast your site can paint pixels to the screen is just part of the story. Equally important is how responsive your site is when users try to interact with those pixels!

The First Input Delay (FID) metric helps measure your user's first impression of your site's interactivity and responsiveness.

What is FID? #

FID measures the time from when a user first interacts with a page (that is, when they click a link, tap on a button, or use a custom, JavaScript-powered control) to the time when the browser is actually able to begin processing event handlers in response to that interaction.

What is a good FID score? #

To provide a good user experience, sites should strive to have a First Input Delay of 100 milliseconds or less. To ensure you're hitting this target for most of your users, a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.

FID in detail #

As developers who write code that responds to events, we often assume our code is going to be run immediately—as soon as the event happens. But as users, we've all frequently experienced the opposite—we've loaded a web page on our phone, tried to interact with it, and then been frustrated when nothing happened.

In general, input delay (a.k.a. input latency) happens because the browser's main thread is busy doing something else, so it can't (yet) respond to the user. One common reason this might happen is the browser is busy parsing and executing a large JavaScript file loaded by your app. While it's doing that, it can't run any event listeners because the JavaScript it's loading might tell it to do something else.

Consider the following timeline of a typical web page load:

The above visualization shows a page that's making a couple of network requests for resources (most likely CSS and JS files), and—after those resources are finished downloading—they're processed on the main thread.

This results in periods where the main thread is momentarily busy, which is indicated by the beige-colored task blocks.

Long first input delays typically occur between First Contentful Paint (FCP) and Time to Interactive (TTI) because the page has rendered some of its content but isn't yet reliably interactive. To illustrate how this can happen, FCP and TTI have been added to the timeline:

You may have noticed that there's a fair amount of time (including three long tasks) between FCP and TTI, if a user tries to interact with the page during that time (for example, by clicking on a link), there will be a delay between when the click is received and when the main thread is able to respond.

Consider what would happen if a user tried to interact with the page near the beginning of the longest task:

Because the input occurs while the browser is in the middle of running a task, it has to wait until the task completes before it can respond to the input. The time it must wait is the FID value for this user on this page.

What if an interaction doesn't have an event listener? #

FID measures the delta between when an input event is received and when the main thread is next idle. This means FID is measured even in cases where an event listener has not been registered. The reason is because many user interactions do not require an event listener but do require the main thread to be idle in order to run.

For example, all of the following HTML elements need to wait for in-progress tasks on the main thread to complete prior to responding to user interactions:

Text fields, checkboxes, and radio buttons (<input>, <textarea>)
Select dropdowns (<select>)
links (<a>)

Why only consider the first input? #

While a delay from any input can lead to a bad user experience, we primarily recommend measuring the first input delay for a few reasons:

The first input delay will be the user's first impression of your site's responsiveness, and first impressions are critical in shaping our overall impression of a site's quality and reliability.
The biggest interactivity issues we see on the web today occur during page load. Therefore, we believe initially focusing on improving site's first user interaction will have the greatest impact on improving the overall interactivity of the web.
The recommended solutions for how sites should fix high first input delays (code splitting, loading less JavaScript upfront, etc.) are not necessarily the same solutions for fixing slow input delays after page load. By separating out these metrics we'll be able to provide more specific performance guidelines to web developers.

What counts as a first input? #

FID is a metric that measures a page's responsiveness during load. As such, it only focuses on input events from discrete actions like clicks, taps, and key presses.

Other interactions, like scrolling and zooming, are continuous actions and have completely different performance constraints (also, browsers are often able to hide their latency by running them on a separate thread).

To put this another way, FID focuses on the R (responsiveness) in the RAIL performance model, whereas scrolling and zooming are more related to A (animation), and their performance qualities should be evaluated separately.

What if a user never interacts with your site? #

Not all users will interact with your site every time they visit. And not all interactions are relevant to FID (as mentioned in the previous section). In addition, some user's first interactions will be at bad times (when the main thread is busy for an extended period of time), and some user's first interactions will be at good times (when the main thread is completely idle).

This means some users will have no FID values, some users will have low FID values, and some users will probably have high FID values.

How you track, report on, and analyze FID will probably be quite a bit different from other metrics you may be used to. The next section explains how best to do this.

Why only consider the input delay? #

As mentioned above, FID only measures the "delay" in event processing. It does not measure the event processing time itself nor the time it takes the browser to update the UI after running event handlers.

Even though this time is important to the user and does affect the experience, it's not included in this metric because doing so could incentivize developers to add workarounds that actually make the experience worse—that is, they could wrap their event handler logic in an asynchronous callback (via setTimeout() or requestAnimationFrame()) in order to separate it from the task associated with the event. The result would be an improvement in the metric score but a slower response as perceived by the user.

However, while FID only measure the "delay" portion of event latency, developers who want to track more of the event lifecycle can do so using the Event Timing API. See the guide on custom metrics for more details.

How to measure FID #

FID is a metric that can only be measured in the field, as it requires a real user to interact with your page. You can measure FID with the following tools.

Field tools #

Measure FID in JavaScript #

To measure FID in JavaScript, you can use the Event Timing API. The following example shows how to create a PerformanceObserver that listens for first-input entries and logs them to the console:

new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    const delay = entry.processingStart - entry.startTime;
    console.log('FID candidate:', delay, entry);
  }
}).observe({type: 'first-input', buffered: true});

In the above example, the first-input entry's delay value is measured by taking the delta between the entry's startTime and processingStart timestamps. In most cases this will be the FID value; however, not all first-input entries are valid for measuring FID.

The following section lists the differences between what the API reports and how the metric is calculated.

Differences between the metric and the API #

The API will dispatch first-input entries for pages loaded in a background tab but those pages should be ignored when calculating FID.
The API will also dispatch first-input entries if the page was backgrounded prior to the first input occurring, but those pages should also be ignored when calculating FID (inputs are only considered if the page was in the foreground the entire time).
The API does not report first-input entries when the page is restored from the back/forward cache, but FID should be measured in these cases since users experience them as distinct page visits.
The API does not report inputs that occur within iframes but the metric does as they are part of the user experience of the page. This can show as a difference between CrUX and RUM. To properly measure FID you should consider them. Sub-frames can use the API to report their first-input entries to the parent frame for aggregation.

Rather than memorizing all these subtle differences, developers can use the web-vitals JavaScript library to measure FID, which handles these differences for you (where possible):

import {onFID} from 'web-vitals';

// Measure and log FID as soon as it's available.
onFID(console.log);

You can refer to the source code for onFID() for a complete example of how to measure FID in JavaScript.

Analyzing and reporting on FID data #

Due to the expected variance in FID values, it's critical that when reporting on FID you look at the distribution of values and focus on the higher percentiles.

While choice of percentile for all Core Web Vitals thresholds is the 75th, for FID in particular we still strongly recommend looking at the 95th–99th percentiles, as those will correspond to the particularly bad first experiences users are having with your site. And it will show you the areas that need the most improvement.

This is true even if you segment your reports by device category or type. For example, if you run separate reports for desktop and mobile, the FID value you care most about on desktop should be the 95th–99th percentile of desktop users, and the FID value you care about most on mobile should be the 95th–99th percentile of mobile users.

How to improve FID #

A full guide on optimizing FID is available to guide you through techniques to improve this metric.

CHANGELOG #

Occasionally, bugs are discovered in the APIs used to measure metrics, and sometimes in the definitions of the metrics themselves. As a result, changes must sometimes be made, and these changes can show up as improvements or regressions in your internal reports and dashboards.

To help you manage this, all changes to either the implementation or definition of these metrics will be surfaced in this CHANGELOG.

If you have feedback for these metrics, you can provide it in the web-vitals-feedback Google group.

First Contentful Paint (FCP)

2019-11-07T00:00:00Z

Browser support

Chrome 60, Supported 60
Firefox 84, Supported 84
Edge 79, Supported 79
Safari 14.1, Supported 14.1

Source

What is FCP? #

The First Contentful Paint (FCP) metric measures the time from when the page starts loading to when any part of the page's content is rendered on the screen. For this metric, "content" refers to text, images (including background images), <svg> elements, or non-white <canvas> elements.

In the above load timeline, FCP happens in the second frame, as that's when the first text and image elements are rendered to the screen.

You'll notice that though some of the content has rendered, not all of it has rendered. This is an important distinction to make between First Contentful Paint (FCP) and Largest Contentful Paint (LCP) —which aims to measure when the page's main contents have finished loading.

What is a good FCP score? #

To provide a good user experience, sites should strive to have a First Contentful Paint of 1.8 seconds or less. To ensure you're hitting this target for most of your users, a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.

How to measure FCP #

FCP can be measured in the lab or in the field, and it's available in the following tools:

Field tools #

Lab tools #

Measure FCP in JavaScript #

To measure FCP in JavaScript, you can use the Paint Timing API. The following example shows how to create a PerformanceObserver that listens for a paint entry with the name first-contentful-paint and logs it to the console.

new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntriesByName('first-contentful-paint')) {
    console.log('FCP candidate:', entry.startTime, entry);
  }
}).observe({type: 'paint', buffered: true});

In the above example, the logged first-contentful-paint entry will tell you when the first contentful element was painted. However, in some cases this entry is not valid for measuring FCP.

The following section lists the differences between what the API reports and how the metric is calculated.

Differences between the metric and the API #

The API will dispatch a first-contentful-paint entry for pages loaded in a background tab, but those pages should be ignored when calculating FCP (first paint timings should only be considered if the page was in the foreground the entire time).
The API does not report first-contentful-paint entries when the page is restored from the back/forward cache, but FCP should be measured in these cases since users experience them as distinct page visits.
The API may not report paint timings from cross-origin iframes, but to properly measure FCP you should consider all frames. Sub-frames can use the API to report their paint timings to the parent frame for aggregation.

Rather than memorizing all these subtle differences, developers can use the web-vitals JavaScript library to measure FCP, which handles these differences for you (where possible):

import {onFCP} from 'web-vitals';

// Measure and log FCP as soon as it's available.
onFCP(console.log);

You can refer to the source code for onFCP() for a complete example of how to measure FCP in JavaScript.

How to improve FCP #

To learn how to improve FCP for a specific site, you can run a Lighthouse performance audit and pay attention to any specific opportunities or diagnostics the audit suggests.

To learn how to improve FCP in general (for any site), refer to the following performance guides:

CHANGELOG #

To help you manage this, all changes to either the implementation or definition of these metrics will be surfaced in this CHANGELOG.

If you have feedback for these metrics, you can provide it in the web-vitals-feedback Google group.

Total Blocking Time (TBT)

2019-11-07T00:00:00Z

What is TBT? #

The Total Blocking Time (TBT) metric measures the total amount of time between First Contentful Paint (FCP) and Time to Interactive (TTI) where the main thread was blocked for long enough to prevent input responsiveness.

The main thread is considered "blocked" any time there's a Long Task—a task that runs on the main thread for more than 50 milliseconds (ms). We say the main thread is "blocked" because the browser cannot interrupt a task that's in progress. So in the event that a user does interact with the page in the middle of a long task, the browser must wait for the task to finish before it can respond.

If the task is long enough (anything above 50 ms), it's likely that the user will notice the delay and perceive the page as sluggish or janky.

The blocking time of a given long task is its duration in excess of 50 ms. And the total blocking time for a page is the sum of the blocking time for each long task that occurs between FCP and TTI.

For example, consider the following diagram of the browser's main thread during page load:

The above timeline has five tasks, three of which are Long Tasks because their duration exceeds 50 ms. The next diagram shows the blocking time for each of the long tasks:

So while the total time spent running tasks on the main thread is 560 ms, only 345 ms of that time is considered blocking time.

	Task duration	Task blocking time
Task one	250 ms	200 ms
Task two	90 ms	40 ms
Task three	35 ms	0 ms
Task four	30 ms	0 ms
Task five	155 ms	105 ms
Total Blocking Time		345 ms

How does TBT relate to TTI? #

TBT is a great companion metric for TTI because it helps quantify the severity of how non-interactive a page is prior it to becoming reliably interactive.

TTI considers a page "reliably interactive" if the main thread has been free of long tasks for at least five seconds. This means that three, 51 ms tasks spread out over 10 seconds can push back TTI just as far as a single 10-second long task—but those two scenarios would feel very different to a user trying to interact with the page.

In the first case, three, 51 ms tasks would have a TBT of 3 ms. Whereas a single, 10-second long tasks would have a TBT of 9950 ms. The larger TBT value in the second case quantifies the worse experience.

How to measure TBT #

TBT is a metric that should be measured in the lab. The best way to measure TBT is to run a Lighthouse performance audit on your site. See the Lighthouse documentation on TBT for usage details.

Lab tools #

What is a good TBT score? #

To provide a good user experience, sites should strive to have a Total Blocking Time of less than 200 milliseconds when tested on average mobile hardware.

For details on how your page's TBT affects your Lighthouse performance score, see How Lighthouse determines your TBT score

How to improve TBT #

To learn how to improve TBT for a specific site, you can run a Lighthouse performance audit and pay attention to any specific opportunities the audit suggests.

To learn how to improve TBT in general (for any site), refer to the following performance guides:

Time to Interactive (TTI)

2019-11-07T00:00:00Z

What is TTI? #

The TTI metric measures the time from when the page starts loading to when its main sub-resources have loaded and it is capable of reliably responding to user input quickly.

To calculate TTI based on a performance trace of a web page, follow these steps:

Start at First Contentful Paint (FCP).
Search forward in time for a quiet window of at least five seconds, where quiet window is defined as: no long tasks and no more than two in-flight network GET requests.
Search backwards for the last long task before the quiet window, stopping at FCP if no long tasks are found.
TTI is the end time of the last long task before the quiet window (or the same value as FCP if no long tasks are found).

The following diagram should help visualize the steps above:

Historically, developers have optimized pages for fast render times, sometimes at the expense of TTI.

Techniques like server-side rendering (SSR) can lead to scenarios where a page looks interactive (that is, links and buttons are visible on the screen), but it's not actually interactive because the main thread is blocked or because the JavaScript code controlling those elements hasn't loaded.

When users try to interact with a page that looks interactive but actually isn't, they'll likely respond in one of two ways:

In the best-case scenario, they'll be annoyed that the page is slow to respond.
In the worst-case scenario, they'll assume the page is broken and likely leave. They may even lose confidence or trust in the value of your brand.

To avoid this problem, make every effort to minimize the difference between FCP and TTI. And in cases where a noticeable difference does exist, make it clear through visual indicators that the components on your page are not yet interactive.

How to measure TTI #

TTI is a metric that's best measured in the lab. The best way to measure TTI is to run a Lighthouse performance audit on your site. See the Lighthouse documentation on TTI for usage details.

Lab tools #

What is a good TTI score? #

To provide a good user experience, sites should strive to have a Time to Interactive of less than 5 seconds when tested on average mobile hardware.

For details on how your page's TTI affects your Lighthouse performance score, see How Lighthouse determines your TTI score.

How to improve TTI #

To learn how to improve TTI for a specific site, you can run a Lighthouse performance audit and pay attention to any specific opportunities the audit suggests.

To learn how to improve TTI in general (for any site), refer to the following performance guides:

Largest Contentful Paint (LCP)

2019-08-08T00:00:00Z

Browser support

Chrome 77, Supported 77
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

Historically, it's been a challenge for web developers to measure how quickly the main content of a web page loads and is visible to users.

Older metrics like load or DOMContentLoaded are not good because they don't necessarily correspond to what the user sees on their screen. And newer, user-centric performance metrics like First Contentful Paint (FCP) only capture the very beginning of the loading experience. If a page shows a splash screen or displays a loading indicator, this moment is not very relevant to the user.

In the past we've recommended performance metrics like First Meaningful Paint (FMP) and Speed Index (SI) (both available in Lighthouse) to help capture more of the loading experience after the initial paint, but these metrics are complex, hard to explain, and often wrong—meaning they still do not identify when the main content of the page has loaded.

Sometimes simpler is better. Based on discussions in the W3C Web Performance Working Group and research done at Google, we've found that a more accurate way to measure when the main content of a page is loaded is to look at when the largest element was rendered.

What is LCP? #

The Largest Contentful Paint (LCP) metric reports the render time of the largest image or text block visible within the viewport, relative to when the page first started loading.

What is a good LCP score? #

To provide a good user experience, sites should strive to have Largest Contentful Paint of 2.5 seconds or less. To ensure you're hitting this target for most of your users, a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.

What elements are considered? #

As currently specified in the Largest Contentful Paint API, the types of elements considered for Largest Contentful Paint are:

<img> elements
<image> elements inside an <svg> element
<video> elements with a poster image (the poster image load time is used)
An element with a background image loaded via the url() function (as opposed to a CSS gradient)
Block-level elements containing text nodes or other inline-level text elements children.
The first frame painted for autoplaying <video> elements (as of August 2023)
The first frame of an animated image format, such as animated GIFs (as of August 2023)

As well as only considering some elements, certain heurisitics are applied to exclude certain elements that are likely to be seen as "non-contentful" to users. For Chromium-based browsers, these include:

Elements with an opacity of 0, that are invisible to the user
Elements that cover the full viewport, that are likely considered as background rather than content
Placeholder images or other images with a low entropy, that likely do not reflect the true content of the page

Browsers are likely to continue to improve these heuristics to ensure we match user expectations of what the largest contentful element is.

These "contentful" heuristics may differ from those used by First Contentful Paint (FCP), which may consider some of these elements, such as placeholder images or full viewport images, even if they are ineligible to be LCP candidates. Despite both using "contentful" in their name, the aim of these metrics is different. FCP measures when any content is painted to screen and LCP when the main content is painted so LCP is intented to be more selective.

How is an element's size determined? #

The size of the element reported for Largest Contentful Paint is typically the size that's visible to the user within the viewport. If the element extends outside of the viewport, or if any of the element is clipped or has non-visible overflow, those portions do not count toward the element's size.

For image elements that have been resized from their intrinsic size, the size that gets reported is either the visible size or the intrinsic size, whichever is smaller. For example, images that are shrunk down to a much smaller than their intrinsic size will only report the size they're displayed at, whereas images that are stretched or expanded to a larger size will only report their intrinsic sizes.

For text elements, only the size of their text nodes is considered (the smallest rectangle that encompasses all text nodes).

For all elements, any margin, padding, or border applied via CSS is not considered.

When is largest contentful paint reported? #

Web pages often load in stages, and as a result, it's possible that the largest element on the page might change.

To handle this potential for change, the browser dispatches a PerformanceEntry of type largest-contentful-paint identifying the largest contentful element as soon as the browser has painted the first frame. But then, after rendering subsequent frames, it will dispatch another PerformanceEntry any time the largest contentful element changes.

For example, on a page with text and a hero image the browser may initially just render the text—at which point the browser would dispatch a largest-contentful-paint entry whose element property would likely reference a <p> or <h1>. Later, once the hero image finishes loading, a second largest-contentful-paint entry would be dispatched and its element property would reference the <img>.

It's important to note that an element can only be considered the largest contentful element once it has rendered and is visible to the user. Images that have not yet loaded are not considered "rendered". Neither are text nodes using web fonts during the font block period. In such cases a smaller element may be reported as the largest contentful element, but as soon as the larger element finishes rendering, it'll be reported via another PerformanceEntry object.

In addition to late-loading images and fonts, a page may add new elements to the DOM as new content becomes available. If any of these new elements is larger than the previous largest contentful element, a new PerformanceEntry will also be reported.

If an element that is currently the largest contentful element is removed from the viewport (or even removed from the DOM), it will remain the largest contentful element unless a larger element is rendered.

The browser will stop reporting new entries as soon as the user interacts with the page (via a tap, scroll, or keypress), as user interaction often changes what's visible to the user (which is especially true with scrolling).

For analysis purposes, you should only report the most recently dispatched PerformanceEntry to your analytics service.

Load time vs. render time #

For security reasons, the render timestamp of images is not exposed for cross-origin images that lack the Timing-Allow-Origin header. Instead, only their load time is exposed (since this is already exposed via many other web APIs).

The usage example below shows how to handle elements whose render time is not available. But, when possible, it's always recommended to set the Timing-Allow-Origin header, so your metrics will be more accurate.

How are element layout and size changes handled? #

To keep the performance overhead of calculating and dispatching new performance entries low, changes to an element's size or position do not generate new LCP candidates. Only the element's initial size and position in the viewport is considered.

This means images that are initially rendered off-screen and then transition on-screen may not be reported. It also means elements initially rendered in the viewport that then get pushed down, out of view will still report their initial, in-viewport size.

Examples #

Here are some examples of when the Largest Contentful Paint occurs on a few popular websites:

In both of the timelines above, the largest element changes as content loads. In the first example, new content is added to the DOM and that changes what element is the largest. In the second example, the layout changes and content that was previously the largest is removed from the viewport.

While it's often the case that late-loading content is larger than content already on the page, that's not necessarily the case. The next two examples show the Largest Contentful Paint occurring before the page fully loads.

In the first example, the Instagram logo is loaded relatively early and it remains the largest element even as other content is progressively shown. In the Google search results page example, the largest element is a paragraph of text that is displayed before any of the images or logo finish loading. Since all the individual images are smaller than this paragraph, it remains the largest element throughout the load process.

How to measure LCP #

LCP can be measured in the lab or in the field, and it's available in the following tools:

Field tools #

Lab tools #

Measure LCP in JavaScript #

To measure LCP in JavaScript, you can use the Largest Contentful Paint API. The following example shows how to create a PerformanceObserver that listens for largest-contentful-paint entries and logs them to the console.

new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    console.log('LCP candidate:', entry.startTime, entry);
  }
}).observe({type: 'largest-contentful-paint', buffered: true});

In the above example, each logged largest-contentful-paint entry represents the current LCP candidate. In general, the startTime value of the last entry emitted is the LCP value—however, that is not always the case. Not all largest-contentful-paint entries are valid for measuring LCP.

The following section lists the differences between what the API reports and how the metric is calculated.

Differences between the metric and the API #

The API will dispatch largest-contentful-paint entries for pages loaded in a background tab, but those pages should be ignored when calculating LCP.
The API will continue to dispatch largest-contentful-paint entries after a page has been backgrounded, but those entries should be ignored when calculating LCP (elements may only be considered if the page was in the foreground the entire time).
The API does not report largest-contentful-paint entries when the page is restored from the back/forward cache, but LCP should be measured in these cases since users experience them as distinct page visits.
The API does not consider elements within iframes but the metric does as they are part of the user experience of the page. In pages with an LCP within an iframe—for example a poster image on an embedded video—this will show as a difference between CrUX and RUM. To properly measure LCP you should consider them. Sub-frames can use the API to report their largest-contentful-paint entries to the parent frame for aggregation.

Rather than memorizing all these subtle differences, developers can use the web-vitals JavaScript library to measure LCP, which handles these differences for you (where possible):

import {onLCP} from 'web-vitals';

// Measure and log LCP as soon as it's available.
onLCP(console.log);

You can refer to the source code for onLCP() for a complete example of how to measure LCP in JavaScript.

What if the largest element isn't the most important? #

In some cases the most important element (or elements) on the page is not the same as the largest element, and developers may be more interested in measuring the render times of these other elements instead. This is possible using the Element Timing API, as described in the article on custom metrics.

How to improve LCP #

A full guide on optimizing LCP is available to guide you through the process of identifying LCP timings in the field and using lab data to drill down and optimize them.

Additional resources #

Lessons learned from performance monitoring in Chrome by Annie Sullivan at performance.now() (2019)

CHANGELOG #

To help you manage this, all changes to either the implementation or definition of these metrics will be surfaced in this CHANGELOG.

If you have feedback for these metrics, you can provide it in the web-vitals-feedback Google group.

Cumulative Layout Shift (CLS)

2019-06-11T00:00:00Z

Browser support

Chrome 77, Supported 77
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

Have you ever been reading an article online when something suddenly changes on the page? Without warning, the text moves, and you've lost your place. Or even worse: you're about to tap a link or a button, but in the instant before your finger lands—BOOM—the link moves, and you end up clicking something else!

Most of the time these kinds of experiences are just annoying, but in some cases, they can cause real damage.

A screencast illustrating how layout instability can negatively affect users.

Unexpected movement of page content usually happens because resources are loaded asynchronously or DOM elements get dynamically added to the page above existing content. The culprit might be an image or video with unknown dimensions, a font that renders larger or smaller than its fallback, or a third-party ad or widget that dynamically resizes itself.

What makes this issue even more problematic is that how a site functions in development is often quite different from how users experience it. Personalized or third-party content often doesn't behave the same in development as it does in production, test images are often already in the developer's browser cache, and API calls that run locally are often so fast that the delay isn't noticeable.

The Cumulative Layout Shift (CLS) metric helps you address this problem by measuring how often it's occurring for real users.

What is CLS? #

CLS is a measure of the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifespan of a page.

A layout shift occurs any time a visible element changes its position from one rendered frame to the next. (See below for details on how individual layout shift scores are calculated.)

A burst of layout shifts, known as a session window, is when one or more individual layout shifts occur in rapid succession with less than 1-second in between each shift and a maximum of 5 seconds for the total window duration.

The largest burst is the session window with the maximum cumulative score of all layout shifts within that window.

Example of session windows. Blue bars represent the scores of each individual layout shift.

What is a good CLS score? #

To provide a good user experience, sites should strive to have a CLS score of 0.1 or less. To ensure you're hitting this target for most of your users, a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.

Layout shifts in detail #

Layout shifts are defined by the Layout Instability API, which reports layout-shift entries any time an element that is visible within the viewport changes its start position (for example, its top and left position in the default writing mode) between two frames. Such elements are considered unstable elements.

Note that layout shifts only occur when existing elements change their start position. If a new element is added to the DOM or an existing element changes size, it doesn't count as a layout shift—as long as the change doesn't cause other visible elements to change their start position.

Layout shift score #

To calculate the layout shift score, the browser looks at the viewport size and the movement of unstable elements in the viewport between two rendered frames. The layout shift score is a product of two measures of that movement: the impact fraction and the distance fraction (both defined below).

layout shift score = impact fraction * distance fraction

Impact fraction #

The impact fraction measures how unstable elements impact the viewport area between two frames.

The union of the visible areas of all unstable elements for the previous frame and the current frame—as a fraction of the total area of the viewport—is the impact fraction for the current frame.

In the image above there's an element that takes up half of the viewport in one frame. Then, in the next frame, the element shifts down by 25% of the viewport height. The red, dotted rectangle indicates the union of the element's visible area in both frames, which, in this case, is 75% of the total viewport, so its impact fraction is 0.75.

Distance fraction #

The other part of the layout shift score equation measures the distance that unstable elements have moved, relative to the viewport. The distance fraction is the greatest distance any unstable element has moved in the frame (either horizontally or vertically) divided by the viewport's largest dimension (width or height, whichever is greater).

In the example above, the largest viewport dimension is the height, and the unstable element has moved by 25% of the viewport height, which makes the distance fraction 0.25.

So, in this example the impact fraction is 0.75 and the distance fraction is 0.25, so the layout shift score is 0.75 * 0.25 = 0.1875.

The next example illustrates how adding content to an existing element affects the layout shift score:

The "Click Me!" button is appended to the bottom of the gray box with black text, which pushes the green box with white text down (and partially out of the viewport).

In this example, the gray box changes size, but its start position does not change so it's not an unstable element.

The "Click Me!" button was not previously in the DOM, so its start position doesn't change either.

The start position of the green box, however, does change, but since it's been moved partially out of the viewport, the invisible area is not considered when calculating the impact fraction. The union of the visible areas for the green box in both frames (illustrated by the red, dotted rectangle) is the same as the area of the green box in the first frame—50% of the viewport. The impact fraction is 0.5.

The distance fraction is illustrated with the purple arrow. The green box has moved down by about 14% of the viewport so the distance fraction is 0.14.

The layout shift score is 0.5 x 0.14 = 0.07.

This last example illustrates multiple unstable elements:

In the first frame above there are four results of an API request for animals, sorted in alphabetical order. In the second frame, more results are added to the sorted list.

The first item in the list ("Cat") does not change its start position between frames, so it's stable. Similarly, the new items added to the list were not previously in the DOM, so their start positions don't change either. But the items labelled "Dog", "Horse", and "Zebra" all shift their start positions, making them unstable elements.

Again, the red, dotted rectangles represent the union of these three unstable elements' before and after areas, which in this case is around 60% of the viewport's area (impact fraction of 0.60).

The arrows represent the distances that unstable elements have moved from their starting positions. The "Zebra" element, represented by the blue arrow, has moved the most, by about 30% of the viewport height. That makes the distance fraction in this example 0.3.

The layout shift score is 0.60 x 0.3 = 0.18.

Expected vs. unexpected layout shifts #

Not all layout shifts are bad. In fact, many dynamic web applications frequently change the start position of elements on the page.

User-initiated layout shifts #

A layout shift is only bad if the user isn't expecting it. On the other hand, layout shifts that occur in response to user interactions (clicking a link, pressing a button, typing in a search box and similar) are generally fine, as long as the shift occurs close enough to the interaction that the relationship is clear to the user.

For example, if a user interaction triggers a network request that may take a while to complete, it's best to create some space right away and show a loading indicator to avoid an unpleasant layout shift when the request completes. If the user doesn't realize something is loading, or doesn't have a sense of when the resource will be ready, they may try to click something else while waiting—something that could move out from under them.

Layout shifts that occur within 500 milliseconds of user input will have the hadRecentInput flag set, so they can be excluded from calculations.

Animations and transitions #

Animations and transitions, when done well, are a great way to update content on the page without surprising the user. Content that shifts abruptly and unexpectedly on the page almost always creates a bad user experience. But content that moves gradually and naturally from one position to the next can often help the user better understand what's going on, and guide them between state changes.

Be sure to respect prefers-reduced-motion browser settings, as some site visitors can experience ill effects or attention issues from animation.

CSS transform property allows you to animate elements without triggering layout shifts:

Instead of changing the height and width properties, use transform: scale().
To move elements around, avoid changing the top, right, bottom, or left properties and use transform: translate() instead.

How to measure CLS #

CLS can be measured in the lab or in the field, and it's available in the following tools:

Field tools #

Lab tools #

Measure layout shifts in JavaScript #

To measure layout shifts in JavaScript, you use the Layout Instability API.

The following example shows how to create a PerformanceObserver to log layout-shift entries to the console:

new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    console.log('Layout shift:', entry);
  }
}).observe({type: 'layout-shift', buffered: true});

Measure CLS in JavaScript #

To measure CLS in JavaScript, you need to group these unexpected layout-shift entries into sessions, and calculate the maximum session value. You can refer to the web vitals JavaScript library source code which contains a reference implementation on how CLS is calculated.

In most cases, the current CLS value at the time the page is being unloaded is the final CLS value for that page, but there are a few important exceptions as noted in the next section. The web vitals JavaScript library accounts for these as much as possible, within the limitations of the Web APIs.

Differences between the metric and the API #

If a page is loaded in the background, or if it's backgrounded prior to the browser painting any content, then it should not report any CLS value.
If a page is restored from the back/forward cache, its CLS value should be reset to zero since users experience this as a distinct page visit.
The API does not report layout-shift entries for shifts that occur within iframes but the metric does as they are part of the user experience of the page. This can show as a difference between CrUX and RUM. To properly measure CLS you should consider them. Sub-frames can use the API to report their layout-shift entries to the parent frame for aggregation.

In addition to these exceptions, CLS has some added complexity due to the fact that it measures the entire lifespan of a page:

Users might keep a tab open for a very long time—days, weeks, months. In fact, a user might never close a tab.
On mobile operating systems, browsers typically do not run page unload callbacks for background tabs, making it difficult to report the "final" value.

To handle such cases, CLS should be reported any time a page is background—in addition to any time it's unloaded (the visibilitychange event covers both of these scenarios). And analytics systems receiving this data will then need to calculate the final CLS value on the backend.

Rather than memorizing and grappling with all of these cases yourself, developers can use the web-vitals JavaScript library to measure CLS, which accounts for everything mentioned above:

import {onCLS} from 'web-vitals';

// Measure and log CLS in all situations
// where it needs to be reported.
onCLS(console.log);

How to improve CLS #

A full guide on optimizing CLS is available to guide you through the process of identifying layout shifts in the field and using lab data to drill down and optimize them.

Additional resources #

Google Publisher Tag's guidance on minimizing layout shift
Understanding Cumulative Layout Shift by Annie Sullivan and Steve Kobes at #PerfMatters (2020)

CHANGELOG #

To help you manage this, all changes to either the implementation or definition of these metrics will be surfaced in this CHANGELOG.

If you have feedback for these metrics, you can provide it in the web-vitals-feedback Google group.

Best Practices for Using IndexedDB

2017-06-08T00:00:00Z

When a user first loads a website or application, there's often a fair amount of work involved in constructing the initial application state that's used to render the UI. For example, sometimes the app needs to authenticate the user client-side and then make several API requests before it has all the data it needs to display on the page.

Storing the application state in IndexedDB can be a great way to speed up the load time for repeat visits. The app can then sync up with any API services in the background and update the UI with new data lazily, employing a stale-while- revalidate strategy.

Another good use for IndexedDB is to store user-generated content, either as a temporary store before it is uploaded to the server or as a client-side cache of remote data - or, of course, both.

However, when using IndexedDB there are many important things to consider that may not be immediately obvious to developers new to the APIs. This article answers common questions and discusses some of the most important things to keep in mind when persisting data in IndexedDB.

Keeping your app predictable #

A lot of the complexities around IndexedDB stem from the fact that there are so many factors you (the developer) have no control over. This section explores many of the issues you must keep in mind when working with IndexedDB.

Not everything can be stored in IndexedDB on all platforms #

If you are storing large, user-generated files such as images or videos, then you may try to store them as File or Blob objects. This will work on some platforms but fail on others. Safari on iOS, in particular, cannot store Blobs in IndexedDB.

Luckily it is not too difficult to convert a Blob into an ArrayBuffer, and vice versa. Storing ArrayBuffers in IndexedDB is very well supported.

Remember, however, that a Blob has a MIME type while an ArrayBuffer does not. You will need to store the type alongside the buffer in order to do the conversion correctly.

To convert an ArrayBuffer to a Blob you simply use the Blob constructor.

function arrayBufferToBlob(buffer, type) {
  return new Blob([buffer], { type: type });
}

The other direction is slightly more involved, and is an asynchronous process. You can use a FileReader object to read the blob as an ArrayBuffer. When the reading is finished a loadend event is triggered on the reader. You can wrap this process in a Promise like so:

function blobToArrayBuffer(blob) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.addEventListener('loadend', () => {
      resolve(reader.result);
    });
    reader.addEventListener('error', reject);
    reader.readAsArrayBuffer(blob);
  });
}

Writing to storage may fail #

Errors when writing to IndexedDB can happen for a variety of reasons, and in some cases these reasons are outside of your control as a developer. For example, some browsers currently don't allow writing to IndexedDB when in private browsing mode. There's also the possibility that a user is on a device that's almost out of disk space, and the browser will restrict you from storing anything at all.

Because of this, it's critically important that you always implement proper error handling in your IndexedDB code. This also means it's generally a good idea to keep application state in memory (in addition to storing it), so the UI doesn't break when running in private browsing mode or when storage space isn't available (even if some of the other app features that require storage won't work).

You can catch errors in IndexedDB operations by adding an event handler for the error event whenever you create an IDBDatabase, IDBTransaction or IDBRequest object.

const request = db.open('example-db', 1);
request.addEventListener('error', (event) => {
  console.log('Request error:', request.error);
};

Stored data may have been modified or deleted by the user #

Unlike server-side databases where you can restrict unauthorized access, client-side databases are accessible to browser extensions and developer tools, and they can be cleared by the user.

While it may be uncommon for users to modify their locally stored data, it's quite common for users to clear it. It's important that your application can handle both of these cases without erroring.

Stored data may be out of date #

Similar to the previous section, even if the user hasn't modified the data themselves, it's also possible that the data they have in storage was written by an old version of your code, possibly a version with bugs in it.

IndexedDB has built-in support for schema versions and upgrading via its IDBOpenDBRequest.onupgradeneeded() method; however, you still need to write your upgrade code in such a way that it can handle the user coming from a previous version (including a version with a bug).

Unit tests can be very helpful here, as it's often not feasible to manually test all possible upgrade paths and cases.

Keeping your app performant #

One of the key features of IndexedDB is its asynchronous API, but don't let that fool you into thinking you don't need to worry about performance when using it. There are a number of cases where improper usage can still block the main thread, which can lead to jank and unresponsiveness.

As a general rule, reads and writes to IndexedDB should not be larger than required for the data being accessed.

While IndexedDB makes is possible to store large, nested objects as a single record (and doing so is admittedly quite convenient from a developer perspective), this practice should be avoided. The reason is because when IndexedDB stores an object, it must first create a structured clone of that object, and the structured cloning process happens on the main thread. The larger the object, the longer the blocking time will be.

This presents some challenges when planning how to persist application state to IndexedDB, as most of the popular state management libraries (like Redux) work by managing your entire state tree as a single JavaScript object.

While managing state in this way has many benefits (e.g. it makes your code easy to reason about and debug), and while simply storing the entire state tree as a single record in IndexedDB may be tempting and convenient, doing this after every change (even if throttled/debounced) will result in unnecessary blocking of the main thread, it will increase the likelihood of write errors, and in some cases it will even cause the browser tab to crash or become unresponsive.

Instead of storing the entire state tree in a single record, you should break it up into individual records and only update the records that actually change.

The same is true if you store large items like images, music, or video in IndexedDB. Store each item with its own key rather than inside a larger object, so that you can retrieve the structured data without paying the cost of also retrieving the binary file.

As with most best practices, this is not an all-or-nothing rule. In cases where it's not feasible to break up a state object and just write the minimal change-set, breaking up the data into sub-trees and only writing those is still preferable to always writing the entire state tree. Little improvements are better than no improvements at all.

Lastly, you should always be measuring the performance impact of the code you write. While it's true that small writes to IndexedDB will perform better than large writes, this only matters if the writes to IndexedDB that your application is doing actually lead to long tasks that block the main thread and degrade the user experience. It's important to measure so you understand what you're optimizing for.

Conclusions #

Developers can leverage client storage mechanisms like IndexedDB to improve the user experience of their application by not only persisting state across sessions but also by decreasing the time it takes to load the initial state on repeat visits.

While using IndexedDB properly can dramatically improve user experience, using it incorrectly or failing to handle error cases can lead to broken apps and unhappy users.

Since client storage involves many factors outside of your control, it's critical your code is well tested and properly handles errors, even those that may initially seem unlikely to occur.

Measuring the Real-world Performance Impact of Service Workers

2016-07-22T00:00:00Z

One of the most significant benefits of service workers (from a performance perspective, at least) is their ability to proactively control the caching of assets. A web application that can cache all of its necessary resources should load substantially faster for returning visitors. But what do these gains actually look like to real users? And how do you even measure this?

The Google I/O web app (IOWA for short) is a progressive web app that leveraged most of the new capabilities offered by service workers to deliver a rich, app-like experience to its users. It also used Google Analytics to capture key performance data and usage patterns from its large and diverse user audience.

This case study explores how IOWA used Google Analytics to answer key performance questions and report on the real-world impact of service workers.

Starting with the questions #

Any time you implement analytics in a website or application, it's important to start by identifying the questions you're trying to answer from the data you'll be collecting.

While we had several questions we wanted to answer, for the purposes of this case study, let's focus on two of the more interesting ones.

1. Is service worker caching more performant than the existing HTTP caching mechanisms available in all browsers?

We already expect pages to load faster for returning visitors than for new visitors since browsers can cache requests and serve them instantly on repeat visits.

Service workers offers alternative caching capabilities that give developers fine-grained control over exactly what and how caching is done. In IOWA, we optimized our service worker implementation so that every asset would be cached, so returning visitors could use the app completely offline.

But would this effort be any better than what the browser already does by default? And if so, how much better? 1

2. How does service worker impact the experience of the site loading?

In other words, how fast does it feel like the site is loading, regardless of the actual load times as measured by traditional page load metrics?

Answering questions about how an experience feels is obviously not an easy task, and no metric is going to perfectly represent such a subjective sentiment. That being said, there are definitely some metrics that are better than others, so choosing the right ones is important.

Choosing the right metric #

Google Analytics, by default, tracks page load times (via the Navigation Timing API) for 1% of a site's visitors, and it makes that data available via metrics like Avg. Page Load Time.

Avg. Page Load Time is a good metric for answering our first question, but it's not a particularly good metric for answering the second. For one thing the load event doesn't necessarily correspond to the moment when the user can actually interact with the app. Moreover, two apps with the exact same load time may feel like they load much differently. For example, a site with a splash screen or a loading indicator probably feels like it loads much faster than a site that just shows a blank page for several seconds.

In IOWA, we showed a splash screen countdown animation that (in my opinion) very successfully served to entertain the user while the rest of the app loaded in the background. Because of this, tracking how long it takes the splash screen to appear makes a lot more sense as a way to measure perceived load performance. We chose the metric time to first paint to get this value.

Once we decided on the questions we wanted to answer and identified the metrics that would be useful in answering them, it was time to implement Google Analytics and start measuring.

The analytics implementation #

If you've used Google Analytics before, then you're probably familiar with the recommended JavaScript tracking snippet. It looks like this:

<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');
</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>

The first line in the above code initializes a global ga() function (if it doesn't already exist), and the last line asynchronously downloads the analytics.js library.

The middle part contains these two lines:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

These two commands track what pages are visited by people going to your site, but not much more. If you want to track additional user interactions, you have to do so yourself.

For IOWA, we wanted to track two additional things:

The elapsed time between when the page first starts to load and when pixels appear on the screen.
Whether or not a service worker is controlling the page. With this information we could segment our reports to compare the results with and without service worker.

Capturing time to first paint #

Some browsers record the precise time at which the first pixel is painted to the screen, and they make that time available to developers. That value, compared with the navigationStart value exposed via the Navigation Timing API gives us a very accurate accounting of how much time has passed between when the user initially requested the page and when they first saw something.

As I already mentioned, time to first paint is an important metric to measure because it's the first point at which a user experiences the load speed of your site. It's the first impression users get, and a good first impression can positively affect the rest of the user experience.2

To get the first paint value in browsers that expose it, we created the getTimeToFirstPaintIfSupported utility function:

function getTimeToFirstPaintIfSupported() {
  // Ignores browsers that don't support the Performance Timing API.
  if (window.performance && window.performance.timing) {
    var navTiming = window.performance.timing;
    var navStart = navTiming.navigationStart;
    var fpTime;

    // If chrome, get first paint time from `chrome.loadTimes`.
    if (window.chrome && window.chrome.loadTimes) {
      fpTime = window.chrome.loadTimes().firstPaintTime * 1000;
    }
    // If IE/Edge, use the prefixed `msFirstPaint` property.
    // See http://msdn.microsoft.com/ff974719
    else if (navTiming.msFirstPaint) {
      fpTime = navTiming.msFirstPaint;
    }

    if (fpTime && navStart) {
      return fpTime - navStart;
    }
  }
}

With this, we could now write another function that sends a non-interaction event with the time to first paint as its value:3

function sendTimeToFirstPaint() {
  var timeToFirstPaint = getTimeToFirstPaintIfSupported();

  if (timeToFirstPaint) {
    ga('send', 'event', {
      eventCategory: 'Performance',
      eventAction: 'firstpaint',
      // Rounds to the nearest millisecond since
      // event values in Google Analytics must be integers.
      eventValue: Math.round(timeToFirstPaint)
      // Sends this as a non-interaction event,
      // so it doesn't affect bounce rate.
      nonInteraction: true
    });
  }
}

After writing both of these functions, our tracking code looks like this:

// Creates the tracker object.
ga('create', 'UA-XXXXX-Y', 'auto');

// Sends a pageview for the initial pageload.
ga('send', 'pageview');

// Sends an event with the time to first paint data.
sendTimeToFirstPaint();

Note that depending on when the above code runs, pixels may or may not have already been painted to the screen. To ensure we always run this code after the first paint occurs, we postponed the call to sendTimeToFirstPaint() until after the load event. In fact, we decided to postpone sending all analytics data until after the page was loaded to ensure those requests wouldn't compete with the loading of other resources.

// Creates the tracker object.
ga('create', 'UA-XXXXX-Y', 'auto');

// Postpones sending any hits until after the page has fully loaded.
// This prevents analytics requests from delaying the loading of the page.
window.addEventListener('load', function() {
  // Sends a pageview for the initial pageload.
  ga('send', 'pageview');

  // Sends an event with the time to first paint data.
  sendTimeToFirstPaint();
});

The code above reports firstpaint times to Google Analytics, but that's only half the story. We still needed to track the service worker status; otherwise we wouldn't be able to compare the first paint times of a service worker-controlled page and a non-controlled page.

Determining service worker status #

To determine the current status of the service worker, we created a utility function that returns one of three values:

controlled: a service worker is controlling the page. In the case of IOWA that also means all assets have been cached and the page works offline.
supported: the browser supports service worker, but the service worker is not yet controlling the page. This is the expected status for first time visitors.
unsupported: the user's browser does not support service worker.

function getServiceWorkerStatus() {
  if ('serviceWorker' in navigator) {
    return navigator.serviceWorker.controller ? 'controlled' : 'supported';
  } else {
    return 'unsupported';
  }
}

This function got the service worker status for us; the next step was to associate this status with the data we were sending to Google Analytics.

Tracking custom data with custom dimensions #

By default, Google Analytics gives you lots of ways to subdivide your total traffic into groups based on attributes of the user, session, or interaction. These attributes are known as dimensions. Common dimensions web developers care about are things like Browser, Operating System, or Device Category.

The service worker's status is not a dimension Google Analytics provides by default; however, Google Analytics does give you the ability to create your own custom dimensions and define them however you want.

For IOWA, we created a custom dimension called Service Worker Status and set its scope to hit (i.e. per-interaction).4 Each custom dimension you create in Google Analytics is given a unique index within that property, and in your tracking code you can reference that dimension by its index. For example, if the index of the dimension we just created were 1, we could update our logic as follows to send the firstpaint event to include the service worker status:

ga('send', 'event', {
  eventCategory: 'Performance',
  eventAction: 'firstpaint',
  // Rounds to the nearest millisecond since
  // event values in Google Analytics must be integers.
  eventValue: Math.round(timeToFirstPaint)
  // Sends this as a non-interaction event,
  // so it doesn't affect bounce rate.
  nonInteraction: true,

  // Sets the current service worker status as the value of
  // `dimension1` for this event.
  dimension1: getServiceWorkerStatus()
});

This works, but it will only associate the service worker's status with this particular event. Since Service Worker Status is something that's potentially useful to know for any interaction, it's best to include it with all data sent to Google Analytics.

To include this information in all hits (e.g. all pageviews, events, etc.) we set the custom dimension value on the tracker object itself, prior to sending any data to Google Analytics.

ga('set', 'dimension1', getServiceWorkerStatus());

Once set, this value gets sent with all subsequent hits for the current pageload. If the user loads the page again later, a new value will likely be returned from the getServiceWorkerStatus() function, and that value will be set on the tracker object.

A quick note on code clarity and readability: since other people looking at this code may not know what dimension1 refers to, it's always best to create a variable that maps meaningful dimension names to the values analytics.js will use.

// Creates a map between custom dimension names and their index.
// This is particularly useful if you define lots of custom dimensions.
var customDimensions = {
  SERVICE_WORKER_STATUS: 'dimension1'
};

// Creates the tracker object.
ga('create', 'UA-XXXXX-Y', 'auto');

// Sets the service worker status on the tracker,
// so its value is included in all future hits.
ga('set', customDimensions.SERVICE_WORKER_STATUS, getServiceWorkerStatus());

// Postpones sending any hits until after the page has fully loaded.
// This prevents analytics requests from delaying the loading of the page.
window.addEventListener('load', function() {
  // Sends a pageview for the initial pageload.
  ga('send', 'pageview');

  // Sends an event with the time to first paint data.
  sendTimeToFirstPaint();
});

As I mentioned, sending the Service Worker Status dimension with every hit allows us to use it when reporting on any metric.

As you can see almost 85% of all pageviews for IOWA were from browsers that support service worker.

The results: answering our questions #

Once we started collecting data to answer our questions, we could report on that data to see the results. (Note: all Google Analytics data shown here represents actual web traffic to the IOWA site from May 16-22, 2016).

The first question we had was: Is service worker caching more performant than the existing HTTP caching mechanisms available in all browsers?

To answer that question, we created a custom report that looked at the metric Avg. Page Load Times across various dimensions. This metric is well-suited to answer this question because the load event fires only after all initial resources are downloaded. Thus it directly reflects the total load time for all the site's critical resources.5

The dimensions we chose were:

Our custom Service Worker Status dimension.
User Type, which indicates whether this is the user's first visit to the site or if they're returning. (Note: a new visitor will not have any resources cached; a returning visitor might.)
Device Category, which lets us compare the results across mobile and desktop.

To control for the possibility that non-service-worker-related factors were skewing our load time results, we limited our query to only include browsers that support service worker.

As you can see, visits to our app when controlled by a service worker loaded quite a bit faster than non-controlled visits, even those from returning users who likely had most of the page's resources cached. It's also interesting to notice that, on average, visitors on mobile with a service worker saw faster loads than new desktop visitors.

"…visits to our app when controlled by a service worker loaded quite a bit faster than non-controlled visits…"

You can see more details in the following two tables:

Avg. Page Load Time (Desktop)
Service Worker Status	User Type	Avg. Page Load Time (ms)	Sample Size
Controlled	Returning Visitor	2568	30860
Supported	Returning Visitor	3612	1289
Supported	New Visitor	4664	21991

Avg. Page Load Time (Mobile)
Service Worker Status	User Type	Avg. Page Load Time (ms)	Sample Size
Controlled	Returning Visitor	3760	8162
Supported	Returning Visitor	4843	676
Supported	New Visitor	6158	5779

You may be wondering how it's possible for a returning visitor whose browser supports service worker to ever be in a non-controlled state. There are a few possible explanations for this:

The user left the page on the initial visit before the service worker had a chance to finish initializing.
The user uninstalled the service worker via the developer tools.

Both of these situations are relatively rare. We can see that in the data by looking at the Page Load Sample values in the fourth column. Notice that the middle rows have a much smaller sample than the other two.

Our second question was: How does service worker impact the experience of the site loading?

To answer this question, we created another custom report for the metric Avg. Event Value and filtered the results to only include our firstpaint events. We used the dimensions Device Category and our custom Service Worker Status dimension.

Contrary to what I would have expected, the service worker on mobile had much less impact on time to first paint than it did on overall page load.

"…service worker on mobile had much less impact on time to first paint than it did on overall page load."

To explore why this is the case, we have to dig deeper into the data. Averages can be good for general overviews and broad strokes, but to really get a sense of how these numbers break down across a range of users, we need to look at a distribution of firstpaint times.

Getting the distribution of a metric in Google Analytics #

To get the distribution of firstpaint times we need access to the individual results for each event. Unfortunately, Google Analytics doesn't make this easy.

Google Analytics lets us break down a report by whatever dimension we want, but it doesn't let use break down a report by metrics. That isn't to say it's impossible, it just means we had to customize our implementation a bit more to get the desired result.

Since report results can only be broken down by dimensions, we had to set the metric value (in this case firstpaint time) as a custom dimension on the event. To do this we created another custom dimension called Metric Value and updated our firstpaint tracking logic as follows:

var customDimensions = {
  SERVICE_WORKER_STATUS: 'dimension1',
  <strong>METRIC_VALUE: 'dimension2'</strong>
};

// ...

function sendTimeToFirstPaint() {
  var timeToFirstPaint = getTimeToFirstPaintIfSupported();

  if (timeToFirstPaint) {
    var fields = {
      eventCategory: 'Performance',
      eventAction: 'firstpaint',
      // Rounds to the nearest millisecond since
      // event values in Google Analytics must be integers.
      eventValue: Math.round(timeToFirstPaint)
      // Sends this as a non-interaction event,
      // so it doesn't affect bounce rate.
      nonInteraction: true
    }

    <strong>// Sets the event value as a dimension to allow for breaking down the
    // results by individual metric values at reporting time.
    fields[customDimensions.METRIC_VALUE] = String(fields.eventValue);</strong>

    ga('send', 'event', fields);
  }
}

The Google Analytics web interface does not currently provide a way to visualize the distribution of arbitrary metric values, but with the help of the Google Analytics Core Reporting API and the Google Charts library we could query for the raw results and then construct a histogram ourselves.

For example, the following API request configuration was used to get a distribution of firstpaint values on desktop with a non-controlled service worker.

{
  dateRanges: [{startDate: '2016-05-16', endDate: '2016-05-22'}],
  metrics: [{expression: 'ga:totalEvents'}],
  dimensions: [{name: 'ga:dimension2'}],
  dimensionFilterClauses: [
    {
      operator: 'AND',
      filters: [
        {
          dimensionName: 'ga:eventAction',
          operator: 'EXACT',
          expressions: ['firstpaint']
        },
        {
          dimensionName: 'ga:dimension1',
          operator: 'EXACT',
          expressions: ['supported']
        },
        {
          dimensionName: 'ga:deviceCategory',
          operator: 'EXACT',
          expressions: ['desktop']
        }
      ],
    }
  ],
  orderBys: [
    {
      fieldName: 'ga:dimension2',
      orderType: 'DIMENSION_AS_INTEGER'
    }
  ]
}

This API request returns an array of values that look like this (Note: these are just the first five results). The results are sorted from smallest to largest, so these rows represent the fastest times.

API Response Results (first five rows)
ga:dimension2	ga:totalEvents
4	3
5	2
6	10
7	8
8	10

Here's what these results mean in plain English:

There were 3 events where the firstpaint value was 4 ms
There were 2 events where the firstpaint value was 5 ms
There were 10 events where the firstpaint value was 6 ms
There were 8 events where the firstpaint value was 7 ms
There were 10 events where the firstpaint value was 8 ms
etc.

From these results we can extrapolate the firstpaint value for every single event and create a histogram of the distribution. We did this for each of the queries we ran.

Here's what the distribution looked like on desktop with a non-controlled (but supported) service worker:

The median firstpaint time for the above distribution is 912 ms.

The shape of this curve is quite typical of load time distributions. Contrast that with the histogram below which shows the distribution of first paint events for visits in which a service worker was controlling the page.

Notice that when a service worker was controlling the page, many visitors experienced a near-immediate first paint, with a median of 583 ms.

"…when a service worker was controlling the page, many visitors experienced a near-immediate first paint…"

To get a better sense of how these two distributions compare to each other, the next chart shows a merged view of the two. The histogram showing non-controlled service worker visits is overlaid on top of the histogram showing controlled visits, and both of those are overlaid on top of a histogram showing both combined.

One thing I found interesting about these results was that the distribution with a controlled service worker still had a bell-shaped curve after the initial spike. I was expecting a large initial spike and then a gradual trail off, I wasn't expecting a second peak in the curve.

When I looked into what might be causing this, I learned that even though a service worker can be controlling a page, its thread can be inactive. The browser does this to save resources - obviously you don't need every service worker for every site you've ever visited to be active and ready at a moment's notice. This explains the tail of the distribution. For some users, there was a delay while the service worker thread started up.

As you can see from the distribution though, even with this initial delay, browsers with service worker delivered content faster than browsers going through the network.

Here's how things looked on mobile:

While we still had a sizeable increase in near-immediate first paint times, the tail was quite a bit larger and longer. This is likely because, on mobile, starting an idle service worker thread takes longer than it does on desktop. It also explains why the difference between average firstpaint time wasn't as big as I was expecting (discussed above).

"…on mobile, starting an idle service worker thread takes longer than it does on desktop."

Here is the breakdown from these variations of median first paint times on mobile and desktop grouped by service worker status:

Median Time to First Paint (ms)
Service Worker Status	Desktop	Mobile
Controlled	583	1634
Supported (not controlled)	912	1933

While building these distribution visualizations took a bit more time and effort than creating a custom report in Google Analytics, they give us a far better sense of how service workers affect the performance of our site than averages alone.

Other impact from Service Workers #

In addition to the performance impact, service workers also impact the user experience in several other ways that are measurable with Google Analytics.

Offline access #

Service workers allow users to interact with your site while offline, and while some sort of offline support is probably critical for any progressive web app, determining how critical it is in your case largely depends on how much usage is occurring offline. But how do we measure that?

Sending data to Google Analytics requires an internet connection, but it doesn't require the data to be sent at the exact time the interaction took place. Google Analytics supports sending interaction data after the fact by specifying a time offset (via the qt parameter).

For the past two years IOWA has been using a service worker script that detects failed hits to Google Analytics when the user is offline and replays them later with the qt parameter.

To track whether the user was online or offline, we created a custom dimension called Online and set it to the value of navigator.onLine, we then listened for the online and offline events and updated the dimension accordingly.

And to get a sense for how common it was for a user to be offline while using IOWA, we created a segment that targeted users with at least one offline interaction. Turns out, that was almost 5% of users.

Push notifications #

Service workers allow users to opt-in to receiving push notifications. In IOWA, users were notified when a session in their schedule was about to start.

As with any form of notifications, it's important to find the balance between providing value to the user and annoying them. To better understand which is happening, it's important to track whether users are opting-in to receive these notifications, if they're engaging with them when they arrive, and if any users who previously opted-in change their preference and opt-out.

In IOWA, we only sent notifications related to the user's personalized schedule, something only logged-in users could create. This limited the set of users who could receive notifications to logged-in users (tracked via a custom dimension called Signed In) whose browsers supported push notifications (tracked via another custom dimension called Notification Permission).

The following report is based on the metric Users and our Notification Permission custom dimension, segmented by users who signed in at some point and whose browsers support push notifications.

It's great to see that more than half of our signed-in users opted to receive push notifications.

App install banners #

If a progress web app meets the criteria and is used frequently by a user, that user may be shown an app install banner, prompting them to add the app to their home screen.

In IOWA, we tracked how often these prompts were shown to the user (and whether they were accepted) with the following code:

window.addEventListener('beforeinstallprompt', function(event) {
  // Tracks that the user saw a prompt.
  ga('send', 'event', {
    eventCategory: 'installprompt',
    eventAction: 'fired'
  });

  event.userChoice.then(function(choiceResult) {
    // Tracks the users choice.
    ga('send', 'event', {
      eventCategory: 'installprompt',
      // `choiceResult.outcome` will be 'accepted' or 'dismissed'.
      eventAction: choiceResult.outcome,
      // `choiceResult.platform` will be 'web' or 'android' if the prompt was
      // accepted, or '' if the prompt was dismissed.
      eventLabel: choiceResult.platform
    });
  });
});

Of the users who saw an app install banner, about 10% chose to add it to their home screen.

Possible tracking improvements (for next time) #

The analytics data we collected from IOWA this year was invaluable. But hindsight always brings to light holes and opportunities to improve things for the next time around. After finishing this year's analysis, here are two things I wish we'd done differently that readers looking to implement a similar strategy might want to consider:

1. Track more events related to the load experience

We tracked several events that correspond to a technical metric (e.g. HTMLImportsLoaded, WebComponentsReady, etc.), but since so much of the load was done asynchronously, the point at which these events fired didn't necessarily correspond with a particular moment in the overall load experience.

The primary load-related event we didn't track (but wish we had) is the point at which the splash screen disappeared and the user could see the page content.

2. Store the analytics client ID in IndexedDB

By default, analytics.js stores the client ID field in the browser's cookies; unfortunately, service worker scripts cannot access cookies.

This presented a problem for us when we tried to implement notification tracking. We wanted to send an event from the service worker (via the Measurement Protocol) each time a notification was sent to a user, and then track the re-engagement success of that notification if the user clicked on it and arrived back in the app.

While we were able to track the success of notifications in general via the utm_source campaign parameter, we weren't able to tie a particular re-engagement session to a particular user.

What we could have done to work around this limitation was store the client ID via IndexedDB in our tracking code, and then that value would have been accessible to the service worker script.

3. Let the service worker report online/offline status

Inspecting navigator.onLine will let you know if your browser is able to connect to the router or local area network, but it won't necessarily tell if you if the user has real connectivity. And since our offline analytics service worker script simply replayed failed hits (without modifying them, or marking them as failed), we were probably under-reporting our offline usage.

In the future we should track both the status of navigator.onLine as well as whether the hit was replayed by the service worker due to an initial network failure. This will give us a more accurate picture of the true offline usage.

Wrapping up #

This case study has shown that using service worker did indeed improve the load performance of the Google I/O webapp across a wide range of browsers, networks, and devices. It has also shown that when you look at a distribution of the load data across a wide range of browsers, networks, and devices, you get much more insight into how this technology handles real-world scenarios, and you discover performance characteristics that you may not have expected.

Here were some of the key takeaways from the IOWA study:

On average, pages loaded quite a bit faster when a service worker was controlling the page than they did without a service worker, for both new and returning visitors.
Visits to pages controlled by a service worker loaded almost instantly for many users.
Service workers, when inactive, took a bit of time to start up. However, an inactive service worker still performed better than no service worker.
The startup time for an inactive service worker was longer on mobile than on desktop.

While the performance gains observed in one particular application are generally useful to report to the larger developer community, it's important to remember that these results are specific to the type of site IOWA is (an event site) and the type of audience IOWA has (mostly developers).

If you're implementing service worker in your application, it's important that you implement your own measurement strategy so you can assess your own performance and prevent future regression. If you do, please share your results so everyone can benefit!

Footnotes #

It's not entirely fair to compare the performance of our service worker cache implementation to the performance of our site with HTTP cache alone. Because we were optimizing IOWA for service worker, we didn't spend much time optimizing for HTTP cache. If we had, the results probably would have been different. To learn more about optimizing your site for HTTP cache, read Optimizing Content Efficiently.
Depending on how your site loads its styles and content, it's possible that the browser is able to paint prior to content or styles being available. In such cases, firstpaint may correspond to a blank white screen. If you use firstpaint, it's important to ensure it corresponds to a meaningful point in the loading of your site's resources.
Technically we could send a timing hit (which are non-interaction by default) to capture this information instead of an event. In fact, timing hits were added to Google Analytics specifically to track load metrics like this; however, timing hits get heavily sampled at processing time, and their values cannot be used in segments. Given these current limitations, non-interaction events remain better suited.
To better understand what scope to give a custom dimension in Google Analytics refer to the Custom Dimension section of the Analytics help center. It's also important to understand the Google Analytics data model, which consists of users, sessions, and interactions (hits). To learn more, watch the Analytics Academy lesson on the Google Analytics Data Model.
This does not account for resources lazily loaded after the load event.

Philip Walton on web.dev

Our top Core Web Vitals recommendations for 2023

Largest Contentful Paint (LCP) #

Ensure the LCP resource is discoverable from the HTML source #

Ensure the LCP resource is prioritized #

Use a CDN to optimize document and resource TTFB #

Cumulative Layout Shift (CLS) #

Set explicit sizes on any content loaded from the page #

Ensure pages are eligible for bfcache #

Avoid animations/transitions that use layout-inducing CSS properties #

First Input Delay (FID) #

Avoid or break up long tasks #

Avoid unnecessary JavaScript #

Avoid large rendering updates #

Conclusion #

Optimize Interaction to Next Paint

Figure out what's causing poor INP #

Find slow interactions in the field #

Diagnose slow interactions in the lab #

Optimize interactions #

Identify and reduce input delay #

The relationship between script evaluation and long tasks during startup #

Optimize event callbacks #

Yield to the main thread often #

Yield to allow rendering work to occur sooner #

Avoid layout thrashing #

Minimize presentation delay #

Minimize DOM size #

Use content-visibility to lazily render off-screen elements #

Be aware of performance costs when rendering HTML using JavaScript #

Conclusion #

How SPA architectures affect Core Web Vitals

Frequently asked questions #

Do Core Web Vitals metrics include SPA route transitions? #

Can the Core Web Vitals metrics treat SPA route changes the same as traditional page loads? #

Is it harder for SPAs to do well on Core Web Vitals than MPAs? #

If SPA architectures improve the user experience, shouldn't that improvement be reflected in the metrics? #

We switched our site from an MPA to an SPA and our scores regressed. Is that expected? #

Should I switch my site from an SPA to an MPA to score better on Core Web Vitals? #

If Core Web Vitals scores are only reported for an SPA's landing pages, how can I debug issues that occur on "pages" after a route transition? #

What is Google doing to ensure MPAs do not have an unfair advantage compared to SPAs? #

Assess cross-origin and same-origin page visits separately #

Design new APIs that enable better SPA measurement #

Final thoughts #

Why lab and field data can be different (and what to do about it)

Lab data versus field data #

Lab data #

Field data #

Why lab and field data are different #

LCP #

Different LCP elements #

Effects of cache state on LCP #

AMP or Signed Exchange optimizations #

Effects of bfcache on LCP #

Effects of user interaction on LCP #

FID #

FID requires real-user interaction #

TBT and TTI do not consider user behavior #

TBT and TTI do not consider tap delay #

Effects of cache state and bfcache on FID #

CLS #

Effects of user interaction on CLS #

Personalized content #

Effects of cache state and bfcache on CLS #

What to do when the results are different #

Further reading #

Measure and debug performance with Google Analytics 4 and BigQuery

Measure #

Analyze #

Query Web Vitals data #

Example queries #

LCP, FID, and CLS at the 75% percentile (p75) across the whole site #

All individual LCP values from highest to lowest #

LCP scores (p75) of the 10 most popular pages #

Top 10 pages with the worst CLS (p75) #

Debug #

Example queries #

Top elements contributing to CLS #

Debug other metrics #

Visualize #

Use `content-visibility` to lazily render off-screen elements #

Never use the `unload` event #

Only add `beforeunload` listeners conditionally #

Minimize use of `Cache-Control: no-store` #

Avoid `window.opener` references #