Articles

Files and directories patterns

Wed, 29 Jul 2026 12:48:36 GMT

Files and directories patterns

A collection of common patterns to deal with files and directories.

Preload responsive images

Fri, 10 Jul 2026 07:00:00 GMT

Published: September 30, 2019, Last updated: July 10, 2026

You can preload responsive images, which can let your images load significantly faster by helping the browser identify the correct image from a srcset before it renders the img tag.

Responsive images overview

Browser Support

Source

Suppose you're browsing the web on a screen that's 300 pixels wide, and the page requests an image 1500 pixels wide. That page has wasted a lot of your mobile data because your screen can't do anything with all that extra resolution. Ideally, the browser would fetch a version of the image that's just a little wider than your screen size, for example, 325 pixels. This ensures a high-resolution image without wasting data, and lets the image load faster.

Responsive images let browsers fetch different image resources for different devices. If you don't use an image CDN, save multiple dimensions for each image and specify them in the srcset attribute. The w value tells the browser the width of each version, so it can choose the appropriate version for any device:

<img src="small.jpg" srcset="small.jpg 500w, medium.jpg 1000w, large.jpg 1500w" alt="…">

Preload overview

Browser Support

Source

Preloading lets you tell the browser about critical resources that you want to load as soon as possible, before they're discovered in HTML. This is especially useful for resources that aren't readily discoverable, such as fonts included in stylesheets, background images, or resources loaded from a script.

<link rel="preload" as="image" href="important.png" fetchpriority="high">

Important: Preloaded images are presumably high priority and so should include the fetchpriority="high" attribute as otherwise the preload will get the default priority for the as attribute. For images this is low by default so the browser can prioritise render-blocking content over images. See Optimize resource loading with the Fetch Priority API for more details.

`imagesrcset` and `imagesizes`

The <link> element uses the imagesrcset and imagesizes attributes to preload responsive images. Use them alongside <link rel="preload">, with the srcset and sizes syntax used in the <img> element.

For example, if you want to preload a responsive image specified with:

 <img src="wolf.jpg" srcset="wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w" sizes="50vw" alt="A rad wolf">

You can do that by adding the following to your HTML's <head>:

<link rel="preload" as="image" href="wolf.jpg" imagesrcset="wolf_400px.jpg 400w, wolf_800px.jpg 800w, wolf_1600px.jpg 1600w" imagesizes="50vw" fetchpriority="high">

This initiates a request using the same resource selection logic that srcset and sizes use.

Use cases

The following are some use cases for preloading responsive images.

Preload dynamically-injected responsive images

Imagine you're dynamically-loading hero images as part of a slideshow, and you know which image will be displayed first. In that case, you probably want to show that image as soon as possible, and not wait for the slideshow script to load it.

You can inspect this issue on a website with a dynamically-loaded image gallery:

Open this slideshow demo in a new tab.
Press Control+Shift+J (or Command+Option+J on Mac) to open DevTools.
Click the Network tab.
In the Throttling drop-down list, select Fast 3G.
Disable the Disable cache checkbox.
Reload the page.

Without preloading, the images start loading after the browser has finished running the script. For the first image, that delay is unnecessary.

Using preload here lets the image start loading ahead of time, so it can be ready to display when the browser needs to display it.

Preloading the first image lets it start loading at the same time as the script.

To see the difference that preloading makes, inspect the same dynamically-loaded image gallery but with the first image preloaded by following the steps from the first example.

Preload background images using image-set

If you have different background images for different screen densities, you can specify them in your CSS with the image-set syntax. The browser can then choose which one to display based on the screen's DPR.

background-image: image-set( "cat.png" 1x, "cat-2x.png" 2x);

The problem with CSS background images is that the browser discovers them only after it has downloaded and processed all the CSS in the page's <head>.

You can inspect this issue on an example website with a responsive background image.

In this example, the image download doesn't start until the CSS is fully downloaded, causing unnecessary lag to the image's display.

Responsive image preloading lets you load those images faster.

<link rel="preload" as="image" imagesrcset="cat.png 1x, cat-2x.png 2x" fetchpriority="high">

Leaving out the href attribute lets you ensure that browsers that don't support imagesrcset on the <link> element, but do support image-set in CSS download the correct source. However, they won't benefit from the preload in this case.

You can inspect how the previous example behaves with a preloaded responsive background image in the responsive background preload demo.

Here the image and CSS start downloading at the same time, letting the image load faster.

Practical effects of preloading responsive images

Preloading your responsive images can speed them up in theory, but what does it do in practice?

To answer that I created two copies of a demo PWA shop: one that doesn't preload images, and one that preloads some of them. Because the site lazy loads images using JavaScript, it's likely to benefit from preloading the ones that appear in the initial viewport.

That produced the following results for no preload and for image preload:

Start Render stayed the same.
Speed Index improved slightly (273 ms, as images arrive faster don't take up a huge chunk of the pixel area).
Last Painted Hero improved significantly, by 1.2 seconds.

Images arrive significantly faster when preloaded, greatly improving the user experience.

Preload and `<picture>`

The Web Performance Working Group is discussing adding a preload equivalent for srcset and sizes, but not the <picture> element, which handles the "art direction" use case.

There are still a number of technical issues to sort out for preloading <picture>, but in the meantime, there are workarounds:

<picture>
    <source srcset="small_cat.jpg" media="(max-width: 400px)">
    <source srcset="medium_cat.jpg" media="(max-width: 800px)">
    <img src="large_cat.jpg">
</picture>

The <picture> element's image source selection logic goes over the media attributes of the <source> elements in order, finds the first one that matches, and uses the attached resource.

Because responsive preload has no notion of "order" or "first match", you'll need to translate the breakpoints into something like the following:

<link rel="preload" href="small_cat.jpg" as="image" media="(max-width: 400px)" fetchpriority="high">
<link rel="preload" href="medium_cat.jpg" as="image" media="(min-width: 400.1px) and (max-width: 800px)" fetchpriority="high">
<link rel="preload" href="large_cat.jpg" as="image" media="(min-width: 800.1px)" fetchpriority="high">

Preload and `type`

The <picture> element also supports matching on the first type, to let you provide different image formats so the browser can pick the first image format it supports.

This use case is only partially supported with preload: browsers should only download preloads for supported types. So you can use this to prevent browsers preloading unsupported mimetypes types by including this in the preload:

<link rel="preload" href="image.avif" type="image/avif" as="image" fetchpriority="high">

However, unlike <picture> it won't stop at the first supported type. So if multiple preloads are included for multiple types, then all the images will be preloaded:

Don't do this — preload multiple types:

<link rel="preload" href="image.avif" type="image/avif" as="image" fetchpriority="high">
<link rel="preload" href="image.jpg" type="image/jpg" as="image" fetchpriority="high">

Instead do this — preload the most preferred type:

<link rel="preload" href="image.avif" type="image/avif" as="image" fetchpriority="high">

Preloading the newest format (AVIF in this case) acts as as a progressive enhancement, where browsers supporting that type will benefit and other browsers won't benefit from the preload.

For sites where the image is quickly discoverable in the HTML, we recommend avoiding preload, and instead having the preload scanner pick up the images from the <picture> and <source> elements instead. This is a best practice anyway, especially when using Fetch Priority for help prioritizing the appropriate image, as it allows the exact image to be preloaded based on browser support. It also removes the risk of a preload becoming outdated from the main markup when images or pages change.

Effects on Largest Contentful Paint (LCP)

Because images can be Largest Contentful Paint (LCP) candidates, preloading them can improve your website's LCP.

Regardless of whether the image you're preloading is responsive, preloads work best when the image resource isn't discoverable in the initial markup payload. You'll also get more LCP improvement on sites that render markup on the client side than on sites that send complete markup from the server.

Back/forward cache

Thu, 02 Jul 2026 07:00:00 GMT

Published: May 25, 2023, Last updated: July 2, 2026

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

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

Browser compatibility

All major browsers include a bfcache, including Chrome since version 96, Firefox and Safari.

bfcache basics

With back/forward cache (bfcache), instead of destroying a page when the user navigates away, we postpone destruction and pause JS execution. If the user navigates back soon, we make the page visible again and unpause JS execution. This results in a near instant page navigation for the user.

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:

Using bfcache makes pages load much more quickly during back and forward navigation.

In the video, 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 don't 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 plays its own role in speeding up repeat navigations. 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 very rare for all requests required to load a page to be fulfilled from the HTTP cache, repeat visits using bfcache restores are always faster than even the most well-optimized non-bfcache navigations.

Freezing a page to potentially re-enable it again later 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 any pending timers or unresolved promises for pages in bfcache, including almost all pending tasks in the JavaScript task queues, and resume processing tasks if the page is restored from the bfcache.

In some cases, such as for timeouts and promises, this is fairly low risk, but in other cases it can lead to 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, because 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 while 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.

The bfcache and iframes

If a page contains embedded iframes, then the iframes themselves are not separately eligible for the bfcache. For example, if you navigate to another URL within an iframe, the previous content does not enter bfcache and if you go back, the browser will go "back" within the iframe rather than in the main frame, but the back navigation within the iframe won't use the bfcache.

However, when the main frame is restored from the bfcache, embedded iframes will be restored as they were when the page entered the bfcache.

The main frame can also be blocked from using the bfcache if an embedded iframe uses APIs that block this. The Permissions Policy set on the main frame or the use of sandbox attributes can be used to avoid this.

The bfcache and Single Page Apps (SPA)

Because bfcache works with browser-managed navigations, it doesn't work for "soft navigations" within a single-page app (SPA). However, bfcache can still help when going back to an SPA rather than doing a full re-initialisation of that app again from the start.

APIs to observe bfcache

Although 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 are supported by most browsers.

The newer Page Lifecycle events—freeze and resume—are also dispatched when pages enter or leave bfcache, as well as in some other situations, for example, when a background tab gets frozen to minimize CPU usage. These events are 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 is true if the page was restored from bfcache and false otherwise. 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 fires when pages are restored from bfcache (immediately before the pageshow event) and when a user revisits a frozen background tab. If you want to update 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.

For details on bfcache measurement best practices, see How bfcache affects analytics and performance measurement.

Observe when a page is entering bfcache

The pagehide event fires either when a page unloads or when the browser tries to put it in the bfcache.

The pagehide event also has a persisted property. If it's false, you can be confident a that page isn't about to enter the bfcache. However, persisted being true doesn't guarantee that a page will be cached. It means the browser intends to cache the page, but there may be other 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 fires immediately after the pagehide event if persisted is true, but that only means the browser intends to cache the page. It might still have to discard it for a number of reasons explained later.

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 won't 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 won't 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, where all browsers use the WebKit rendering engine, and so behave like Safari.

Instead of using the unload event, use the pagehide event. The pagehide event fires in all cases where the unload event 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.

Warning: Never add an unload event listener! Use the pagehide event instead. Adding an unload event listener will make your site slower in Firefox, and the code won't even run most of the time in Chrome and Safari.

Due to its unreliability, and the performance impact for bfcache, Chrome is looking to deprecate the unload event.

Use Permission Policy to prevent unload handlers being used on a page

Sites that don't use unload event handlers can ensure these are not added by using a Permissions Policy.

Permissions-Policy: unload=()

This also prevents third parties or extensions from slowing the site down by adding unload handlers and making the site ineligible for the bfcache.

Only add `beforeunload` listeners conditionally

The beforeunload event won't make your pages ineligible for bfcache in modern browsers' bfcache but previously it did and it is still unreliable, 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?';
  }
});

This code 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);
});

This code 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. It's used for resources containing sensitive user information, such as pages behind a login.

Although 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 so any pages using Cache-Control: no-store may not be eligible for bfcache. There is work underway to change this behavior for Chrome in a privacy-preserving manner.

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 need 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 don't 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 don't 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:

window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    // Do any checks and updates to the page
  }
});

While ideally you would update the content in place, for some changes you may want to force a full reload. 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();
  }
});

A reload has the advantage that will still preserve the history (to allow forward navigations), but a redirect may be more appropriate in some cases.

Ads and bfcache restore

It may be tempting to try to avoid the use of bfcache to serve a new set of ads on each back/forward navigation. However, as well as having a performance impact, it is questionable whether such behavior leads to better ad engagement. Users may have noticed an ad they intended to return to click but by reloading rather than restoring from the bfcache they not be able to. Testing this scenario—ideally with an A/B test—is important before making assumptions.

For sites that do want to refresh ads on bfcache restore, then refreshing just the ads on the pageshow event when event.persisted is true allows this to happen without impacting the page performance. Check with your ad provider but here is one example on how to do this with Google Publishing Tag.

Avoid `window.opener` references

In older browsers, if a page was opened using window.open() from a link with target=_blank, without specifying rel="noopener", the opening page would 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 can't safely be put into 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 (note, this is now the default in all modern browsers). 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.

Close open connections before the user navigates away

As mentioned previously, when a page is held in the bfcache, it pauses all scheduled JavaScript tasks and resumes them 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) this can be problematic because pausing these tasks may prevent code in other tabs from running.

As a result, some browsers won't 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. Chrome (as of 149) and Safari do no block on open WebSockets but other browsers do.

If your page is using any of these APIs, we strongly recommend closing connections and removing or disconnecting observers during the pagehide or freeze event. That allows the browser to safely cache the page without the risk of affecting other open tabs.

Then, if the page is restored from the bfcache, you can reopen or reconnect to those APIs during the pageshow or resume event, or have them always automatically reopen using the error or close events. Ensure you do no open multiple connections if using multiple events.

The following example shows how to ensure that pages using IndexedDB are eligible for bfcache 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 leaves.
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 might prevent them from being eligible.

To test a page:

Navigate to the page in Chrome.
In DevTools, go to Application -> Back-forward Cache.
Click the Run Test button. DevTools then tries to navigate away and back to determine whether the page can be restored from bfcache.

The Back-forward Cache panel in DevTools.

If the test is successful, the panel reports "Restored from back-forward cache".

A successfully restored page.

If it's unsuccessful, the panel indicates the reason why. If the reason is something you can address as a developer, the panel marks it as Actionable.

A failed bfcache test with an actionable result.

In this example, the use of an unload event listener makes the page ineligible for bfcache. You can fix that by switching from unload to using pagehide:

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

Don't

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

Lighthouse 10.0 also added a bfcache audit, which performs a similar test. For more information, see the bfcache audit's docs.

How bfcache affects analytics and performance measurement

If you use an analytics tool to measure visits to your site, you might notice a decrease in the total number of pageviews reported as Chrome enables bfcache for more users.

In fact, you're likely already underreporting pageviews from other browsers that implement bfcache, because many popular analytics libraries don't measure bfcache restores as new pageviews.

To include bfcache restores in your pageview count, set listeners for the pageshow event and check the persisted property.

The following example shows how to do this with Google Analytics. Other analytics tools likely use similar logic:

// Send a pageview when the page is first loaded.
// This happens by default just by loading gtag
gtag('config', 'TAG_ID');

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

Measure your bfcache hit ratio

You may also want to measure whether the bfcache was used, to help identify pages that are not utilizing the bfcache. This can be done by measuring the navigation type for page loads:

// Send a navigation_type when the page is first loaded.
// To do this disable the default pageview so you can manually send it
// supplemented with the additional detail.
gtag('config', 'TAG_ID', { send_page_view: false });
gtag('event', 'page_view', {
   'navigation_type': performance.getEntriesByType('navigation')[0].type;
});

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

Calculate your bfcache hit ratio using the counts for back_forward navigations and back_forward_cache navigations.

It is important to realize that there are a number of scenarios, outside of the site owners control, when a Back/Forward navigation won't 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 reopens it

In some of these cases the original navigation type may be preserved by some browsers and so may show a type of back_forward despite these not being Back/Forward navigations.

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

So, website owners shouldn't 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 has added the NotRestoredReasons API to help expose the reasons why pages don't use bfcache, so developers can improve their bfcache hit rates. The Chrome team has also added navigation types to CrUX making it possible to see the number of bfcache navigations even without measuring it yourself.

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 lets you continue to monitor your performance within these navigation types, even if the overall distribution skews negative. We recommend this approach 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.

Caution: The back_forward navigation type in the Navigation Timing API is not to be confused with bfcache restores. The Navigation Timing API only annotates page loads, whereas bfcache restores are re-using a page loaded from a previous navigation.

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 full 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 that collect and report on the Core Web Vitals metrics, like the Chrome User Experience Report, treat bfcache restores as separate page visits in their dataset. And while there aren't dedicated web performance APIs for measuring these metrics after bfcache restores, you can approximate their values using existing web APIs:

For Largest Contentful Paint (LCP), use the delta between the pageshow event's timestamp and the timestamp of the next painted frame, because all elements in the frame will be painted at the same time. In the case of a bfcache restore, LCP and FCP are the same.
For Interaction to Next Paint (INP), keep using your existing Performance Observer, but reset the current INP value to 0.
For Cumulative Layout Shift (CLS), keep using your existing Performance Observer, but reset the current CLS value to 0.

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

The web-vitals JavaScript library supports bfcache restores in the metrics it reports.

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)

Lazy loading video

Thu, 02 Jul 2026 07:00:00 GMT

Published: August 16, 2019, Last updated: July 2, 2026

As with image elements, you may also want to lazy-load video. Videos are commonly loaded with the <video> element, though for videos hosted on other services such as YouTube they may use <iframe>s (in which case check out the article in lazy-loading iframes).

How to lazy-load <video> depends on the use case, as there are a couple of different solutions.

Using the `loading` attribute

Browsers have started to support the loading attribute on media elements (<video> and <audio>). Where supported this means both the media and any poster image are automatically lazy-loaded just by adding the loading="lazy" attribute:

<video controls loading="lazy" preload="none" poster="one-does-not-simply-placeholder.jpg">
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

Using loading="lazy" will prevent the poster image from loading at all, until in or near the viewport, and then will use the preload attribute to decide how much of the video to load. This also means autoplay videos won't autoplay until in or near the viewport. The loading="lazy" attribute works with poster, preload, and autoplay attributes and does not replace the need for them.

Browsers that don't support loading attribute on media elements will ignore this attribute, which will result in the poster image loading immediately, and the video loading based on the preload attribute, which we will cover next.

Use the `preload` attribute to lazy-load video that doesn't autoplay

Avoiding autoplaying videos is usually best practice as it leaves the control with the user. In these cases specifying the preload attribute on the <video> element is the best way to avoid loading the whole video until needed:

<video controls loading="lazy" preload="none" poster="one-does-not-simply-placeholder.jpg">
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

The previous example uses a preload attribute with a value of none to prevent browsers from preloading any video data, even when in the viewport. The poster attribute gives the <video> element a placeholder that will occupy the space while the video loads.

In most browsers preload defaults to metadata and a portion of the video is preloaded using the Content-Range header. This can result in more data being downloaded than desired—browsers cannot know what bytes the metadata is stored at, and it may not be stored at the beginning of the file. Therefore, the best chance of avoiding loading the video is with using preload="none".

This can be further enhanced to preload the metadata when the user hovers the video with an onmouseenter attribute (or with the equivalent mouseenter event handler):

<video controls
  loading="lazy"
  preload="none"
  poster="one-does-not-simply-placeholder.jpg"
  onmouseenter="event.target.setAttribute('preload','metadata')">
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

This not only reduces the delay when the user goes to play the video, but also shows the duration of the video as soon as they.

Videos can qualify as LCP candidates. A poster image will be quicker to load than the video so where this is an LCP candidate, you should use a poster image, but also preload it with a fetchpriority attribute value of "high", since at the time of writing you cannot specify the fetchpriority for poster attributes:

<link rel="preload" href="one-does-not-simply-placeholder.jpg" as="image" fetchpriority="high">
<video controls preload="none"
  poster="one-does-not-simply-placeholder.jpg"
  onmouseenter="event.target.setAttribute('preload','metadata')">
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

Videos that are LCP elements shouldn't use loading="lazy"—in the same way that you shouldn't lazy load LCP images videos.

For video acting as an animated GIF replacement

Autoplaying videos are commonly used for GIF-style quick animations. While animated GIFs enjoy wide use, they're subpar to video equivalents in a number of ways, particularly in file size. Animated GIFs can stretch into the range of several megabytes of data. Videos of similar visual quality tend to be far smaller.

Using the <video> element as a replacement for animated GIF is not as straightforward as the <img> element. Animated GIFs have three characteristics:

They play automatically when loaded.
They loop continuously (though that's not always the case).
They don't have an audio track.

Achieving this with the <video> element looks something like this:

<video autoplay muted loop playsinline>
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

The loading="lazy" attribute avoids loading the video until near the viewport. The autoplay, muted, and loop attributes are self-explanatory. playsinline is necessary for autoplaying to occur in iOS.

Now you have a serviceable video-as-GIF replacement that works across platforms. But how to go about lazy loading it?

For browsers that support this the loading="lazy" is the easiest option:

<video loading="lazy" autoplay muted loop playsinline>
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

To support lazy-loading of video in other browsers you need to use JavaScript and modify your <video> markup accordingly:

<video class="lazy" preload="none" controls muted loop playsinline width="610" height="254" poster="one-does-not-simply.jpg">
  <source src="one-does-not-simply.webm" type="video/webm">
  <source src="one-does-not-simply.mp4" type="video/mp4">
</video>

You'll notice the removal of autoplay, and the addition of the class="lazy", preload="none" and poster attributes, which lets you specify a placeholder to occupy the <video> element's space until the video is lazy-loaded. Then, we use a JavaScript Intersection Observer to re-enabled the autoplaying:

document.addEventListener("DOMContentLoaded", function() {
  var lazyVideos = [].slice.call(document.querySelectorAll("video.lazy"));

  if ("IntersectionObserver" in window) {
    var lazyVideoObserver = new IntersectionObserver(function(entries, observer) {
      entries.forEach(function(video) {
        if (video.isIntersecting) {
          video.target.removeAttribute('preload');
          video.target.removeAttribute('controls');
          video.target.autoplay = true;
          video.target.classList.remove("lazy");
          lazyVideoObserver.unobserve(video.target);
        }
      });
    });

    lazyVideos.forEach(function(lazyVideo) {
      lazyVideoObserver.observe(lazyVideo);
    });
  }
});

Using this method, the video does not autoplay by default and only when the intersection observer detects the video as entering the viewport. Additionally, the controls attribute handles the cases when the JavaScript fails. Together this means you have a video solution that emulates animated GIF behavior, but doesn't incur the same intensive data usage as animated GIFs do, and you can lazy-load that content.

Lazy loading libraries

The following libraries can help you to lazy-load video:

vanilla-lazyload and lozad.js are super lightweight options that use Intersection Observer only. As such, they are highly performant, but will need to be polyfilled before you can use them on older browsers.
If you need a React-specific lazy loading library, you might consider react-lazyload. While it doesn't use Intersection Observer, it does provide a familiar method of lazy loading images for those accustomed to developing applications with React.

Each of these lazy loading libraries is well documented, with plenty of markup patterns for your various lazy loading endeavors.

As the loading attribute for <video> becomes available in more browsers we expect JavaScript solutions (including libraries) to be used less in favor of the built-in solutions, except for those that want more control than that allows.

Rendering on the Web

Mon, 05 Jan 2026 08:00:00 GMT

Published: February 6, 2019, Last updated: January 5, 2026

One of the core decisions web developers must make is where to implement logic and rendering in their application. This can be difficult because there are so many ways to build a website.

Our understanding of this space is informed by our work in Chrome talking to large sites over the past few years. Broadly speaking, we encourage developers to consider server-side rendering or static rendering over a full rehydration approach.

To better understand the architectures we're choosing from when we make this decision, we need consistent terminology and a shared framework for each approach. Then, you can better evaluate the tradeoffs of each rendering approach from the perspective of page performance.

Terminology

First, we define some terminology we will use.

Rendering

Server-side rendering (SSR): Rendering an app on the server to send HTML, rather than JavaScript, to the client.
Client-side rendering (CSR): Rendering an app in a browser, using JavaScript to modify the DOM.
Prerendering: Running a client-side application at build time to capture its initial state as static HTML. Note "prerendering" in this sense is different to browser prerendering of future navigations.
Hydration: Running client-side scripts to add application state and interactivity to server-rendered HTML. Hydration assumes the DOM doesn't change.
Rehydration: While often used to mean the same thing as hydration, rehydration implies regularly updating the DOM with the latest state, including after the initial hydration.

Performance

Time to First Byte (TTFB): The time between clicking a link and the first byte of content loading on the new page.
First Contentful Paint (FCP): The time when requested content (article body, etc) becomes visible.
Interaction to Next Paint (INP): A representative metric that assesses whether a page consistently responds quickly to user inputs.
Total Blocking Time (TBT): A proxy metric for INP that calculates how long the main thread was blocked during page load.

Server-side rendering

Server-side rendering generates the full HTML for a page on the server in response to navigation. This avoids additional round trips for data fetching and templating on the client, because the renderer handles them before the browser gets a response.

Server-side rendering generally produces a fast FCP. Running page logic and rendering on the server lets you avoid sending lots of JavaScript to the client. This helps to reduce a page's TTBT, which can also lead to a lower INP, because the main thread isn't blocked as often during page load. When the main thread is blocked less often, user interactions have more opportunities to run sooner.

This makes sense, because with server-side rendering, you're really just sending text and links to the user's browser. This approach can work well for a variety of device and network conditions and opens up interesting browser optimizations, such as streaming document parsing.

FCP and TTI with server-side rendering.

With server-side rendering, users are less likely to be left waiting for CPU-bound JavaScript to run before they can use your site. Even when you can't avoid third-party JavaScript, using server-side rendering to reduce your own first-party JavaScript costs can give you more budget for the rest. However, there is one potential trade-off with this approach: generating pages on the server takes time, which can increase your page's TTFB.

Whether server-side rendering is enough for your application largely depends on what type of experience you're building. There's a long-standing debate over the correct applications of server-side rendering versus client-side rendering, but you can always choose to use server-side rendering for some pages and not others. Some sites have adopted hybrid rendering techniques with success. For example, Netflix server-renders its relatively static landing pages, while prefetching the JavaScript for interaction-heavy pages, giving these heavier client-rendered pages a better chance of loading quickly.

With many modern frameworks, libraries, and architectures, you can render the same application on both the client and the server. You can use these techniques for server-side rendering. However, architectures where rendering happens both on the server and on the client are their own class of solution with very different performance characteristics and tradeoffs. React users can use server DOM APIs or solutions built on them like Next.js for server-side rendering. Vue users can use Vue's server-side rendering guide or Nuxt. Angular has Universal.

Most popular solutions use some form of hydration, though, so be aware of the approaches your tool uses.

Static rendering

Static rendering happens at build time. This approach offers a fast FCP, and also a lower TBT and INP, as long as you limit the amount of client-side JavaScript on your pages. Unlike server-side rendering, it also achieves a consistently fast TTFB, because the HTML for a page doesn't have to be dynamically generated on the server. Generally, static rendering means producing a separate HTML file for each URL ahead of time. With HTML responses generated in advance, you can deploy static renders to multiple CDNs to take advantage of edge caching.

FCP and TTI with static rendering.

Solutions for static rendering come in all shapes and sizes. Tools like Gatsby are designed to make developers feel like their application is being rendered dynamically, not generated as a build step. Static site generation tools such as 11ty, Jekyll, and Metalsmith embrace their static nature, providing a more template-driven approach.

One of the downsides to static rendering is that it must generate individual HTML files for every possible URL. This can be challenging or even infeasible when you need to predict those URLs ahead of time and for sites with a large number of unique pages.

React users might be familiar with Gatsby, Next.js static export, or Navi, all of which make it convenient to create pages from components. However, static rendering and prerendering behave differently: statically rendered pages are interactive without needing to execute much client-side JavaScript, whereas prerendering improves the FCP of a Single Page Application that must be booted on the client to make pages truly interactive.

If you're unsure whether a given solution is static rendering or prerendering, try disabling JavaScript and load the page you want to test. For statically rendered pages, most interactive features still exist without JavaScript. Prerendered pages might still have some basic features like links with JavaScript disabled, but most of the page is inert.

Another useful test is to use network throttling in Chrome DevTools and see how much JavaScript downloads before a page becomes interactive. Prerendering generally needs more JavaScript to become interactive, and that JavaScript tends to be more complex than the progressive enhancement approach used in static rendering.

Server-side rendering versus static rendering

Server-side rendering isn't the best solution for everything, because its dynamic nature can have significant compute overhead costs. Many server-side rendering solutions don't flush early, delay TTFB, or double the data being sent (for example, inlined states used by JavaScript on the client). In React, renderToString() can be slow because it's synchronous and single-threaded. Newer React server DOM APIs support streaming, which can get the initial part of an HTML response to the browser sooner while the rest of it is still being generated on the server.

Getting server-side rendering "right" can involve finding or building a solution for component caching, managing memory consumption, using memoization techniques, and other concerns. You're often processing or rebuilding the same app twice, once on the client and once on the server. Server-side rendering showing content sooner doesn't necessarily give you less work to do. If you have a lot of work on the client after a server-generated HTML response arrives on the client, this can still lead to higher TBT and INP for your website.

Server-side rendering produces HTML on demand for each URL, but it can be slower than just serving static rendered content. If you can put in the additional legwork, server-side rendering plus HTML caching can significantly reduce server render time. The upside to server-side rendering is the ability to pull more "live" data and respond to a more complete set of requests than is possible with static rendering. Pages that need personalization are a concrete example of the type of request that doesn't work well with static rendering.

Server-side rendering can also present interesting decisions when building a PWA. Is it better to use full-page service worker caching, or server-render individual pieces of content?

Client-side rendering

Client-side rendering means rendering pages directly in the browser with JavaScript. All logic, data fetching, templating, and routing are handled on the client instead of on the server. The effective outcome is that more data is passed to the user's device from the server, and that comes with its own set of tradeoffs.

Client-side rendering can be difficult to make and keep fast for mobile devices. With a little work to keep a tight JavaScript budget and deliver value in as few round-trips as possible, you can get client-side rendering to almost replicate the performance of pure server-side rendering. You can get the parser to work for you faster by delivering critical scripts and data using <link rel=preload> We also recommend considering using patterns like PRPL to ensure that initial and subsequent navigations feel instant.

FCP and TTI with client-side rendering.

The primary downside to client-side rendering is that the amount of JavaScript required tends to grow as an application grows, which can impact a page's INP. This becomes especially difficult with the addition of new JavaScript libraries, polyfills, and third-party code, which compete for processing power and must often be processed before a page's content can render.

Experiences that use client-side rendering and rely on large JavaScript bundles should consider aggressive code-splitting to lower TBT and INP during page load, as well as lazy-loading JavaScript to serve only what the user needs, when it's needed. For experiences with little or no interactivity, server-side rendering can represent a more scalable solution to these issues.

For folks building single page applications, identifying core parts of the user interface shared by most pages lets you apply the application shell caching technique. Combined with service workers, this can dramatically improve perceived performance on repeat visits, because the page can load its application shell HTML and dependencies from CacheStorage very quickly.

Rehydration combines server-side and client-side rendering

Hydration is an approach that mitigate the tradeoffs between client-side and server-side rendering by doing both. Navigation requests, like full page loads or reloads, are handled by a server that renders the application to HTML. Then the JavaScript and data used for rendering is embedded into the resulting document. When done carefully, this achieves a fast FCP like server-side rendering, then "picks up" by rendering again on the client.

This is an effective solution, but it can have considerable performance drawbacks.

The primary downside of server-side rendering with rehydration is that it can have a significant negative impact on TBT and INP, even if it improves FCP. Server-side rendered pages can appear to be loaded and interactive, but can't actually respond to input until the client-side scripts for components are executed and event handlers have been attached. On mobile, this can take minutes, confusing and frustrating the user.

A rehydration problem: one app for the price of two

For the client-side JavaScript to accurately take over where the server left off, without re-requesting all the data the server rendered its HTML with, most server-side rendering solutions serialize the response from a UI's data dependencies as script tags in the document. Because this duplicates a lot of HTML, rehydration can cause more problems than just delayed interactivity.

HTML document containing serialized UI, inlined data and a bundle.js script.

The server is returning a description of the application's UI in response to a navigation request, but it's also returning the source data used to compose that UI, and a complete copy of the UI's implementation which then boots up on the client. The UI doesn't become interactive until after bundle.js has finished loading and executing.

Performance metrics collected from real websites using server-side rendering and rehydration indicate that it's rarely the best option. The most important reason is its effect on the user experience, when a page looks ready but none of its interactive features work.

The negative effects of client-side rendering on TTI.

There's hope for server-side rendering with rehydration. In the short term, only using server-side rendering for highly cacheable content can reduce TTFB, producing similar results to prerendering. Rehydrating incrementally, progressively, or partially might be the key to making this technique more viable in the future.

Stream server-side rendering and rehydrate progressively

Server-side rendering has had a number of developments over the last few years.

Streaming server-side rendering lets you send HTML in chunks that the browser can progressively render as it's received. This can get markup to your users faster, speeding up your FCP. In React, streams being asynchronous in renderToPipeableStream(), compared to synchronous renderToString(), means backpressure is handled well.

Progressive rehydration is also worth considering (React has implemented it). With this approach, individual pieces of a server-rendered application are "booted up" over time, instead of the current common approach of initializing the entire application at once. This can help reduce the amount of JavaScript needed to make pages interactive, because it lets you defer client-side upgrading of low-priority parts of the page to prevent it from blocking the main thread, letting user interactions happen sooner after the user initiates them.

Progressive rehydration can also help you avoid one of the most common server-side rendering rehydration pitfalls: a server-rendered DOM tree gets destroyed and then immediately rebuilt, most often because the initial synchronous client-side render required data that wasn't quite ready, often a Promise that hasn't resolved yet.

Partial rehydration

Partial rehydration has proven difficult to implement. This approach is an extension of progressive rehydration that analyzes individual pieces of the page (components, views, or trees) and identifies the pieces with little interactivity or no reactivity. For each of these mostly-static parts, the corresponding JavaScript code is then transformed into inert references and decorative features, reducing their client-side footprint to nearly zero.

The partial rehydration approach comes with its own issues and compromises. It poses some interesting challenges for caching, and client-side navigation means we can't assume that server-rendered HTML for inert parts of the application are available without a full page load.

Trisomorphic rendering

If service workers are an option for you, consider trisomorphic rendering. This technique lets you use streaming server-side rendering for initial or non-JavaScript navigations, and then have your service worker take on rendering of HTML for navigations after it has been installed. This can keep cached components and templates up to date and enable SPA-style navigations for rendering new views in the same session. This approach works best when you can share the same templating and routing code between the server, client page, and service worker.

Trisomorphic rendering, demonstrating a browser and service worker communicating with the server.

SEO considerations

When choosing a web rendering strategy, teams often consider the impact of SEO. Server-side rendering is a popular choice for delivering a "complete looking" experience that crawlers can interpret. Crawlers can understand JavaScript, but there are often limitations to how they render. Client-side rendering can work, but often needs additional testing and overhead. More recently, dynamic rendering has also become an option worth considering if your architecture depends heavily on client-side JavaScript.

Conclusion

When deciding on an approach to rendering, measure and understand what your bottlenecks are. Consider whether static rendering or server-side rendering can get you most of the way there. It's fine to mostly ship HTML with minimal JavaScript to get an experience interactive. Here's a handy infographic showing the server-client spectrum:

Rendering options and their tradeoffs.

Credits

Thanks to everyone for their reviews and inspiration:

Jeffrey Posnick, Houssein Djirdeh, Shubhie Panicker, Chris Harrelson, and Sebastian Markbåge.

Why is CrUX data different from my RUM data?

Wed, 17 Dec 2025 08:00:00 GMT

Learn about reasons why RUM data can show different Core Web Vitals numbers from CrUX.

Published: August 15, 2022, Last updated: December 17, 2025

The Chrome User Experience Report (CrUX) provides user experience metrics for how real-world Chrome users experience popular destinations on the web. This data is automatically collected by Chrome from users who have opted in, and is made available based on the CrUX eligibility criteria.

CrUX data is therefore available for millions of websites. Many site owners have not had access to field data before, and CrUX has enabled many sites to see the value of this for the first time. As a public dataset, CrUX can also be used for competitive analysis and benchmarking of user experience metrics.

Real User Monitoring (RUM) is similar to CrUX, but instead of Chrome automatically collecting user-experience metrics, code is included on the websites to do this collection and feed it back to a RUM provider or analytics solution for further analysis.

With both solutions measuring user experience metrics, it is natural to assume that they should be equivalent. It can be confusing when we see differences. This guide will explain why that can happen, and offers suggestions for what to do when the numbers don't align.

Benefits of supplementing CrUX with a RUM solution

CrUX is a great tool for a consistent view across sites and—as the Google dataset for the Core Web Vitals program—sites will likely want to keep an eye on what it is showing. The aim of CrUX is to provide a statistically relevant overview of millions of websites for cross comparison.

However, for a deeper dive in investigating why data is showing the numbers it is, investing in a full RUM solution to supplement CrUX can give you access to more detailed information than can be made available in a publicly queryable dataset. This can help you explain and improve your metrics in a number of ways.

Deeper analysis to investigate issues

CrUX can often be used to point out if you have a problem on your site, but not necessarily exactly where on your site the issue lies nor why. RUM solutions—whether home-grown through the likes of the web-vitals library or some of the many commercial products—can help bridge that gap.

Using a RUM solution gives you access to much more fine-grained data for all your pages, and on all browsers. It also lets you segment and analyze this data in ways CrUX does not, enabling you to drill down and investigate problem areas of the site. Are they affected by a particular segment of users? Or users who take certain actions? Exactly when did the problem start? These are questions that are much easier to answer with the additional data that a RUM tool can provide.

Correlate with other business metrics

RUM also lets you compare your web performance metrics directly with any business metrics, showing the value in investing in performance, and what other performance work to prioritize. We have numerous case studies with businesses doing this correlation, such as Farfetch or The Economic Times.

Collect other performance data

A RUM solution allows collection of other custom metrics, tied directly to your specific business. One of the more well-known examples is Twitter's "Time to first Tweet" metric. These site-specific measures can then be correlated with Core Web Vital improvements and business metrics.

Differences between two sets of field data

A man with a watch knows what time it is. A man with two watches is never sure.
Segal's Law

Whenever you have two sources of data, it can often be confusing and frustrating as to why they differ. In much the same way as it's important to understand the difference between lab and field metrics, there can also be differences between two sources of field data. While the data would be the same in an ideal world, there are many reasons why they can differ.

Lab data versus field data

The first thing to check is whether you are looking at lab (synthetic) metrics or field (RUM) metrics. While it's natural to assume RUM products only look at field data, many offer a lab component as well.

Lab data is incredibly useful precisely because of the fixed conditions it measures under. It can be used to monitor unexpected changes or regressions in a production environment without the noise of a changing field population. However, lab data may not be representative of the real user experience, so field metrics can show quite different results.

Populations

The datasets used by CrUX and RUM solutions may be different due to differences in which page visits are being measured depending on which browsers, users, sites, and devices are being compared.

Included browsers

The Chrome User Experience Report, as its name suggests, is Chrome-only. While there are many Chromium-based browsers (Edge, Opera, and Brave to name a few) that shares a lot of the Chrome codebase, only Chrome users feed data into CrUX. This restriction also means Chrome users on iOS are not included, since it uses the underlying Webkit browser engine. Android WebViews also don't count as "Chrome", so data from these users is not included—though Chrome Custom Tabs are included.

While Chrome is one of the world's most popular browsers—and therefore would likely give a broad representation of your site's performance in most cases—measuring just that browser is by no means a measure of all your users. This may explain one main difference between RUM and CrUX. This is particularly true for performance techniques that rely on APIs or image formats only available in Chrome, for example.

The lack of iOS data can also lead to bias. For example, as iOS users are typically on more performant devices or visiting from more countries with better network infrastructure, including them can lead to high overall performance metrics. On the other hand, excluding them—as CrUX does—can lead to data that is skewed to the lower end of site visitors (example case study). Android users typically cover a wider range of devices, device capabilities, and markets.

RUM solutions can get data for non-Chrome browsers, and in particular from Chromium-based browsers that often have the same metrics (such as Core Web Vitals) built-in. Non-Chromium-based browsers are also measured by RUM solutions, but may have a more limited set of metrics. For example, Cumulative Layout Shift (CLS) is only available in Chromium-based browsers. Some other paint-based metrics like LCP, INP, and even First Contentful Paint (FCP) can be measured quite differently (see later).

Opted-in users

As well as being limited to Chrome users, CrUX is further restricted by only measuring a subset of Chrome users who have opted in to share CrUX data when the browser was installed.

RUM providers also only look at a subset of users, usually due to cookie banner prompts—asking users to opt into RUM data collection—or tracking blockers. This can adversely affect some initial page loads if the confirmation is not given until the second or subsequent page, when some of the site assets have already been cached from previous pages. If this happens frequently, the metrics may appear more favorable in RUM than they actually are if slower initial page loads are excluded in a sufficient number of cases.

Included sites

CrUX is only intended to report on public websites, so there are other eligibility criteria that may result in data not being logged in CrUX. Most notable of these criteria is that the website must be publicly discoverable and sufficiently popular to ensure a minimal sample size from which to draw meaningful conclusions. In most cases, this will result in no data being available in CrUX. This is less of a confusing difference compared to the data being available but different, but explains why that happens.

However, if specific pages of a site are marked as indexable but others are not, then you may only see a subset of URLs in CrUX. If the origin is publicly discoverable, then all page views within that origin will be included in the origin-level data, but URL-level data may not be available.

Devices

CrUX segments data by mobile, desktop, and tablet - though many tools concentrate on the first two and may not expose tablet data, or may include it within mobile or desktop. The performance characteristics on mobile versus desktop can be quite different—both in terms of the content delivered, and in the capabilities of the devices viewing them.

RUM data will allow segmenting traffic similarly, but often shows consolidated data by default. RUM may only allow segmenting by device type (for example, mobile) or browser (for example, Chrome), but not both to only see mobile Chrome traffic. When comparing to CrUX data, ensure you are comparing like-for-like by filtering by device type and the Chrome browser.

Sampling

RUM solutions typically allow adjusting the sampling rate of opted-in visitors where data is collected. This can be used to reduce the volume of data needed to be analyzed, and to reduce costs of commercial RUM services. If that sample size is too small and not representative of the wider population, then the resulting metrics will also be similarly skewed. Discuss with your RUM provider the appropriate sampling size for your site.

Aggregation of data

Field data by its very nature will include many, many data points of the same metrics compared to lab data, which will give a single value. If this data is aggregated differently for reporting, it can lead to another reason for differences between CrUX and RUM.

Timespan

CrUX data is based on a 28 day sliding window of traffic, and it is not possible to change this timeframe—though the CrUX BigQuery data is stored for each month, allowing you to see previous months, and the CrUX History API also gives historical data over a weekly period. Both still provide data based on the 28 day sliding window.

RUM data typically allows much greater granularity to allow seeing the impact of changes much sooner. When choosing smaller periods, though, RUM data can be unduly impacted by fluctuations in website traffic and visitors. When comparing RUM data to CrUX data, always ensure you are looking at performance over 28 days. Once you are satisfied the data is similar, you can look at other time frames to drill into the RUM data.

Aggregation of statistics

CrUX metrics are measured at the 75th percentile—that is, looking at the value that 75% of page views achieved. There will be extremes in field data and removing the worst 25% experiences, it is intended to give a value that the majority of visitors can reasonably be expected to achieve.

RUM products often give a wider number of options of how to aggregate the metrics, including 75th percentile, median and other percentiles. If comparing RUM values to CrUX data, it is necessary to ensure you are looking at 75th percentile data to compare like-for-like.

The histogram data in CrUX includes all available data—not just 75th percentile—and shows the number of page views in each rating, but the aggregate score will be based on 75th percentile. This CrUX data is surfaced in tools like PageSpeed Insights:

PageSpeed Insights shows CrUX 75th percentile and histogram data

Differences in metrics

There are many metrics used to measure web performance, so when comparing two different sets of data, it's important to understand what metrics are being measured, and how those metrics are being used.

Metrics measured

CrUX data is the Google dataset of the Core Web Vitals initiative and primarily measures these metrics (LCP, CLS, and INP), with a few additional metrics to complement these.

RUM tools usually include these Core Web Vitals, but often include many other metrics too. Some RUM providers also measure the user experience using their own combination of all these metrics perhaps to give a "happiness index" or such. When comparing RUM data to CrUX, ensure you are comparing like-for-like.

Tools that assess Core Web Vitals pass or fail status should consider a page passing if it meets the recommended targets at the 75th percentile for all Core Web Vitals. If INP is not present for pages with no interactions, then only LCP and CLS need to pass.

Metric differences across browsers

CrUX only measures in Chrome browsers, and you can refer to the Web Vitals Changelogs to see how these change with each version of Chrome.

RUM solutions, however, will measure from a wider variety of browsers. Chromium-based browsers (Edge, Opera, and so on) will likely be similar to Chrome, unless Chrome is implementing new changes as noted in the Changelog.

For non-Chromium browsers, the differences can be more pronounced. paint based metrics like LCP, INP and FCP, for example, are available in Safari and Firefox, but is measured in a different way. This can lead to significant variances in the times reported. As stated previously, if you are wanting to compare RUM to CrUX, it is best to filter on just Chrome users to allow for a like-for-like comparison.

Metrics timing

Core Web Vitals metrics are provided by web browser APIs, but that does not mean there is not a potential for differences of values reported using them. Exactly when the metric measurement is taken—at page load or throughout the full page life cycle—can lead to differences. RUM tools may not always measure metrics in the same way—even if using the same names—and the same browser APIs to get the data, which can be confusing.

Largest Contentful Paint (LCP) is a page-load metric. A number of LCP elements can be reported by the Web API if larger elements are loaded later after the initial render. The final LCP element is when the page finishes loading or the user interacts with the page. Therefore differences can arise if the LCP element is reported earlier than those two events.

Additionally, in field data, the LCP element can be different depending on how the page is loaded. For a default page load showing the top of the page content, the LCP element will depend primarily on the screen size. However, if the page is opened with an anchor link further down the document, or similarly opened with a deep-link into a Single Page App (SPA)—more on that later—then the LCP element can be different.

Don't assume that the LCP timings provided in either CrUX nor RUM are based on the same element as lab tools. While CrUX will give you the overall LCP value per page or origin, RUM can segment this further to identify individual LCP problem sessions.

Cumulative Layout Shift (CLS) is measured throughout the life of the page, so the initial page-load CLS may not be representative of pages that cause greater shifts later after the page has loaded and the user has interacted with it. Taking the CLS value only after the page load—as many RUM products do—will therefore give a different result than taking the CLS value after the user finishes with the page.

Interaction to Next Paint (INP) responsiveness metric requires an input to be measured, and observes all click, tap, and keyboard interactions throughout the life of the page, in a similar fashion to CLS, and so the reported value of INP may be very different if measured after the user has made a number of interactions on the page.

CrUX will follow the Core Web Vitals documentation and measure these through the full lifetime of the page. Many RUM providers choose instead to measure these metrics either after page load, or at some other time (for example, when a key call-to-action is clicked) for various reasons.

Getting an understanding from your RUM provider as to when Core Web Vitals are measured is important when seeing unexplained variances between the two data sources.

Single-page applications

Single-page applications (SPA) work by updating the content on the current page, rather than performing actual page navigations at the browser level. This means the browser does not see these as page navigations, despite users experiencing them as such. The Core Web Vitals APIs provided by the browser won't take these into consideration, and therefore CrUX does not support these page navigations. Work is underway to resolve this issue—see the Measuring soft navigations post for more information.

Some RUM providers do attempt to detect "soft navigations" in SPAs, but if they're also attributing Core Web Vitals metrics to those "soft navigations" it will lead to differences with CrUX since the underlying APIs don't support this for many of the metrics.

CrUX and Web API differences

As well as the differences in which page views are measured, and what is measured, there are a few other, more complicated, scenarios to be aware of that can lead to differences in CrUX and RUM data. Some of these are due to limitations of the Web APIs used to measure the metrics, and some are where the results returned by the API need to be treated differently for certain scenarios. The Core Web Vitals documentation lists these differences for LCP and CLS but the main differences are also noted in the following sections.

Back/forward cache

CrUX considers Back/forward cache (or bfcache) restores as page navigations even though they don't result in a conventional page load. As the Web APIs don't treat these as a page load, RUM solutions need to take extra steps for these pages to be counted if they want to match CrUX. These are considerably faster page loads that can result in overall better performance being reported for a site, so not including them can result in worse overall page performance metrics. Refer to your RUM solution to understand if they handle bfcache restored pages.

Iframes

For security and privacy reasons, top-level pages don't have access to content within iframes (not even same-origin iframes). This means performance metrics for content in those can only be measured by the iframe itself, and not through the Web APIs on the framing page. If the iframe content includes the LCP element, or content that impacts the CLS or INP experienced by the user, this won't be available to RUM solutions (including the Google web-vitals JavaScript library).

CrUX however, being measured by the Chrome browser itself rather than JavaScript on the page, does not have these limitations and so does measure metrics within iframes when reporting Core Web Vitals. This more accurately reflects what the user experiences, but can be another reason for differences for sites making use of iframes.

One concrete example of how this can lead to differences between LCP data in CrUX and RUM is embedded <video>. An playsinline autoplaying <video> element's first painted frame can count as an LCP candidate, but embeds for popular video streaming services may place these elements in an <iframe>. CrUX can account for this, as it can access <iframe> contents, but RUM solutions cannot.

Cross-origin resources

LCP media served from other domains may not give render time in the PerformanceObserver API—unless the Timing-Allow-Origin header (TAO) is provided—due to browser security restrictions to reduce timing attacks. This falls back to the load time of the resource but this may be quite different from when the content was actually painted.

This can lead to the seemingly impossible situation where LCP is reported by web APIs as earlier than FCP. This is not the case but only appears so due to this security restriction.

This was resolved in late 2024 and a slightly coarsened render time is available from Chrome 133 even when Timing-Allow-Origin is not provided.

Again, CrUX does report the render time data for Core Web Vitals. Sites are advised to limit cross-origin content that impacts the Core Web Vitals metrics and to enable TAO where possible if they want to measure this more accurately. Other cross-origin resources may be subject to similar restrictions.

Background tabs

When a page is not opened in a background tab they will still emit metrics using Web APIs. However, these are not reported by CrUX since they give timings that are inconsistent with the user experience. RUM solutions should also consider ignoring these, or at least explaining how these page views are treated.

So what can we do about it?

We have shown why there may be differences between CrUX and RUM data, either due to differences in the methodology each uses or due to which users and page views are included or excluded. Ideally, both sets of data will still be representative of your site performance to be useful, but the reasons given should outline why it is very unlikely to get the exact same numbers in each.

Where differences are slight (for example reporting a LCP of 2.0 seconds versus 2.2 seconds) both datasets will be useful and can usually be considered to be roughly in sync.

When pronounced differences make you question the accuracy of the data, you should try to understand those differences. Can the RUM data be filtered to be more closely aligned with CrUX (looking only at Chrome users, for desktop or mobile, with 75th percentile values over 28 days) to reduce these differences?

If so—and you can get the data to match more closely—then you should still ask why you are seeing these differences in the overall data and what this means. Are non-Chrome users skewing your metrics in a positive or negative way? Does this give you more insights into where you have performance issues that you can prioritize?

If your non-Chrome users are getting different results then you can use this valuable insight that RUM has given you to optimize differently. For example, certain APIs are not available on certain browsers, but you can consider alternatives for unsupported browsers to also improve their experiences. Or you can give a different, but more performant, experience to users on constrained devices or networks. CrUX is limited to Chrome data, but you should consider all your site visitors' experiences to help prioritize improvements. RUM data can fill that gap.

Once you understand the reasons for any differences, both tools can be incredibly useful to understand the user experiences of your website, and to help improve this even if the numbers are not identical. Use your RUM data to complement CrUX data and allow you to dig into what CrUX is telling you at a high level by segmenting your traffic to help you identify if it's particular areas of your site or user base that need attention.

Looking at the trends to see your improvements are having the expected positive impacts is often more important than having each number match exactly between the two data sources. As mentioned previously, RUM lets you look at different time frames to get an advance look at what your 28 day CrUX scores will be—though looking at too short time frames can lead to noisy data, hence why CrUX uses 28 days.

Often there is no "right" or "wrong" answer in these different metrics - they are just a different lens on your users and how they are experiencing your site. As long as you understand why these differences happen, and what that can do to drive your decision making, that is what is more important to better serve your site visitors.

Acknowledgements

Thumbnail image by Steven Lelham on Unsplash

Responsive and fluid typography with Baseline CSS features

Tue, 16 Dec 2025 08:00:00 GMT

Published: December 16, 2025

Responsive web design is an approach to building websites that look good and function well across a range of different browsers, viewport dimensions, devices, and user preferences. When applied to typography, the central concern is often adjusting font-size based on the browser width—which can also have implications for spacing values like line-height and margin.

As designers, it makes sense to think about what space is available in the browser, and adjust your typography accordingly. It's also important to remember that different users will have different font-size needs across a range of devices, depending on personal circumstances outside your reach or awareness. So it's dangerous to do anything that would take away user control of the final result. There are two primary inputs that people can use to impact font sizing while they browse the web:

Providing a default font-size preference across all websites.
Zooming in or out on a site-by-site basis.

The goal of this demo is to make typography responsive to both the browser's viewport size, and also the user inputs. But it's important to understand that the more your typography responds to the viewport, the less it will respond to user preferences. If you are going to implement responsive typography, it's important to do so carefully, and test that the results are still accessible.

Negotiate a base `font-size` based on user preferences

The first step for defining any typography online is to negotiate an initial font size based on the user's font-size preference. This will be used for the majority of the text on the page, and as a basis for other font sizes like headings. The simplest option here is to give the user full control by using 1em, without any adjustments. When you don't set any other font-size value, 1em refers to the user preference. On the other end of the spectrum, setting a font-size in pixels or other absolute units (and even viewport-relative units) will override the user entirely, which should be avoided.

However, different use cases call for different typography. An article might be easier to read in large text, while data-heavy sites might call for a more compact design with smaller text. In either case, you might want to suggest a default that fits the design, while still allowing the user to adjust the result based on their unique situation.

Option one: calculate a multiplier based on assumptions

One common compromise is to define an adjusted font-size in em or % units, relative to the user default font-size. Generally, this approach starts with the assumption that browsers provide a 16px default, and most users will leave that default in place. If you think a 20px font size will work better for your site, then a font-size of 1.25em or 125% will usually give the result you want:

html {
  /* 20px preferred, 16px expected: 20/16 = 1.25 */
  font-size: 1.25em;
}

You could also use a calc() function here to show the math, but you still have to know what the equation is—the target size, divided by the expected size, multiplied by 1em:

html {
  font-size: calc(20 / 16 * 1em);
}

Users with a larger or smaller preference will have some ability to impact the result, since your default is now relative to theirs—1.25 times their preference in this case. But, it can be strange if both you and the user are both requesting 20px defaults, and the result is 25px—their adjusted default times 1.25 again—a size that no one asked for.

Option two: let `clamp()` do the work

A more nuanced approach involves CSS comparison functions, without any math! Rather than assuming 1em is equal to 16px, and doing unreliable conversions from px to em, you can think of 1em as a variable that refers to the user preference. No matter what pixel value 1em represents, a font-size of max(1em, 20px) will always return the larger of your design preference (20px) and the user's preference (1em). This allows the user to choose larger, but not smaller font sizes.

By switching to a clamp() function, you can allow the user to scale both directions, when their preferred size gets too far from your chosen default. For example, a font-size of clamp(1em, 20px, 1.25em) will default to 20px as long as that is larger than the user default, but not more than 125% of their default.

This allows your design to take priority when it is close to the user preference, but the user still has priority when their preference is outside the specified range. There's no conversion math involved, no assumptions about the user preference size, and no multiplication of designer and user values.

By setting this as the root font-size on the html element, you can now reference 1rem anywhere on the site, as the negotiated base size.

Add responsiveness

To make this font-size responsive to the viewport, one option would be to add media query (or container query) breakpoints. For example, you could change the clamped value depending on the screen size:

html {
  font-size: clamp(1em, var(--base-font-size, 16px), 1.25em);
  @media (width > 30em) { --base-font-size: 18px; }
  @media (width > 45em) { --base-font-size: 20px; }
}

The other option is adding viewport or container units to the static base value:

html {
  font-size: clamp(1em, 16px + 0.25vw, 1.25em);
}

The vw (viewport width) or vi (viewport inline size) units represent 1% of the total viewport—the part of the browser that renders your site. Similarly, the cqw and cqi units represent 1% of an inline-size container on the page. Check out the container queries and units demo for more details.

This approach is often referred to as fluid typography, since the change in font-size is constant over a range of viewport widths, rather than jumping from one value to another at media or container breakpoints. However, don't get distracted by the smoothness of the transition—that distinction is generally only visible in testing, if you smoothly adjust the window size. That effect is rarely (if ever) seen by users. While users may regularly change the size of the browser—or the zoom level—they would have to make those adjustments in a slow and fluid manner to notice the difference between a breakpoint and a viewport unit. It only impacts the transition, not the result after resizing.

The main advantage of fluid font sizing is that it removes any need to calculate or specify breakpoints manually, providing an interpolated result at any given size. You only set the starting point (16px) and the rate of change (0.25vw will provide a 0.25px increase in font-size for every 100px increase in the viewport), and possibly min and max values. When the viewport is 1000px wide, the font-size will be 16px + 2.5px or 18.5px—but that calculation is handled entirely by the browser. This is the approach used in the demo, using cqi units to show container-based responsiveness. When used on the root (html) element, where there is no defined container, cqi units still refer to the viewport size.

If you prefer to think in terms of the specified font-size at a given viewport size, consider using the more direct media query approach, which is a bit more clear. Things get complicated when you try to calculate viewport units based on intended breakpoints. Many people do this by copy and pasting values from third-party tools, but the resulting code is much more difficult to understand or change directly. In general with CSS, the best option is the one that most clearly expresses your intentions.

Warning: Viewport changes don't always mean the same thing!

While media queries and vi units are applied in different ways, both approaches are based on the same measurement of the viewport. If the viewport is 600px wide, then 100vw will be equal to 600px, and styles inside the (width > 500px) media query will be applied.

But what does it mean for the viewport to be 600px wide? In reality, a pixel is not one fixed size with a single meaning in all situations. While it feels natural that a viewport with fewer pixels across is on a smaller screen (like a phone), or in a narrow browser window, that's not a reliable assumption. In fact, zooming in and making the browser window smaller will both have the same impact on the measured viewport width. One action (zooming) changes the size of a pixel, while the other (resizing) changes the size of the browser itself—but both change the number of pixels across the width of the browser. What we get from the viewport measurement is a relationship between the current pixel size and the current browser window.

For the user, zooming and resizing each serve a very different purpose. A user that changes the zoom level is trying to make the contents of the page larger or smaller, but a user that resizes the browser is only managing the space across different screens. Even though the user intent is different, the result on CSS measurements is the same. As the window gets smaller, or the pixel gets larger, there are fewer pixels across the browser's width.

That disconnect makes responsive typography unreliable. If your text is set to resize based only on a viewport or container, then the user zoom will have no effect!

Changing the value of the viewport-relative unit to 1vw or 100vw will change the exact relationship between the font size and viewport. A 1vw font will grow 1px for every 100px of viewport size, while a 100vw font will be exactly the same size as the viewport. You can change that value to make the font grow more slowly or more quickly in relation to the browser. But any viewport-relative value will remain constant as the user zooms in or out—entirely unresponsive to user controls.

Similarly, neither 1vw nor 100vw accounts for the user default font-size.

Using viewport or container-relative units on their own for font-size is always hostile to the user. When a font-size is fully responsive to its container, it cannot also be responsive to user defaults or adjustments. Even with the best intentions and safeguards, taking that final font-size control away from users should be avoided. It's not only a bad user experience, but can also break accessibility guidance that is often required by law. Specifically, section 1.4.4 of the Web Content Accessibility Guidelines requires that "text can be resized without assistive technology up to 200 percent."

How to ensure `font-size` values are responsive to zoom

To ensure that a viewport-relative font-size is responsive to zoom, the viewport-relative value has to be applied as an adjustment to some other value. That's possible in CSS using the calc() function or any other math function that accepts calculations—such as min(), max(), and clamp(). A font-size of calc(16px + 1vw) is based on both the viewport size, and also the current (zoom-relative) size of a pixel. While the vw unit won't be impacted by zoom, the base value will be.

The result is a font-size that responds to both the viewport size and the user's zoom settings. If the user zooms to 200%, the base value will render twice as large (32px), while the responsive value remains unchanged. A 1000px viewport would initially give you a font-size of 16px + 10px = 26px, but at 200% zoom, the font size would only grow to 42px, just over 160%. That may not seem like an extreme issue, but the more your font-size is based on the viewport, the less effective zoom becomes.

On small screens, the font-size will come primarily from the base pixel value, and will respond well to zoom. But on larger screens, the viewport-sizing becomes a larger fraction of the rendered font size, making zoom less effective. This becomes particularly dangerous at the point where 500% zoom (the max in most browsers) can no longer provide the 200% increase in font-size required by WCAG 1.4.4—but even before that point, it can be frustrating to have zoom become ineffective.

The horizontal axis represents viewport size, from 0 to 2600px wide. The vertical axis for font-size is also in pixels, showing the result of calc(17px + 2.5vw). The 500% zoom line uses the same viewport-width horizontal axis, but treats the vertical axis as a percentage.

At the left edge of the graph (0 viewport width), 500% zoom is fully effective. However, that effectiveness drops away quickly as the browser size increases, and (unzoomable) viewport units become a larger factor in the font-size. When the browser is 2040px wide, the maximum 500% zoom is only able to achieve a 200% increase in font-size. Beyond that point, 200% effective font-zoom is no longer possible.

By moving this calculation into a clamp() function, with min and max values, you can enforce boundaries that ensure zoomable text. According to Maxwell Barvian:

If the maximum font size is less than or equal to 2.5 times the minimum font size, then the text will always pass WCAG SC 1.4.4, at least on all modern browsers.

Since @media and @container queries are based on the same measurements as vw and cqw units, the same logic applies when using a breakpoint to change the font size. When the size increase is too dramatic, zoom becomes ineffective. You can experiment with how these values interact in the following visualization:

How to ensure `font-size` values are responsive to user defaults

But calc(16px + 1vw) is still not responsive to user default font settings. To achieve that, you can set a base—or min and max values—using em or rem units rather than px. Putting it all together, you get a familiar result that matches the linked demo:

html {
  font-size: clamp(1em, 17px + 0.24vw, 1.125em);
}

Note that:

The minimum and maximum both use em units, which are based on the user preference (and responsive to zoom).
The additional vw value is kept minimal, so that zoom isn't too heavily impacted.
The maximum size (1.125em) is well under 2.5 times the minimum (1em), ensuring that an effective font-size value of 200% is always possible.

Typographic scales with `pow()`

Most designs use more than one font size! A typographic scale describes the relationship between multiple font sizes. This can be expressed as a base size and a series of multipliers to calculate the other sizes. CSS provides a built-in typographic scale relative to the medium keyword, which refers to the user's font size preference, or a default of 16px. The full keyword scale is:

xx-small: 3/5 (0.6)
x-small: 3/4 (0.75)
small: 8/9 (0.89)
medium: 1 (the base size that others are multiplied against)
large: 6/5 (1.2)
x-large: 3/2 (1.5)
xx-large: 2/1 (2)
xxx-large: 3/1 (3)

This scale is relative to the user default rather than the root font-size, so it doesn't work as well once you change the root font-size of your site. Most authors end up re-creating a similar type scale with custom properties—sometimes using the same t-shirt size names, and sometimes preferring a series of steps up and down a mathematical scale. There are many third-party tools for generating these scales based on common ratios, mostly borrowed from a western musical scale:

html {
  /* musical ratios */
  --minor-second: calc(16/15);
  --major-second: calc(9/8);
  --minor-third: calc(6/5);
  --major-third: calc(5/4);
  --perfect-fourth: calc(4/3);
  --augmented-fourth: sqrt(2);
  --perfect-fifth: calc(3/2);
  --major-sixth: calc(5/3);

  /* the golden ratio*/
  --golden-ratio: calc((1 + sqrt(5)) / 2);
}

But you don't need outside tools to create your own scale in CSS—the new pow() function can generate your scale for you—with 1rem as your own base size!

html {
  /* choose a ratio */
  --scale: 1.2;

  /* generate the scale using pow() */
  --xx-small: calc(1rem * pow(var(--scale), -0.5));
  --x-small: calc(1rem * pow(var(--scale), -0.25));
  --small: calc(1rem * pow(var(--scale), -0.125));
  --medium: 1rem;
  --large: calc(1rem * pow(var(--scale), 1));
  --x-large: calc(1rem * pow(var(--scale), 2));
  --xx-large: calc(1rem * pow(var(--scale), 3));
  --xxx-large: calc(1rem * pow(var(--scale), 4));

  /* change the ratio for different viewport sizes */
  @media (width > 50em) {
    --scale: var(--perfect-fourth);
  }
}

You don't have to use whole steps to keep the scale consistent. In fact, the common 12pt typography scale uses roughly 5 fractions per step. While the large sizes here use whole steps in the scale, the small sizes use fractions to scale at a slower rate.

CSS mixins and functions make it possible to condense that logic even more, while other built-in tools like progress() make it easier to create scales that fluidly adjust from one value to another. But those features are out of scope for this demo.

Respond to the size of in-page containers

You can make all these calculations work in container queries by using the cqi unit in place of vw or vi, but it also helps to leave the user's font-size in place on the html element, so that every type-setting container can refer back to that user preference as 1rem. In the demo, you'll find that the entire type scale is applied to the body rather than the root html element for global type, and then reset based on the container size for every element with the type-set attribute.

This is always a trade-off with container-relative font sizes. You achieve more fluid font sizing for each element in context, but at the expense of a page-wide consistency. Which one is more important to you will depend on the specifics of your use case. And remember that fluid typography itself is a trade-off, making user controls like zoom less effective!

While responsive typography and typographic scales are great tools for designers, there's no need to make things more complicated, if you don't need to. The user default and built-in type scale are a great option as well! But if you do choose responsive (or fluid) typography, make sure to test how the results behave in relation to different user defaults and zoom settings. Enjoy!

Ten modern layouts in one line of CSS

Mon, 15 Dec 2025 08:00:00 GMT

This post highlights a few powerful lines of CSS that do some serious heavy lifting and help you build robust modern layouts.

Published: July 7, 2020, Last updated: December 15, 2025

Modern CSS layouts enable developers to write really meaningful and robust styling rules with just a few keystrokes. The talk above and this subsequent post examine 10 powerful lines of CSS that do some serious heavy lifting.

To follow along or play with these demos on your own, check out the site embed above, or visit 1linelayouts.com.

01. Super Centered: `place-items: center`

For the first 'single-line' layout, let's solve the biggest mystery in all of the CSS land: centering things. I want you to know that it's easier than you think with place-items: center.

First specify grid as the display method, and then write place-items: center on the same element. place-items is a shorthand to set both align-items and justify-items at once. By setting it to center, both align-items and justify-items are set to center.

.parent {
  display: grid;
  place-items: center;
}

This enables the content to be perfectly centered within the parent, regardless of intrinsic size.

02. The Deconstructed Pancake: `flex: <grow> <shrink> <baseWidth>`

Next we have the deconstructed pancake! This is a common layout for marketing sites, for example, which may have a row of 3 items, usually with an image, title, and then some text, describing some features of a product. On mobile, we'll want those to stack nicely, and expand as we increase the screen size.

By using Flexbox for this effect, you won't need media queries to adjust the placement of these elements when the screen resizes.

The flex shorthand stands for: flex: <flex-grow> <flex-shrink> <flex-basis>.

Because of this, if you want your boxes to fill out to their <flex-basis> size, shrink on smaller sizes, but not stretch to fill any additional space, write: flex: 0 1 <flex-basis>. In this case, your <flex-basis> is 150px so it looks like:

.parent {
  display: flex;
}

.child {
  flex: 0 1 150px;
}

If you do want the boxes to stretch and fill the space as they wrap to the next line, set the <flex-grow> to 1, so it would look like:

.parent {
  display: flex;
}

.child {
  flex: 1 1 150px;
}

Now, as you increase or decrease the screen size, these flex items both shrink and grow.

03. Sidebar Says: `grid-template-columns: minmax(<min>, <max>) …)`

This demo takes advantage of the minmax function for grid layouts. What we're doing here is setting the minimum sidebar size to be 150px, but on larger screens, letting that stretch out to 25%. The sidebar will always take up 25% of its parent's horizontal space until that 25% becomes smaller than 150px.

Add this as a value of grid-template-columns with the following value: minmax(150px, 25%) 1fr. The item in the first column (the sidebar in this case) gets a minmax of 150px at 25%, and the second item (the main section here) takes up the rest of the space as a single 1fr track.

.parent {
  display: grid;
  grid-template-columns: minmax(150px, 25%) 1fr;
}

04. Pancake Stack: `grid-template-rows: auto 1fr auto`

Unlike the Deconstructed Pancake, this example does not wrap its children when the screen size changes. Commonly referred to as a sticky footer, this layout is often used for both websites and apps, across mobile applications (the footer is commonly a toolbar), and websites (single page applications often use this global layout).

Adding display: grid to the component will give you a single column grid, however the main area will only be as tall as the content with the footer below it.

To make the footer stick to the bottom, add:

.parent {
  display: grid;
  grid-template-rows: auto 1fr auto;
}

This sets the header and footer content to automatically take the size of its children, and applies the remaining space (1fr) to the main area, while the auto sized row will take the size of the minimum content of its children, so as that content increases in size, the row itself will grow to adjust.

05. Classic Holy Grail Layout: `grid-template: auto 1fr auto / auto 1fr auto`

For this classic holy grail layout, there is a header, footer, left sidebar, right sidebar, and main content. It's similar to the previous layout, but now with sidebars!

To write this entire grid using a single line of code, use the grid-template property. This enables you to set both the rows and columns at the same time.

The property and value pair is: grid-template: auto 1fr auto / auto 1fr auto. The slash in between the first and second space-separated lists is the break between rows and columns.

.parent {
  display: grid;
  grid-template: auto 1fr auto / auto 1fr auto;
}

As in the last example, where the header and footer had auto-sized content, here the left and right sidebar are automatically sized based on their children's intrinsic size. However, this time it is horizontal size (width) instead of vertical (height).

06. 12-Span Grid: `grid-template-columns: repeat(12, 1fr)`

Next we have another classic: the 12-span grid. You can quickly write grids in CSS with the repeat() function. Using: repeat(12, 1fr); for the grid template columns gives you 12 columns each of 1fr.

.parent {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
}

.child-span-12 {
  grid-column: 1 / 13;
}

Now you have a 12 column track grid, we can place our children on the grid. One way to do this would be to place them using grid lines. For example, grid-column: 1 / 13 would span all the way from the first line to the last (13th) and span 12 columns. grid-column: 1 / 5; would span the first four.

Another way to write this is by using the span keyword. With span, you set the starting line and then how many columns to span into from that starting point. In this case, grid-column: 1 / span 12 would be equivalent to grid-column: 1 / 13, and grid-column: 2 / span 6 would be equivalent to grid-column: 2 / 8.

.child-span-12 {
  grid-column: 1 / span 12;
}

07. RAM (Repeat, Auto, MinMax): `grid-template-columns(auto-fit, minmax(<base>, 1fr))`

For this seventh example, combine some of the concepts you've already learned about to create a responsive layout with automatically-placed and flexible children. Pretty neat. The key terms to remember here are repeat, auto-(fit|fill), and minmax()', which you remember by the acronym RAM.

All together, it looks like:

.parent {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
}

You are using repeat again, but this time, using the auto-fit keyword instead of an explicit numeric value. This enables auto-placement of these child elements. These children also have a base minimum value of 150px with a maximum value 1fr, meaning on smaller screens, they will take up the full 1fr width, and as they reach 150px wide each, they will start to flow onto the same line.

With auto-fit, the boxes will stretch as their horizontal size exceeds 150px to fill the entire remaining space. However, if you change this to auto-fill, they will not stretch when their base size in the minmax function is exceeded:

.parent {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
}

08. Line Up: `justify-content: space-between`

For the next layout, the main point to demonstrate here is justify-content: space-between, which places the first and last child elements at the edges of their bounding box, with the remaining space evenly distributed between the elements. For these cards, they are placed in a Flexbox display mode, with the direction being set to column using flex-direction: column.

This places the title, description, and image block in a vertical column inside of the parent card. Then, applying justify-content: space-between anchors the first (title) and last (image block) elements to the edges of the flexbox, and the descriptive text in between those gets placed with equal spacing to each endpoint.

.parent {
  display: flex;
  flex-direction: column;
  justify-content: space-between;
}

09. Clamping My Style: `clamp(<min>, <actual>, <max>)`

Here's where we get into some techniques that have really exciting implications for layouts and responsive UI design. In this demo, you are setting the width using clamp like so: width: clamp(<min>, <actual>, <max>).

This sets an absolute min and max size, and an actual size. With values, that can look like:

.parent {
  width: clamp(23ch, 60%, 46ch);
}

The minimum size here is 23ch or 23 character units, and the maximum size is 46ch, 46 characters. Character width units are based on the font size of the element (specifically the width of the 0 glyph). The 'actual' size is 50%, which represents 50% of this element's parent width.

What the clamp() function is doing here is enabling this element to retain a 50% width until 50% is either greater than 46ch (on wider viewports), or smaller than 23ch (on smaller viewports). You can see that as I stretch and shrink the parent size, the width of this card increases to its clamped maximum point and decreases to its clamped minimum. It then stays centered in the parent since we've applied additional properties to center it. This enables more legible layouts, as the text won't be too wide (above 46ch) or too squished and narrow (less than 23ch).

This is also a great way to implement responsive typography. For example, you could write: font-size: clamp(1.5rem, 20vw, 3rem). In this case, the font-size of a headline would always stay clamped between 1.5rem and 3rem but would grow and shrink based on the 20vw actual value to fit the width of of the viewport.

This is a great technique to ensure legibility with a minimum and maximum size value.

10. Respect for Aspect: `aspect-ratio: <width> / <height>`

And finally, this last layout solves a frequently met problem of maintaining the aspect ratio of an image.

With the aspect-ratio property, as I resize the card, the green visual block maintains this 16 x 9 aspect ratio. We are Respecting the Aspect Ratio with aspect-ratio: 16 / 9.

.video {
  aspect-ratio: 16 / 9;
}

To maintain a 16 x 9 aspect ratio without this property, you'd need to use a padding-top hack and give it a padding of 56.25% to set a top-to-width ratio. We will soon have a property for this to avoid the hack and the need to calculate the percentage. You can make a square with 1 / 1 ratio, a 2 to 1 ratio with 2 / 1, and really just anything you need for this image to scale with a set size ratio.

.square {
  aspect-ratio: 1 / 1;
}

This feature is a good one to know about as it resolves a lot of developer strife that I have faced many times myself, especially when it comes to video and iframes.

Conclusion

Thank you for following this journey through 10 powerful lines of CSS. To learn more, watch the full video, and try out the demos yourself.

Color themes with Baseline CSS features

Thu, 11 Dec 2025 08:00:00 GMT

Published: December 11, 2025

So, you have a site that you want to build or redesign. Maybe you have a few core colors in mind, and you're thinking about how to quickly implement a theme based on those colors.

You'll need your primary color, but also colors for actions, hover states, errors, and colors for other user interface needs. Then what about light and dark mode options? Suddenly there's lots of colors you'll need, and it can feel overwhelming.

The good news is that when it comes to building a palette relative to the color tokens that define your site and switching between color modes, Baseline features can do a lot of the heavy lifting for you. You can explore some of these techniques in the featured demo, a color themed playlist on the fictional Baseline Radio site.

Build a base with relative colors

If you have an idea for a primary color for your theme, with some basic color theory and the CSS relative color syntax, you can quickly start generating a palette of colors to use in your theme.

Say your base color is a shade of teal, which you can first define in your preferred color format. Then you can use any color function to create new colors relative to your base color:

html {
  --base-color: oklch(43.7% 0.075 224);
}

The --base-color custom property is made using the oklch() color function. OkLCh is the cylindrical form of the Oklab color space, and defines values for three channels: L (lightness), C (chroma), H (hue), plus an optional alpha channel to control transparency.

OkLCh is a good format for this type of color manipulation, as it's designed to provide perceptual uniformity. For example, if you adjust just the hue of a color, the resulting color should have a similar perceived lightness and chroma to the original color. This is especially useful in avoiding unexpected contrast issues.

Keeping the same lightness and chroma from your --base-color, you could adjust the hue by 120 degrees in both directions for a triadic palette.

html {
  /* ... */
  --triadic-color-primary: oklch(from var(--base-color) l c calc(h + 120));
  --triadic-color-secondary: oklch(from var(--base-color) l c calc(h - 120));
}

As shown here, the relative color syntax uses a color function that references an origin color (--base-color in this example) with the from keyword, and adjusts the color space's respective channels based on the chosen output color, which in this case will also be OkLCh.

The resulting output gives you a dark pink for the --accent-color, and a shade of gold to use for the --highlight-color, both with the same lightness and chroma as the original --base-color.

html {
  /* ... */
  --accent-color: var(--triadic-color-primary);
  --highlight-color: var(--triadic-color-secondary);
}

  html {
    /* Input color in the rgb color space*/
    --base-color: teal;

     /* Output color in oklch. Computes to oklch(0.543123 0.0927099 314.769) */
     --triadic-color-primary: oklch(from var(--base-color) l c calc(h + 120));
  }

A complementary color would add 180 degrees to the hue angle.

html {
  /* ... */
  --complement-color: oklch(from var(--base-color) l c calc(h + 180));
  --border-highlight: var(--complement-color);
}

For a hover state in your UI, you might want to output a lighter version of a particular color. This would mean increasing the value of the lightness channel. For an active state, you might want to add transparency by adjusting the alpha channel, or darkening it by decreasing the value of the lightness channel.

html {
  /* Darken the --base-color by 15% */
  --base-color-darkened: oklch(from var(--base-color) calc(l * 0.85) c h);
  /* Assign this color a meaningful variable name */
  --action-color: var(--base-color-darkened);
  /* Lighten the --action-color by 15% */
  --action-color-light: oklch(from var(--action-color) calc(l * 1.15) c h);
  /* Darken the --action-color by 10% */
  --action-color-dark: oklch(from var(--action-color) calc(l * 0.9) c h);
}

Here, we are deriving the --action-color from the --base-color, and using it for buttons and links. The --action-color has two variants—lighter and darker—that would still apply even if the --action-color was changed to be relative to another color different from the --base-color.

You can adjust channels by using a math function like calc() or replacing the channel entirely with a new value. Unchanged channels are represented by their respective letters (for example, l for an unchanged lightness value).

Mix colors with `color-mix()`

For other color variants, you could take a similar approach and adjust other channels of the --base-color custom property. Or use color-mix() to add hints of the base color to other aspects of your design.

The --border-color is a mix of the base color and the named color grey, interpolated in the oklab color space. When used as a color interpolation method, this provides perceptually uniform results.

html {
  --base-mix-grey-50: color-mix(in oklab, var(--base-color), grey);
  --border-color: var(--base-mix-grey-50);
}

By default, this would be 50% of each color, but you can make either color more or less prominent by adjusting its percentage weight.

html {
  --background-mix-base-80: color-mix(in oklab,
    var(--background-color) 80%,
    var(--base-color));
  --surface-light: var(--background-mix-base-80);
}

An alternative to adding more color to an element would be to adjust its chroma channel using the relative color syntax. The border of the text inputs in the contact form have a slightly more colorful border when in focus.

[data-input*="text"] {
  --focus-ring: transparent;
  /* ... */
  &:focus {
    --focus-ring: oklch(from var(--border-color) l calc(c + 0.1) h);
  }
}

Opt in to light and dark modes

Once you have a set of colors to work with, you'll want an efficient way to apply different colors for light and dark modes.

Signal support for light and dark themes with the `color-scheme` property

You can instantly tell the browser that your site can be viewed in "light", "dark", or both modes with the color-scheme property. This property tells the browser in which color schemes an element can be comfortably rendered.

 html {
   color-scheme: light dark;
}

Setting color-scheme: light dark on the :root pseudo-element or the html element:

Tells the browser that your page supports being viewed in light or dark mode.
Changes the default colors of the browser user interface to match the respective operating system setting.

To give user agents earlier notice that your page supports light and dark modes, you can also signal support for color scheme switching by adding a <meta> element in the <head> of the document.

<head>
  <!-- ... -->
   <meta name="color-scheme" content="light dark">
</head>

Set "light" and "dark" variants with the `light-dark()` function

As an author, you might be used to setting a page's colors with a prefers-color-scheme @media query.

@media (prefers-color-scheme: light) {
  html {
    --background-color: oklch(95.5% 0 162);
    --text-color: black;
  }
}

@media (prefers-color-scheme: dark) {
  html {
    --background-color: oklch(22.635% 0.01351 291.83);
    --text-color: white;
  }
}

This works great for colors and styles controlled by the author, but as mentioned in the previous section, you would still need color-scheme to update the colors of the browser UI.

Changing the page's colors with a prefers-color-scheme query also means some code duplication since you have to define colors for each mode separately.

With color-scheme set on the overall page (or specific elements) though, you can use the light-dark() function to set colors for each mode in one line of code.

The function accepts two colors. The first is used when the color scheme is set to "light", and the second for when the color scheme is set to "dark".

html {
  color-scheme: light dark;
  /* Color custom property values for both light and dark modes */
  --base-color: light-dark(oklch(43.7% 0.075 224), oklch(89.2% 0.069 224));
  --background-color: light-dark(oklch(95.5% 0 162), oklch(22.635% 0.01351 291.83));
  --accent-color: oklch(from var(--base-color) l c calc(h + 120));
  --active-color: light-dark(var(--action-color-light), var(--action-color-dark));
  /* ... */
}

As with any custom property, the light-dark() settings for your colors can be set globally or within specific components and then used elsewhere as needed.

/* custom property usage */
body {
  background-color: var(--background-color);
  /* ... */
}

:any-link {
  /* ... */
  text-decoration-color: var(--accent-color);
}

Give users control with built-in theme switcher

It's great to have a theme that adapts to a user's default system or browser color preferences, but you can take it a step further and give viewers of your site the ability to override these default color preferences.

If you build a theme toggle which updates the data-scheme attribute on the <html> element you can use the same attribute to change the color-scheme with CSS.

html {
  color-scheme: light dark;

  &[data-scheme="light"] {
    color-scheme: light;
  }

  &[data-scheme="dark"] {
    color-scheme: dark;
  }

  &[data-scheme="green"] {
      --base-color-light: oklch(48.052% 0.11875 151.945);
      --base-color-dark: oklch(92.124% 0.13356 151.558);
      color-scheme: light dark;
   }
}

data-scheme="light" and data-scheme="dark" show the page only in their respective color modes. data-scheme="green" can be viewed in either mode and also changes the --base-color to a shade of green, which gives you an entirely new palette since most other colors are based on the --base-color.

Register custom properties with `@property`

So far, colors in the demo have been set as standard custom properties. You can also register properties with the @property rule to tap into the benefits that come with type checking.

Since the --base-color is used as the base of so many of the other colors in the interface, it could be good to make sure it's always a color and has a fallback value.

@property --base-color-light {
  syntax: '<color>';
  inherits: false;
  initial-value: oklch(43.7% 0.075 224);
}

@property --base-color-dark {
  syntax: '<color>';
  inherits: false;
  initial-value: oklch(89.2% 0.069 224);
}

html {
  --base-color: light-dark(var(--base-color-light), var(--base-color-dark));
}

This way, if the --base-color is inadvertently changed to an invalid value, it would always fallback to its initial-value set with the @property rule.

Registering certain properties this way also allows for smoothly animating colors in a linear-gradient().

.main-heading {
  background: linear-gradient(in oklch 90deg, var(--text-color) 50%, oklch(from var(--base-color) l c var(--header-hue)));
  background-clip: text;
  color: transparent;
  animation: header-hue-switch 5s ease-in-out infinite alternate;
}

.main-heading has a linear-gradient() background that's shown through the transparent text with the background-clip property.

A portion of the text shows a hue that, using the relative color syntax, animates from a channel value of 26.67 to 277:

@keyframes header-hue-switch {
  from {
    --header-hue: 26.67;
  }

  to {
    --header-hue: 277;
  }
}

With a registered --header-hue custom property, this animation is able to happen smoothly since the browser knows that this custom property is a number.

@property --header-hue {
  syntax: '<number>';
  inherits: false;
  initial-value: 100;
}

With an unregistered custom property, the browser wouldn't know the data type of --header-hue, so the transition to a number would be a discrete animation, which would jump between states without gradual interpolation.

Wrap up

New Baseline tools can help you quickly build an adjustable color palette and make creating color variables a more efficient process. You'll still have to agonize over the endless color options and combinations yourself, though.

Creating your palette dynamically like this gives you flexibility. If you need to change the base color for branding, you can just update the --base-color, and the rest of the theme will flow from that. Or, if you add music playback capabilities, you could decide that you want to dynamically change the base color to match the currently playing song.

Credits

Theme switcher logic adapted from Adam Argyle's Theme switch component.

Optimize Time to First Byte

Fri, 28 Nov 2025 08:00:00 GMT

Learn how to optimize for the Time to First Byte metric.

Published: January 19, 2023, Last updated: November 28, 2025

Time to First Byte (TTFB) is a foundational web performance metric that precedes every other meaningful user experience metric such as First Contentful Paint (FCP) and Largest Contentful Paint (LCP). This means that high TTFB values add time to the metrics that follow it.

It's recommended that your server responds to navigation requests quickly enough so that the 75th percentile of users experience an FCP within the "good" threshold. As a rough guide, most sites should strive to have a TTFB of 0.8 seconds or less.

Good TTFB values are 0.8 seconds or less, poor values are greater than 1.8 seconds

Key point: TTFB is not a Core Web Vitals metric, so it's not absolutely necessary that sites meet the "good" TTFB threshold, provided that it doesn't impede their ability to score well on the metrics that matter.

Websites vary in how they deliver content. A low TTFB is crucial for getting markup out to the client as soon as possible. However, if a website delivers the initial markup quickly, but that markup then requires JavaScript to populate it with meaningful content—as is the the case with Single Page Applications (SPAs)—then achieving the lowest possible TTFB is especially important so that the client-rendering of markup can occur sooner.

Conversely, a server-rendered site that requires less client-side work could have a higher TTFB, but better FCP and LCP values than an entirely client-rendered experience. This is why the TTFB thresholds are a rough guide and should be weighed against how your site delivers its core content.

How to Measure TTFB

Before you can optimize TTFB, you need to observe how it affects your website's users. You should rely on field data as a primary source of observing TTFB as it affected by redirects, whereas lab-based tools are often measured using the final URL therefore missing this extra delay.

PageSpeed Insights is one way to get both field and lab information for public websites that are available in the Chrome User Experience Report.

TTFB for real users is shown in the top Discover what your real users are experiencing section:

PageSpeed Insights real user data.

For lab data, TTFB issues are shown in the Document request latency insight:

PageSpeed Insights Document request latency insight.

To find out more ways how to measure TTFB in both the field and the lab, consult the TTFB metric page.

Understand differences between field and lab TTFB

Lab and field TTFB can differ for a number of reasons and when they do differ, it's important to understand why to be able to effectively use the lab data to improve your user experiences.

When lab TTFB is much larger than field TTFB this indicates that the lab environment is more constrained that the typical user experiences. This isn't necessarily a problem, as the lab results and recommendations are still be valid, but may exaggerate the impact and the improvement.
When field TTFB is much larger than lab TTFB this indicates issues that aren't apparent in the lab run, such as use of server-side caching, redirects, or network differences. In this case, the lab results and recommendations may be less useful, as they miss one of the main issues.

To see if server-side caching is impacting lab TTFB, try testing less common pages or using different URL parameters to get uncached content to see if the TTFB is more inline with field TTFB. It can also be useful to you have the ability to bypass server-side caching with a particular URL parameter. See the cached content section.

For redirects and network differences, analytics of how traffic is coming to our site, and where it's coming from, can be useful to diagnose if those are potential issues.

Debug high TTFB in the field with `Server-Timing`

The Server-Timing response header can be used in your application backend to measure distinct backend processes that could contribute to high latency. The header value's structure is flexible, accepting, at minimum, a handle that you define. Optional values include a duration value (via dur), as well as an optional human-readable description (via desc).

Note: If measuring backend latency with Server-Timing is not feasible, then a suitable alternative may be to rely on Application Performance Monitoring (APM) to detect and diagnose backend performance problems.

Serving-Timing can be used to measure many application backend processes, but there are some that you may want to pay special attention to:

Database queries
Server-side rendering time, if applicable
Disk seeks
Edge server cache hits or misses (if using a CDN)

All parts of a Server-Timing entry are colon-separated, and multiple entries can be separated by a comma:

// Two metrics with descriptions and values
Server-Timing: db;desc="Database";dur=121.3, ssr;desc="Server-side Rendering";dur=212.2

The header can be set using your application backend's language of choice. In PHP, for example, you could set the header like so:

<?php
// Get a high-resolution timestamp before
// the database query is performed:
$dbReadStartTime = hrtime(true);

// Perform a database query and get results...
// ...

// Get a high-resolution timestamp after
// the database query is performed:
$dbReadEndTime = hrtime(true);

// Get the total time, converting nanoseconds to
// milliseconds (or whatever granularity you need):
$dbReadTotalTime = ($dbReadEndTime - $dbReadStartTime) / 1e+6;

// Set the Server-Timing header:
header('Server-Timing: db;desc="Database";dur=' . $dbReadTotalTime);
?>

When this header is set, it surfaces information you can use in both the lab, and in the field.

In the field, any page with a Server-Timing response header set populates the serverTiming property in the Navigation Timing API:

// Get the serverTiming entry for the first navigation request:
performance.getEntries('navigation')[0].serverTiming.forEach(entry => {
  // Log the server timing data:
  console.log(entry.name, entry.description, entry.duration);
});

In the lab, data from the Server-Timing response header is visualized in the Timings panel of the Network tab in Chrome DevTools:

Server-Timing header values in the Network tab of Chrome DevTools.

Here, Server-Timing is used to measure whether a request for a resource has hit the CDN cache, and how long it takes for the request to hit the CDN's edge server and then the origin.

Server timings are also surfaced in the Network track of the Performance panel in Chrome DevTools:

Server-Timing header values in the Network track of the Performance panel of Chrome DevTools.

Once you've determined that you have a problematic TTFB by analyzing the data available, then you can move onto fixing the problem.

Ways to optimize TTFB

The most challenging aspect of optimizing TTFB is that, while the web's frontend stack is always be HTML, CSS, and JavaScript, backend stacks can vary significantly. There are numerous backend stacks and database products that each have their own optimization techniques. Therefore, this guide focuses on what applies to most architectures, rather than focusing solely on stack-specific guidance.

Platform-specific guidance

The platform you use for your website can heavily impact TTFB. For example, WordPress performance is impacted by the number and quality of plugins, or what themes are used. Other platforms are similarly impacted when the platform is customized. You should consult the documentation for your platform for vendor-specific advice to supplement the more general performance advice in this post. The Lighthouse insight also includes some limited stack-specific guidance.

Hosting, hosting, hosting

Before you even consider other optimization approaches, hosting should be the first thing you consider. There's not much in the way of specific guidance that can be offered here, but a general rule of thumb is to ensure that your website's host is capable of handling the traffic you send to it.

Shared hosting is generally be slower. If you're running a small personal website that serves mostly static files, this is probably fine. Use some of the optimization techniques that follow to help you reduce your TTFB as much as possible.

However, if you're running a larger application with many users that involves personalization, database querying, and other intensive server-side operations, your choice of hosting becomes critical to lower TTFB in the field.

When choosing a hosting provider, these are some things to look out for:

How much memory is your application instance allocated? If your application has insufficient memory, it will thrash and struggle to serve pages up as fast as possible.
Does your hosting provider keep your backend stack up to date? As new versions of application backend languages, HTTP implementations, and database software are released, performance in that software improves over time. It's key to partner with a hosting provider that prioritizes this kind of crucial maintenance.
If you have very specific application requirements and want the lowest level access to server configuration files, ask if it makes sense to customize your own application instance's backend.

There are many hosting providers that take care of these things for you, but if you start to observe long TTFB values even in dedicated hosting providers, it may be a sign that you might need to re-evaluate your current hosting provider's capabilities so that you can deliver the best possible user experience.

Use a Content Delivery Network (CDN)

The topic CDN usage is a well-worn one, but for good reason: you could have a very well-optimized application backend, but users located far from your origin server may still experience high TTFB in the field.

CDNs solve the problem of user proximity from your origin server by using a distributed network of servers that cache resources on servers that are physically closer to your users. These servers are called edge servers.

CDN providers may also offer benefits beyond edge servers:

CDN providers usually offer extremely fast DNS resolution times.
A CDN likely serves your content from edge servers using modern protocols such as HTTP/2 or HTTP/3.
HTTP/3 in particular solves the head-of-line blocking problem present in TCP (which HTTP/2 relies on) by using the UDP protocol.
A CDN likely provides modern versions of TLS, which lowers the latency involved in TLS negotiation time. TLS 1.3 in particular is designed to keep TLS negotiation as short as possible.
Some CDN providers provide a feature often called an "edge worker", which uses an API similar to that of the Service Worker API to intercept requests, programmatically manage responses in edge caches, or rewrite responses altogether.
CDN providers are very good at optimizing for compression. Compression is tricky to get right on your own, and may lead to slower response times in certain cases with dynamically generated markup, which must be compressed on the fly.
Also, CDN providers automatically cache compressed responses for static resources, leading to the best mix of compression ratio and response time.

While adopting a CDN involves a varying amount of effort from trivial to significant, it should be a high priority to pursue in optimizing your TTFB if your website is not already using one.

Use cached content where possible

CDNs allow content to be cached at edge servers which are located physically closer to visitors, provided the content is configured with the appropriate Cache-Control HTTP headers. While this is not appropriate for personalized content, requiring a trip all the way back to the origin can negate much of the value of a CDN.

For sites that frequently update their content, even a short caching time can result in noticeable performance gains for busy sites, since only the first visitor during that time experiences the fully latency back to the origin server, while all other visitors can reuse the cached resource from the edge server. Some CDNs allow cache invalidation on site releases allowing the best of both worlds—long cache times, but instant updates when needed.

Even where caching is correctly configured, this can be ignored through the use of unique query string parameters for analytics measurement. These may look like different content to the CDN despite being the same, and so the cached version won't be used.

Older or less visited content may also not be cached, which can result in higher TTFB values on some pages than others. Increasing caching times can reduce the impact of this, but be aware that with increased caching times comes a greater possibility of serving potentially stale content.

The impact of cached content does not just affect those using CDNs. Server infrastructure may need to generate content from costly database lookups when cached content cannot be reused. More frequently accessed data or precached pages can often perform better.

Avoid multiple page redirects

One common contributor to a high TTFB is redirects. Redirects occur when a navigation request for a document receives a response that informs the browser that the resource exists at another location. One redirect can certainly add unwanted latency to a navigation request, but it can certainly get worse if that redirect points to another resource that results in another redirect—and so on. This can particularly impact sites that receive high volumes of visitors from advertisements or newsletters, since they often redirect through analytics services for measurement purposes. Eliminating redirects under your direct control can help to achieve a good TTFB.

There are two types of redirects:

Same-origin redirects, where the redirect occurs entirely on your website.
Cross-origin redirects, where the redirect occurs initially on another origin—such as from a social media URL shortening service, for example—before arriving at your website.

Focus on eliminating same-origin redirects, as this is something you have direct control over. This would involve checking links on your website to see if any of them result in a 302 or 301 response code. Often this can be the result of not including the https:// scheme (so browsers default to http:// which then redirects) or because trailing slashes are not appropriately included or excluded in the URL.

Cross-origin redirects are trickier as these are often outside of your control, but try to avoid multiple redirects where possible—for example, by using multiple link shorteners when sharing links. Ensure the URL provided to advertisers or newsletters is the correct final URL, so as not to add another redirect to the ones used by those services.

Another important source of redirect time can come from HTTP-to-HTTPS redirects. One way you can get around this is to use the Strict-Transport-Security header (HSTS), which enforces HTTPS on the first visit to an origin, and then tells the browser to immediately access the origin through the HTTPS scheme on future visits.

Once you have a good HSTS policy in place, you can speed things up on the first visit to an origin by adding your site to the HSTS preload list.

Stream markup to the browser

Browsers are optimized to process markup efficiently when it's streamed, meaning that markup is handled in chunks as it arrives from the server. This is crucial where large markup payloads are concerned, as it means the browser can parse that the chunks of markup incrementally, as opposed to waiting for the entire response to arrive before parsing can begin.

Though browsers are great at handling streaming markup, it's crucial to do all that you can to keep that stream flowing so those initial bits of markup are on their way as soon as possible. If the backend is holding things up, that's a problem. Because backend stacks are numerous, it would be beyond the scope of this guide to cover every single stack and the issues that could arise in each specific one.

React, for example—and other frameworks that can render markup on demand on the server—have used a synchronous approach to server-side rendering. However, newer versions of React have implemented server methods for streaming markup as it's being rendered. This means you don't have to wait for a React server API method to render the entire response before it's sent.

Another way to ensure markup is streamed to the browser quickly is to rely on static rendering which generates HTML files during build time. With the full file available immediately, web servers can start sending the file immediately and the inherent nature of HTTP results in streaming markup. While this approach isn't suitable for every page on every website—such as those requiring a dynamic response as part of the user experience—it can be beneficial for those pages that don't require markup to be personalized to a specific user.

Use a service worker

The Service Worker API can have a big impact on the TTFB for both documents and the resources they load. The reason for this is that a service worker acts as a proxy between the browser and the server—but whether there is an impact on your website's TTFB depends on how you set up your service worker, and if that setup aligns with your application requirements.

Use a stale-while-revalidate strategy for assets. If an asset is in the service worker cache, be it a document or a resource the document requires, the stale-while-revalidate strategy services that resource from the cache first, then downloads that asset in the background and serves it from the cache for future interactions.
- If you have document resources that don't change very often, using a stale-while-revalidate strategy can make a page's TTFB nearly instant. However, this doesn't work so well if your website sends dynamically generated markup—such as markup that changes based on whether a user is authenticated. In such cases, you'll always want to hit the network first, so the document is as fresh as possible.
- If your document loads non-critical resources that change with some frequency, but fetching the stale resource won't greatly affect the user experience—such as select images or other resources that aren't critical—the TTFB for those resources can be greatly reduced using a stale-while-revalidate strategy.
Use the app shell model for client-rendered applications. This model fits best for SPAs where the "shell" of the page can be delivered instantly from the service worker cache, and the dynamic content of the page is populated and rendered later on in the page lifecycle.

Use `103 Early Hints` for render-critical resources

No matter how well your application backend is optimized, there could still be a significant amount of work the server needs to do in order to prepare a response, including expensive (yet necessary) database work that delays the navigation response from arriving as quickly as it could. The potential effect of this is that some subsequent render-critical resources could be delayed, such as CSS or—in some cases—JavaScript that renders markup on the client.

The 103 Early Hints header is an early response code that the server can send to the browser while the backend is busy preparing markup. This header can be used to hint to the browser that there are render-critical resources the page should begin downloading while the markup is being prepared. For supporting browsers, the effect can be faster document rendering (CSS) and quicker page loading.

Note: If your website doesn't do a lot of processing on the backend to prepare markup—for example, static sites—then 103 Early Hints probably won't help much. It tends to work best for sites that involve considerable backend time before markup can be sent to the user.

One downside to 103 Early Hints is that, like caching, they can mask the "real" TTFB of a site. If a server infrastructure is slow (either because it's underpowered or the code needs optimizing), then that can be less obvious when 103 Early Hints is used as the TTFB looks fast. Sites using 103 Early Hints should consider measuring the actual server time (though Server-Timing or finalResponseHeadersStart of the PerformanceNavigationTiming API).

Conclusion

Since there are so many combinations of backend application stacks, there's no one article that can encapsulate everything you can do to lower your website's TTFB. However, these are some options you can explore to try and get things going just a little bit faster on the server side of things.

As with optimizing every metric, the approach is largely similar: measure your TTFB in the field, use lab tools to drill down into the causes, and then apply optimizations where possible. While some techniques may not be viable for your situation, some likely are. As always, you'll need to keep a close eye on your field data, and make adjustments as needed to ensure the fastest possible user experience.

Time to First Byte (TTFB)

Fri, 28 Nov 2025 08:00:00 GMT

Published: October 26, 2021, Last updated: November 18, 2025

What is TTFB?

TTFB is a metric that measures the time between starting navigating to a page and when the first byte of a response begins to arrive.

A diagram of network request phases and their associated timings. TTFB measures the elapsed time between startTime and responseStart.

TTFB is the sum of the following request phases:

Redirect time
Service worker startup time (if applicable)
DNS lookup
Connection and TLS negotiation
Request, up until the point at which the first byte of the response has arrived

Reducing latency in connection setup time and on the backend can lower your TTFB.

TTFB and Early Hints

The introduction of 103 Early Hints causes some confusion as to what "first byte" TTFB measures. The 103 Early Hints counts as the "first bytes". The finalResponseHeadersStart is an additional timing entry to responseStart that measures the the start of the final document response (typically an HTTP 200 response) to be measured.

Note: Based on feedback from the community, Chrome updated the responseStart (and so the TTFB) to the start of the final document response (that was later standardized as finalResponseHeadersStart) from Chrome 115. However, this created a compatibility issue across many tools and so was reverted in Chrome 133.

Early Hints is just a newer example of responding early. Some servers allow early flushing of the document response to happen before the main body is available—either with just the HTTP headers, or with the <head> element, both of which could be considered similar in effect to Early Hints. This is another reason why all these are measured as responseStart and so TTFB.

There is real value in sending back data early if the full response is going to take some more time. However, this does make it difficult to compare TTFB across different platforms or technologies depending on what features they use, and how that impacts the TTFB measurement being used. What is most important is to understand what the measure the tool you are using measures and how that is affected by the platform being measured.

What is a good TTFB score?

Because TTFB precedes user-centric metrics such as First Contentful Paint (FCP) and Largest Contentful Paint (LCP), it's recommended that your server responds to navigation requests quickly enough so that the 75th percentile of users experience an FCP within the "good" threshold. As a rough guide, most sites should strive to have a TTFB of 0.8 seconds or less.

Good TTFB values are 0.8 seconds or less, and poor values are greater than 1.8 seconds.

Key point: Because TTFB isn't a Core Web Vitals metric, it's not absolutely necessary that sites meet the "good" TTFB threshold, provided that it doesn't impede their ability to score well on the metrics that matter.

Conversely, a server-rendered site that does not require as much client-side work could have a higher TTFB, but better FCP and LCP values than an entirely client-rendered experience. This is why the TTFB thresholds are a "rough guide", and will need to be weighed against how your site delivers its core content.

How to measure TTFB

TTFB can be measured in the lab or in the field in the following ways.

Field tools

Lab tools

In the network panel of Chrome's DevTools
WebPageTest

Measure TTFB in JavaScript

You can measure the TTFB of navigation requests in the browser with the Navigation Timing API. The following example shows how to create a PerformanceObserver that listens for a navigation entry and logs it to the console:

new PerformanceObserver((entryList) => {
  const [pageNav] = entryList.getEntriesByType('navigation');

  console.log(`TTFB: ${pageNav.responseStart}`);
}).observe({
  type: 'navigation',
  buffered: true
});

The web-vitals JavaScript library can also measure TTFB in the browser more succinctly:

import {onTTFB} from 'web-vitals';

// Measure and log TTFB as soon as it's available.
onTTFB(console.log);

Measure resource requests

TTFB can also be measured on all requests, not just navigation requests. In particular, resources hosted on cross-origin servers can introduce latency due to the need to set up connections to those servers.

To measure TTFB for resources in the field, use the Resource Timing API within a PerformanceObserver:

new PerformanceObserver((entryList) => {
  const entries = entryList.getEntries();

  for (const entry of entries) {
    // Some resources may have a responseStart value of 0, due
    // to the resource being cached, or a cross-origin resource
    // being served without a Timing-Allow-Origin header set.
    if (entry.responseStart > 0) {
      console.log(`TTFB: ${entry.responseStart}`, entry.name);
    }
  }
}).observe({
  type: 'resource',
  buffered: true
});

The previous code snippet is similar to the one used to measure the TTFB for a navigation request, except instead of querying for 'navigation' entries, you query for 'resource' entries instead. It also accounts for the fact that some resources loaded from the primary origin may return a value of 0, since the connection is already open, or a resource is instantaneously retrieved from a cache.

How to improve TTFB

For guidance on improving your site's TTFB, see our in-depth guide to optimizing TTFB.

and popover: Baseline layered UI patterns

Tue, 25 Nov 2025 08:00:00 GMT

Published: November 25, 2025

Elements and windows that pop up on the screen are one of the most common patterns on the web. With use cases spanning from alerts and brief forms requesting data, to the now ubiquitous cookie settings prompt, these layered UI patterns are used frequently by developers.

Most of these user interface elements are added to web applications using either custom JavaScript or common libraries. With that route there's a lot to make sure that you or the library you choose gets right.

The <dialog> element and the popover attribute are two Baseline layered UI patterns that developers can reach for instead of custom implementations. To show the advantages of using layered UI patterns built into today's web browsers—and to give an example of when you might reach for <dialog> or use the popover attribute—this article walks through an example of a modal that appears when the user attempts to save an image to a favorites list without being logged in.

A modal `<dialog>`

The <dialog> element is a box that appears over other content that a user can interact with to complete a task or input information. They can be modal or non-modal. The main difference is that when a modal <dialog> is open, interaction with the rest of the content underneath is disabled.

Each image in the gallery demo has a "favorite" button that can be pressed to save the image to what would be a favorites list. Since the user is not logged in, a pop up prompts them to sign up with an email address in order to complete the action.

The modal in this example is a <dialog> element inserted right after the image gallery.

<dialog aria-labelledby="dialog-title" aria-describedby="description">
  <h2 id="dialog-title">Yay! You found a favorite!</h2>
  <p id="description">Sign up with your email address to start adding to your favorites list.</p>
</dialog>

Use the `showModal()` method to open a modal `<dialog>`

The <dialog> element is hidden by default. To display it as a modal, you can use the showModal() method.

const openDialogBtns = document.querySelectorAll(`[data-button*="show-dialog"]`);
const dialog = document.querySelector('dialog');

openDialogBtns.forEach(openDialogBtn => {
  openDialogBtn.addEventListener('click', () => {
    dialog.showModal();
  });
});

In addition to opening the <dialog> as a modal, using the showModal() method:

Adds the dialog to the top layer.
Attaches a ::backdrop pseudo-element directly underneath it.
Implicitly adds the aria-modal="true" attribute.
Automatically makes all of the elements on the page underneath the dialog inert.

In a custom implementation, all of the behavior included with dialog.showModal or command="show-modal" are all details you would have to account for yourself. In addition to these characteristics of a modal, the WAI ARIA Authoring Practices Guide lists further requirements and guidelines for the ideal user experience once a modal dialog is open:

Focus moves to an element inside of the dialog.
Tabbing and keyboard focus should stay within the dialog until it is closed.
Since users shouldn't be able to interact with the content underneath the modal, that content should be slightly dimmed or obscured.
Once a modal is closed, focus should return to the element that opened it.

That's a lot to remember, test, and get right.

However, with the HTML <dialog> element, its built-in showModal() method, and the ::backdrop CSS pseudo-selector, you get all of the web features just described that are now Baseline.

How to close the dialog

Modal dialogs can be closed by pressing <kbd>Esc</kbd>, or you can add a <button> element to explicitly close the them with the built-in HTMLDialogElement.close() method.

// Code omitted...
const dialog = document.querySelector('dialog');
const closeDialogBtn = document.getElementById('close');
// Code omitted...

closeDialogBtn.addEventListener('click', () => {
  dialog.close();
});

You can also declaratively close a dialog by adding a <form> element separate from any user inputs in the dialog, and adding method="dialog". This sets the submission behavior for all submit events in that form to close the dialog. Adding markup that closes the dialog declaratively may feel familiar to you if you've used component libraries with a <DialogClose> component.

<dialog aria-labelledby="dialog-title" aria-describedby="description">
  <form method="dialog">
    <button data-button="close" type="submit">Close</button>
  </form>
</dialog>

`popover`, rising to the top

The popover attribute is another way to add layered UI patterns to your applications. Unlike the <dialog> element, any element can be turned into a popover. The two are similar but have some key differences:

Popovers don't make the rest of the page inert, while a modal dialog does.
Default popovers (popover="auto") can be "light-dismissed", while modal dialogs opened with dialog.showModal can only be light-dismissed if the dialog has the closedBy="any" attribute .
Popovers have no inherent semantics, while a dialog has an implicit ARIA role of "dialog".
Popover is styled with the :popover-open pseudo class, while a dialog is styled with the open attribute

One behavior that a <dialog> and an element with the popover attribute shares is that when they are open their content is automatically promoted to the top layer. As the name implies, elements in the top layer are rendered outside of the document flow, on top of all other content. Even if content in the normal document flow has a sky-high z-index, it will always appear underneath content in the top layer.

What happens when you open an element that gets promoted to the top layer from inside of another element that's already open in the top layer? The last element opened inside of the top layer is highest in the top layer stack, so the popover in the demo opens on top of the dialog without you having to configure a z-index position for it.

<form method="dialog">
  <label for="email">Enter your email</label>
  <button id="popover-trigger" type="button" popovertarget="privacy-popover">
    <span class="visually-hidden">How we handle your email</span>
  </button>
  <p id="privacy-popover" popover>As with all of your information, we promise not to sell your email address</p>
</form>

The button that will open the popover is placed next to the label for the email address input, and is made into a control for opening our popover by adding the popovers id to the value of its popovertarget attribute. By giving the popover the attribute of popover and assigning it an id that matches the popovertarget attribute on the popover control, the popover can now be toggled.

Autofocus

The <dialog> traps focus inside of itself and when opened, and places focus on the first focusable element inside of it. Use the autofocus attribute if it makes more sense to apply focus on a different element instead. In the demo, the <input> element for the email address has an autofocus attribute, so that users can start entering their email address as soon as the dialog is open.

Style the `::backdrop`

As mentioned earlier, a <dialog> opened by the showModal() method is displayed in the top layer, and makes all content underneath it inert. You can style the attached ::backdrop pseudo-element to further emphasize the <dialog>, and adjust the visibility of content underneath.

The ::backdrop has a faint linear-gradient and a blur effect when the dialog is open. The backdrop-filter property lets you apply graphic effects to the area behind an element.

To achieve the animation effect on the color stops in the linear-gradient, you first must register the custom properties with the @property rule. Registering the custom property in this way—as opposed to using a standard custom property—lets the browser know what data type to expect, allowing for smooth transitions and animations. You can then define @keyframes, or use a transition to specify when and how the color stops change.

@property --backdrop-gradient-start {
  syntax: "<color>";
  initial-value: oklch(33.894% 0.08072 246.33);
  inherits: true;
}

@property --backdrop-gradient-end {
  syntax: "<color>";
  initial-value: oklch(45.859% 0.00345 174.48 / 0.3);
  inherits: true;
}

/* ... */

dialog[open]::backdrop {
  opacity: 1;
  background: linear-gradient(140deg,
      var(--backdrop-gradient-start),
      var(--backdrop-gradient-end));
  backdrop-filter: blur(2px);
  animation: show-gradient var(--transition-timing-slower) forwards;
}

@keyframes show-gradient {
    from {
    --backdrop-gradient-start: oklch(45.859% 0.00345 174.48 / 0.3);
    --backdrop-gradient-end: oklch(33.894% 0.08072 246.33 / 0.3);
    }

    to {
      --backdrop-gradient-start: oklch(33.894% 0.08072 246.33);
      --backdrop-gradient-end: oklch(45.859% 0.00345 174.48 / 0.3);
    }
}

You can use a different technique to animate the dialog and popover and you'll see how that works in the next section.

Make an entrance (and exit) with `@starting-style`

The <dialog> element and popover both go from being display: none to display: block by default. Due to how CSS transitions typically handle this flip of the display property, elements having their display set to any visible display property from display: none enter and exit the page immediately. Thankfully, with a combination of Baseline features @starting-style and transition-behavior you can use transitions to make their entrances and exits more seamless.

In the next step, you'll animate the dialog. The demo transitions the dialog's opacity, translate, overlay, and display properties. You can achieve this by setting values for the dialog's three states.

The open state describes how the dialog should look once it is open:

dialog[open] {
  --opacity: 1;
  --translate: 0 0;
}

The state in between, the transitioning state, is made by adding a @starting-style block. These are the styles the browser will use when the dialog is first rendered in the DOM, as it transitions from display: none to display: block. Without the @starting-style block, the transition would fail, since the element wouldn't have a previous state from which to transition.

/* Open state */
dialog[open] {
  --opacity: 1;
  --translate: 0 0;

  /* Transitioning state */
  @starting-style {
    --opacity: 0;
    --translate: 100vw -10rem;
  }
}

The last state to include to successfully transition elements like dialog is the closed state. This is the default or exit state that the element will return to as it transitions to display: none.

Here you can include the specific transition settings for each property you are animating. In addition to the opacity, translate, and display properties you must also transition the overlay property for animations to work.

/* Closed state */
dialog {
  opacity: var(--opacity, 0);
  translate: var(--translate, 100vw -10rem);
  transition:
    opacity 1s ease-in,
    translate 0.6s ease-in-out
    overlay 0.6s ease-in-out,
    display 0.6s linear;
  transition-behavior: allow-discrete;
}

The final step is to specify the transition-behavior for the overlay and display properties that normally have discrete animation behavior.

Conclusion

Reaching for the web platform's tools can make it easier to implement layered UI patterns accessibly, and can keep you from worrying about handling all of the expected functionality yourself. This gives you more time to focus on enhancing the user experience with platform features, and less time debugging custom or library implementations.

How to implement an image gallery using Baseline features

Wed, 29 Oct 2025 07:00:00 GMT

Published: October 29, 2025

From image sharing sites to online stores, image galleries are a common pattern on the web. Images can be very data heavy, and loading images can make the page take a long time to load. In addition, users have high expectations around the usability of galleries, so it's common to add additional libraries that further increase page size.

The web platform has added support for many of the underlying pieces of an image gallery. So, what does it look like to code an image gallery with Baseline features? This demo showcases a variety of techniques that you can use to do just that.

How to deal with large image sizes

Images can be some of the largest assets you ask your users to download, and image galleries by their nature often have many images. This demo uses a couple of Baseline features to help reduce the performance impact on users.

Lazy loading

Loading all of the images when the page loads can make the other content slower to load overall. It's a useful pattern to defer loading of images that aren't on the screen until they are on the screen.

But it's a balance—you don't want users to have to wait for images to load as they scroll. You want them to already be loaded when they scroll into view.

JavaScript libraries have made this possible in the past, and you could also roll your own with an IntersectionObserver. However, both options mean shipping more code, and leave more room for bugs.

Browsers have made this possible with an HTML-based progressive enhancement: By adding loading="lazy" to <img> elements, the browser will defer loading those images until they are needed.

If you have a sense of how many images will be seen on screens when the page is first loaded, you can set loading="eager" on the first few images, to make sure that those are loaded immediately. Because loading="eager" is the default, you can also just omit the attribute for those images.

If you view the Network panel in your browser's developer tools as you load the demo, only the first six will load immediately. Depending on your screen size and how many are visible, several others may be loaded. As you scroll, the browser will load the remaining images.

Lazy loading images works with more than just scrolling. If an image is initially hidden—for example, in a dialog—the image won't load until the dialog is opened. This would be useful in an image gallery if you are loading a larger image size when the user clicks on an image.

When you add lazy loading to your images, make sure that you are providing dimensions for the image. This prevents a layout shift if the image doesn't get loaded in time. In this demo, the inline size is determined by the grid definition, and the aspect-ratio CSS property on the image gallery grid items is set to 1 / 1, so the block size matches that. You can also set dimension attributes directly.

AVIF

While you want to show your users high resolution images, you likely don't want to show them the full resolution image, especially in the gallery of thumbnails. You'll want to either compress and resize your images before uploading to your server, or configure your server to resize images for you.

The AVIF file format is a relatively new format that can be an alternative to legacy formats such as JPEG and PNG, and is worth investigating for potential loading performance benefits.

Along with supporting animated images and transparency, AVIF can have lower file sizes than other image formats. The images in this demo were converted to AVIF from JPG, and are much smaller while retaining suitable image quality. AVIF also supports HDR images.

Online tools like Squoosh and Cloudinary are useful for one-off conversions to AVIF if you're looking to experiment with the format. Design tools such as Photoshop (version 26+) and GIMP also export to AVIF. You can also incorporate AVIF encoding in your image processing pipelines using ImageMagick.

Lightbox effect

In an image gallery, users have the expectation that they can click an image to view a larger version. In the past, this often required z-index hacks, but now you can use the <dialog> element, which is Baseline Widely available. Built with accessibility in mind, the <dialog> element handles focus management more effectively, and requires less custom JavaScript.

A dialog places your content in a new top layer, on top of everything else. To create the lightbox effect, you can use the ::backdrop pseudo element. This is a styleable box below the dialog, but above the rest of the page. This all works without you needing to worry about the z-index of anything.

Transition the lightbox

By default, a dialog appears and disappears with no transition effects. Adding some slight transitions can make the experience feel more smooth, and help the user mentally transition. The demo uses allow-discrete transition behavior and @starting-style for the dialog to define the transition for the dialog.

Style the button

Backdrop filter

A common design pattern for image galleries is to place text on top of the image. This comes with the risk that the image won't provide sufficient contrast with the text, making the text difficult or impossible to read. One way of handling that is to add a semi-transparent background behind the text, but this doesn't always provide the needed effect. The backdrop-filter CSS property gives you more control over the effect.

With backdrop-filter, you can combine color effects and blurs that apply to the content behind the <dialog> element. You can also use pseudo classes to update the filter when the button is hovered or focused.

button {
  --btn-filter: blur(1em);
  backdrop-filter: var(--btn-filter);
  
  &:hover,
  &:focus {
    --btn-filter: blur(0.75em) saturate(350%);
  }
}

Resolution media query

The demo also uses a resolution media query to add a bit of extra polish. The button's top border is 1px, which will serve as a default size, but you can choose to display a subpixel border on higher resolution screens.

 @media (min-resolution: 2x) {
    --border-size: 0.5px;
  }

Aspect ratio

For the images to be displayed in a consistent size, you can set an aspect ratio. This works best when paired with object-fit to instruct the image how best to fill the space.

[data-img] {
  aspect-ratio: 1 / 1;
  object-fit: cover;
}

The gallery example uses an aspect ratio of 1 / 1 meaning the width and height will be equal. The width comes from grid-template-columns which has a minimum size of 16em, but can grow until there is enough room to add another column. The height then matches the width.

With an object-fit value of cover, this will ensure each image fills its container in both dimensions maintaining its intrinsic aspect ratio, and will be cropped if it's overflowing.

As you saw in the section on lazy loading images, this demo also uses aspect-ratio to make sure an image doesn't change dimensions when it loads, preventing a layout shift.

Take it further

There are other Baseline features that you may want to incorporate into your image gallery. If you add navigation to the previous and next images from within the dialog, you may want to animate the change with view transitions. If you have the ability to generate multiple sizes of the images, you can use the <picture> element to serve different resolutions of images on different screen sizes.

Baseline web features are making it possible to make a performant and usable image gallery with less code, and without relying on additional libraries. The next time you need to build an image gallery, you can use this demo as a pattern, or you can adopt pieces of it to enhance your current tools today.

Container queries and units in action

Thu, 23 Oct 2025 07:00:00 GMT

Published: October 23, 2025

One of the goals when writing CSS is to build component parts that will adapt well to different (and unexpected) contexts. Ideally, a component can be placed inside any "container" element without it feeling broken or out of place. How can you accomplish this in a complex layout like a store where the primary component—the "product"—has to fit into a variety of list layouts, including the sidebar?

Responsive typography with `cqi` units

The first step is to define some basic sizing variables that could be reused across the project—starting with whitespace sizes. But before creating any custom properties, the browser provides some useful named values as CSS units:

1em: the current font size.
1rem: the font size on the :root (html) element.
1lh / 1rlh: the current and root line heights.
1vw: the viewport width.
1vi: the viewport "inline" size (for English, this is the same as vw).
1cqi: the inline size of the nearest "container" (defaulting to the viewport).

You can think of these units as common variables provided by the browser, with a shorthand syntax for multiplication. If you wanted half of a --line-height custom property in CSS, you would need to write the entire calculation calc(0.5 * var(--line-height)), but with the lh unit, you can ask for 0.5lh instead.

Custom properties like --brand-color and --button-background have different meanings and serve a different purpose, even when they result in the same deepPink color (another browser-provided variable). Similarly, 1em might sometimes be equal to 16px, but that's not a stable relationship. Like any other variable, units should be used to express a relationship, rather than an expected value.

Both 1em and 1lh are font-relative units that could be used for spacing, but only one of them has a reliable relationship to the current line height. If this page involved a lot of elements with prose in them—paragraphs and lists, for example—the lh unit would work well for spacing between them:

p, ul, ol {
  margin-block: 1lh;
}

That will maintain a consistent baseline rhythm, without any extra work. But this page has almost no prose. Instead of spacing within a flow of text, this layout requires spacing to push text away from the edge of a card, and spacing between columns and rows in a grid or stacked layout. In this case there are several things to consider:

Multiples (or fractions) of 1lh may still be useful for maintaining vertical rhythm across the page.
The cqi unit would account for the amount of available space in a given context.

By combining these two units in a round() function, the --gap variable is based primarily on the container size, but rounded up to a multiple of quarter-lines:

html {
  --gap: round(up, 2cqi, 0.25lh);
}

If the line-height is 20px, then the --gap will be multiples of 5px—but the exact multiple will depend on available space. If either the line-height or available space change, the --gap variable will adapt to its new context. To make the --gap consistent across the entire design, you could replace the container-relative cqi units with viewport-relative vi units.

The same approach is useful when establishing "fluid" font sizes that respond to available space. This --body-text variable is based on the user-provided font preference, with some range to adapt based on the container. In this case, clamp() ensures the font will be at least as large as the user's preference, can grow some as the container size increases, but will stop growing at some point:

html {
  --body-text: clamp(1rem, 0.875rem + 0.5cqi, 1.25rem);
}

The range is clamped between 1rem and 1.25rem, to stay near the user-selected font size.
The cqi value determines how fast the font will grow or shrink in relation to available space, which is added to a rem value to offset that growth based on the user-selected size.

Keeping the central rem value near 1 and the added cqi value low ensures that users still have significant control when zooming in or out. You can adjust those two values, and then use browser zoom to see how they interact. The closer you get to 100cqi, and the farther you fall below 1rem, the less influence user font preferences will have—and the less font sizes will respond to zooming in or out.

The --item-title variable is slightly larger and more responsive, and the --list-title size responds to the viewport size (using vi) rather than the immediate container size. That way item headings respond to their context, but the main list headings all match in size no matter where they show up.

Defining containers to measure in context

At this point, container query units have been used to create adaptive typography on a web page, but new containers haven't been defined.

By default, 1cqi (1/100 container query inline size) is the same as 1svi (1/100 small viewport inline size) because the "small" viewport acts as the initial container for any web page. In order to take full advantage of the cqi unit, you need to define additional "containers" within the page. The primary layout containers on this page are the product-list and shopping-cart—so they are set to expose their inline-size.

product-list,
shopping-cart {
  container-type: inline-size;
}

Container query units—including cqi—aren't able to measure the element that they are used on. If you set the width of shopping-cart to 25cqi, it would be a paradox to determine the container's width based on its own width! Instead, the result will be based on the next ancestor container in the tree hierarchy that contains shopping-cart.

The product-detail cards are part of a product-list grid that can be changed by the user. The list layout option displays each card at full width. In that case, referring to the parent container size is useful, but both the small-grid and large-grid options cause the card to grow and shrink depending on how many columns fit into the container. Even when the container is quite large, the cards can remain tightly packed into smaller grid cells.

There's currently no way to declare those grid cells as "containers" directly. Instead, an extra element is needed to measure within each cell. That's why each product-detail instance has an <article> element nested directly inside. product-detail > article is the card to be styled, while product-detail itself is used only as a container to measure. That allows the cqi-based text and spacing calculations previously defined to be recalculated for the space available to each card.

Explicit container queries

Container units are powerful, but sometimes it's useful to make more dramatic changes in a component layout when the available size crosses a threshold. These are often called breakpoints—since the fix is applied at the point when a given layout begins to break. You may already be familiar with using @media to add breakpoints based on the viewport size:

main {
  display: grid;
  grid-template:
    'controls' auto
    'cart' 1fr
    'list' auto
    / minmax(min-content, 1fr);

  @media (width > 30em) {
    grid-template:
      'controls controls' auto
      'list cart' 1fr
      / 2fr 1fr
    ;
  }
}

Here, shopping-cart appears above the main product-list on small screens—but at a certain point, there's more horizontal space, and a sidebar makes more sense. Since that shift depends on the overall viewport, a media query is used to handle the change. However, the product-list and product-detail components might appear in different contexts, somewhat independent of the viewport size. When the viewport grows wider than the sidebar breakpoint, the shopping-cart component suddenly becomes smaller, providing less space for products inside. This is where container queries become necessary. The syntax is nearly identical to a media query, but uses @container rather than @media at the start of the rule:

article {
  display: grid;
  grid-template:
    'image' auto 'title' auto
    'summary' auto
    'button' auto / auto
  ;

  @container (inline-size > 40ch) {
    --image-ratio: 1;
    grid-template:
      'image title' auto
      'image summary' 1fr
      'image button' auto
      / minmax(50px, min(20%, 500px)) 1fr
    ;
  }

  @container (inline-size > 50ch) {
    grid-template:
      'image title title' auto
      'image summary button' 1fr
      / minmax(50px, min(20%, 500px)) 1fr fit-content(20%);
  }
}

The initial goal of this post is that components should be able to respond to any context. To make that work, each component defines its own internal behavior, without explicit knowledge of the surrounding components. Container queries help us accomplish that. The product-list and product-detail components don't need to be aware of why they have more or less space in a given context, they only need to know how much space is currently available.

Transition grid templates and visibility

With a layout that's changing often based on container queries, how do we smooth out all of the transitions? When using grids for layout, it's possible to animate the size of a column or row, as well as the gap between columns and rows. In this case, the cart area and gap are expanded from 0 width when the cart is opened. In order to animate grid templates like this, two things are required:

The initial and end states must have the same number of tracks (columns or rows).
The animated tracks must use comparable units.

While it would be possible to change from a one-column grid to a two-column grid when the sidebar is hidden, the empty sidebar column is instead resized to 0, and the column-gap is also set to 0. When the cart is open in the sidebar, the 0-width column transitions to calc(15em + 1cqi). Since the calculation results in a normal length value, the transition can be animated from length 0. The gap also animates from one length to another—from 0 to var(--gap)—which was defined earlier:

main {
  transition: grid-template 250ms, gap 250ms;
}

Non-Baseline animation enhancements

The shopping-cart and product-detail components are also animated when hidden or shown, and this is done using two recent features that are not yet Baseline, but work as progressive enhancements for browsers that do have support:

Applying interpolate-size: allow-keywords allows transitioning element dimensions from 0 to auto. This is used for transitioning the products to and from a block-size of 0 when they are added or removed from the cart. Since the interpolate-size property inherits, that only needs to be defined once on the <html> element, and it is available to every other element on the page. This is only supported in Chrome-based browsers (Chrome, Edge, and others), but can be used as a progressive enhancement. The fallback works as expected, just without the animated transition.
Browser Support
Source
"Discrete" properties like display can now be transitioned as well, even though there are no intermediate values between grid and none. Instead the transition is applied at the start or end of the duration provided. To achieve that, allow-discrete is added to the transition-behavior property. While transition-behavior is otherwise Baseline, animating the display property is not yet supported in Firefox. But again, this works well as a progressive enhancement.
Browser Support

Querying media versus containers

There are many situations where container queries and units can be used to replace media queries and viewport units, and that's great when it helps you express the intent of a design more clearly. But one is not meant to replace the other, and there's not a better query or unit that will work in every situation. CSS works best when the relationships established in code match the goals and purpose of the design. When you want text and spacing that is relative to immediate context, container queries provide that functionality, but when you want consistent sizing relative to the overall viewport, media queries and viewport units are still an excellent option. Most websites will likely involve a mix of both.

content-visibility: the new CSS property that boosts your rendering performance

Tue, 23 Sep 2025 07:00:00 GMT

Improve initial load time by skipping the rendering of offscreen content.

Published: August 5, 2020

The content-visibility property enables the user agent to skip an element's rendering work, including layout and painting, until it is needed. Because rendering is skipped, if a large portion of your content is off-screen, using the content-visibility property makes the initial user load much faster. It also allows for faster interactions with the on-screen content. Pretty neat.

Browser Support

Source

In our article demo, applying content-visibility: auto to chunked content areas gives a 7x rendering performance boost on initial load. Read on to learn more.

CSS Containment

The key and overarching goal of CSS containment is to enable rendering performance improvements of web content by providing predictable isolation of a DOM subtree from the rest of the page.

Basically a developer can tell a browser what parts of the page are encapsulated as a set of content, allowing the browsers to reason about the content without needing to consider state outside of the subtree. Knowing which bits of content (subtrees) contain isolated content means the browser can make optimization decisions for page rendering.

There are four types of CSS containment, each a potential value for the contain CSS property, which can be combined in a space-separated list of values:

size: Size containment on an element ensures that the element's box can be laid out without needing to examine its descendants. This means we can potentially skip layout of the descendants if all we need is the size of the element.
layout: Layout containment means that the descendants do not affect the external layout of other boxes on the page. This allows us to potentially skip layout of the descendants if all we want to do is lay out other boxes.
style: Style containment ensures that properties which can have effects on more than just its descendants don't escape the element (e.g. counters). This allows us to potentially skip style computation for the descendants if all we want is to compute styles on other elements.
paint: Paint containment ensures that the descendants of the containing box don't display outside its bounds. Nothing can visibly overflow the element, and if an element is off-screen or otherwise not visible, its descendants will also not be visible. This allows us to potentially skip painting the descendants if the element is offscreen.

Skip rendering work with `content-visibility`

It may be hard to figure out which containment values to use, since browser optimizations may only kick in when an appropriate set is specified. You can play around with the values to see what works best, or you can use content-visibility to apply the needed containment automatically. content-visibility ensures that you get the largest performance gains the browser can provide with minimal effort from you as a developer.

The content-visibility property accepts several values, but auto is the one that provides immediate performance improvements. An element that has content-visibility: auto gains layout, style and paint containment. If the element is off-screen (and not otherwise relevant to the user—relevant elements would be the ones that have focus or selection in their subtree), it also gains size containment (and it stops painting and hit-testing its contents).

What does this mean? In short, if the element is off-screen its descendants are not rendered. The browser determines the size of the element without considering any of its contents, and it stops there. Most of the rendering, such as styling and layout of the element's subtree are skipped.

As the element approaches the viewport, the browser no longer adds the size containment and starts painting and hit-testing the element's content. This enables the rendering work to be done just in time to be seen by the user.

Caution: The browser is only able to skip rendering work if you are also careful not to call any DOM API that forces some of rendering to occur on one of the skipped subtrees. If you're using content-visibility to improve performance, audit your code to make sure these APIs are not getting called. To help find them, Chromium will print console messages if you call one of these APIs for a subtree of an element with content-visibility:hidden. To see the messages, turn on verbose logging.

A note on accessibility

One of the features of content-visibility: auto is that the off-screen content remains available in the document object model and therefore, the accessibility tree (unlike with visibility: hidden). This means, that content can be searched for on the page, and navigated to, without waiting for it to load or sacrificing rendering performance.

The flip-side of this, however, is that landmark elements with style features such as display: none or visibility: hidden will also appear in the accessibility tree when off-screen, since the browser won't render these styles until they enter the viewport. To prevent these from being visible in the accessibility tree, potentially causing clutter, be sure to also add aria-hidden="true".

Example: a travel blog

In this example, we baseline our travel blog on the right, and apply content-visibility: auto to chunked areas on the left. The results show rendering times going from 232ms to 30ms on initial page load.

A travel blog typically contains a set of stories with a few pictures, and some descriptive text. Here is what happens in a typical browser when it navigates to a travel blog:

A part of the page is downloaded from the network, along with any needed resources.
The browser styles and lays out all of the contents of the page, without considering if the content is visible to the user.
The browser goes back to step 1 until all of the page and resources are downloaded.

In step 2, the browser processes all of the contents looking for things that may have changed. It updates the style and layout of any new elements, along with the elements that may have shifted as a result of new updates. This is rendering work. This takes time.

An example of a travel blog. See Demo on Codepen

Now consider what happens if you put content-visibility: auto on each of the individual stories in the blog. The general loop is the same: the browser downloads and renders chunks of the page. However, the difference is in the amount of work that it does in step 2.

With content-visibility, it will style and layout all of the contents that are currently visible to the user (they are on-screen). However, when processing the story that is fully off-screen, the browser will skip the rendering work and only style and layout the element box itself.

The performance of loading this page would be as if it contained full on-screen stories and empty boxes for each of the off-screen stories. This performs much better, with expected reduction of 50% or more from the rendering cost of loading. In our example, we see a boost from a 232ms rendering time to a 30ms rendering time. That's a 7x performance boost.

What is the work that you need to do in order to reap these benefits? First, we chunk the content into sections:

Example of chunking content into sections with the story class applied, to receive content-visibility: auto. See Demo on Codepen

Then, we apply the following style rule to the sections:

.story {
  content-visibility: auto;
  contain-intrinsic-size: 1000px; /* Explained in the next section. */
}

Specify the natural size of an element with `contain-intrinsic-size`

In order to realize the potential benefits of content-visibility, the browser needs to apply size containment to ensure that the rendering results of contents don't affect the size of the element in any way. This means that the element will lay out as if it was empty. If the element does not have a height specified in a regular block layout, then it will be of 0 height.

This might not be ideal, since the size of the scrollbar will shift, being reliant on each story having a non-zero height.

Thankfully, CSS provides another property, contain-intrinsic-size, which effectively specifies the natural size of the element if the element is affected by size containment. In our example, we are setting it to 1000px as an estimate for the height and width of the sections.

This means it will lay out as if it had a single child of "intrinsic-size" dimensions, ensuring that your unsized divs still occupy space. contain-intrinsic-size acts as a placeholder size in lieu of rendered content.

The auto keyword for contain-intrinsic-size causes the browser will remember the last-rendered size, if any, and use that instead of the developer-provided placeholder size. For example, if you specified contain-intrinsic-size: auto 300px, the element will start out with a 300px intrinsic sizing in each dimension, but once the element's contents are rendered, it will retain the rendered intrinsic size. Any subsequent rendering size changes will also be remembered. In practice, this means that if you scroll an element with content-visibility: auto applied, and then scroll it back offscreen, it will automatically retain its ideal width and height, and not revert to the placeholder sizing. This feature is especially useful for infinite scrollers, which can now automatically improve sizing estimation over time as the user explores the page.

Note: We can use IntersectionObserver and MutationObserver to set the correct sizes inline for each element. Alex Russell explains how this works in content-visibility without jittery scrollbars, and Resize-Resilient content-visibility Fixes.

Hide content with `content-visibility: hidden`

What if you want to keep the content unrendered regardless of whether or not it is on-screen, while leveraging the benefits of cached rendering state? Enter: content-visibility: hidden.

The content-visibility: hidden property gives you all of the same benefits of unrendered content and cached rendering state as content-visibility: auto does off-screen. However, unlike with auto, it does not automatically start to render on-screen.

This gives you more control, allowing you to hide an element's contents and later unhide them quickly.

Compare it to other common ways of hiding element's contents:

display: none: hides the element and destroys its rendering state. This means unhiding the element is as expensive as rendering a new element with the same contents.
visibility: hidden: hides the element and keeps its rendering state. This doesn't truly remove the element from the document, as it (and it's subtree) still takes up geometric space on the page and can still be clicked on. It also updates the rendering state any time it is needed even when hidden.

content-visibility: hidden, on the other hand, hides the element while preserving its rendering state, so, if there are any changes that need to happen, they only happen when the element is shown again (i.e. the content-visibility: hidden property is removed).

Some great use cases for content-visibility: hidden are when implementing advanced virtual scrollers, and measuring layout. They're also great for single-page applications (SPA's). Inactive app views can be left in the DOM with content-visibility: hidden applied to prevent their display but maintain their cached state. This makes the view quick to render when it becomes active again.

Effects on Interaction to Next Paint (INP)

INP is a metric that evaluates a page's ability to be reliably responsive to user input. Responsiveness can be affected by any excessive amount of work that occurs on the main thread, including rendering work.

Whenever you can reduce rendering work on any given page, you're giving the main thread an opportunity to respond to user inputs more quickly. This includes rendering work, and using the content-visiblity CSS property where appropriate can reduce rendering work—especially during startup, when most rendering and layout work is done.

Reducing rendering work has a direct effect on INP. When users attempt to interact with a page that uses the content-visibility property properly to defer layout and rendering of offscreen elements, you're giving the main thread a chance to respond to critical user-visible work. This can improve your page's INP in some situations.

Conclusion

content-visibility and the CSS Containment Spec mean some exciting performance boosts are coming right to your CSS file. For more information on these properties, check out:

Use Baseline with Browserslist

Wed, 17 Sep 2025 07:00:00 GMT

Published: May 7, 2025, Last updated: September 17, 2025

Browserslist is one of the most popular tools for configuring minimum supported browser versions in frontend code bases. Developers add a browserslist query to their package.json file (or other configuration point for Browserslist, such as a .browserslistrc file), and Browserslist exposes a list of minimum supported browsers. Browserslist can be used with a wide range of popular linting, polyfilling and packaging tools, including:

Autoprefixer
Babel using @babel/preset-env
PostCSS using postcss-preset-env
ESLint using eslint-plugin-compat
Stylelint using stylelint-no-unsupported-browser-features
webpack

Baseline targets

When you decide to use Baseline, you should consider your user base and decide which Baseline feature set you want to target:

Baseline Widely available includes all web features that were fully supported by the Baseline core browser set 30 or more months in the past.
Baseline year feature sets, for example Baseline 2020, include all features that were Newly available at the end of the specified year.

Depending on your user base, you may be able to target Baseline Widely available, or you may need to target an older Baseline year. Consult your analytics or RUM tools to understand which browsers versions your users have.

How to target Baseline Newly or Widely available

Support for Baseline is built into Browserslist through a few different queries. If you want to target Baseline Newly available browsers, try specifying baseline newly available in your Browserslist config:

{
  ...
  "browserslist": [
    "baseline newly available"
   ]
  ...
}

You can specify baseline widely available as a query, too:

{
  ...
  "browserslist": [
    "baseline widely available"
   ]
  ...
}

How to target Baseline years

If you want to target a Baseline year feature set, you specify the year in a query, such as baseline 2024 if you want to target the 2024 feature set:

"browserslist": "baseline 2024"

You can specify years from baseline 2015 to the current year.

How to specify downstream browsers

The Baseline core browser set includes Chrome, Edge, Firefox, and Safari. Other browsers are based on the same open source code as Chrome and Edge—Chromium—and should support the same feature set as whichever version of Chromium they implement. To include these browsers in your Baseline configuration, add with downstream after your Baseline query. For example, to target downstream browsers as part of Baseline Widely available, specify baseline widely available with downstream:

"browserslist": "baseline widely available with downstream"

baseline newly available with downstream is another valid query, as is adding with downstream to yearly targets:

"browserslist": "baseline 2024 with downstream"

Examples of Baseline queries in action

In packaging tools

Using the Baseline queries offered by Browserslist in your project can have an immediate effect. Babel is a popular build tool for packaging Javascript. If you use the @babel/preset-env package defaults, many modern Javascript APIs and methods will be replaced with the more verbose syntax required by older browsers:

However, using a query of baseline 2020 to target the 2020 feature set on the same example project dramatically decreases the output size of this Javascript, because fewer syntax transforms are required:

Try this for yourself using the example code in the Google Chrome Labs baseline-demos repository.

In linters

Some linters already work with Browserslist, or can be made to work with Browserslist using a compatibility module. For example, stylelint can consume a browserslist config using the stylelint-browser-compat module. Set your stylelint.config.js file to use the Baseline query of your choice:

module.exports = {
  plugins: ['stylelint-browser-compat'],
  rules: {
    'plugin/browser-compat': [
      true,
      {
        browserslist: ['baseline widely available'],
      },
    ],
  },
};

Stylelint will now flag CSS that isn't currently part of Baseline Widely available:

Stylelint also provides a plugin that lets you set Baseline rules directly, but if you are already using Browserslist to handle your config, using the built-in Baseline queries that Browserslist offers is a viable solution.

Create Baseline tools with the web-features package

Fri, 12 Sep 2025 07:00:00 GMT

Published: September 12, 2025

Emerging tooling for Baseline helps you determine which web features are safe to use in your web applications today. These tools, such as linters and IDE features, use a data source of web platform features that contains data about their support in modern browsers.

The Web Platform Status Dashboard is one data source for these features and provides a queryable HTTP API. Querying this data source on demand is not practical for all tools. For many tooling use cases, the web-features npm package is a more reliable and practical version of web feature data that you use locally. This guide will show you how to use the web-features package to develop your own Baseline tools.

Get started with the `web-features` package

First, install the package as a dependency in your project:

npm install web-features

Once installed, import one or more named exports from the web-features package into your project:

import { features, groups, browsers, snapshots } from 'web-features';

Depending on your goals, you might not need all of these exports. These exports provide the following information:

features: An array of objects, where each object represents a web feature. This is the export you will most frequently use.
browsers: An array of objects describing browsers.
groups: An array of objects that defines a logical grouping of features. These are useful if your goal is to target a subset of web platform features, such as those for CSS, JavaScript, and more specific groupings.
snapshots: Contains the ECMAScript versions of corresponding JavaScript features, such as ES2023, ES2022, and other ECMAScript versions.

The features export provides the following properties for building Baseline tooling:

id: The unique identifier for the feature. For example, the identifier for CSS Grid is "grid". Note: this is not a property within the data object. It's the object key.
compat_features: An array of individual BCD keys included in the feature.
name: The human-readable string of the feature's name, such as "Container Queries".
description: A short description of the feature.
group: The group in which the feature belongs. This corresponds to group data found in the groups export.
baseline: The feature's Baseline status. This can be one of three values:
1. false: The feature's status is Limited availability.
2. "low": The feature is Baseline Newly available.
3. "high": The feature is Baseline Widely available.
4. baseline_high_date: The date the feature became Baseline Widely available. Note: this is not available if the feature is not Baseline Widely available.
5. baseline_low_date: The date the feature became Baseline Newly available. Note: this is not available for Limited availability features.

The following example is the full data object for the CSS subgrid feature:

"subgrid": {
  "caniuse": "css-subgrid",
  "compat_features": [
    "css.properties.grid-template-columns.subgrid",
    "css.properties.grid-template-rows.subgrid"
  ],
  "description": "The subgrid value for the grid-template-columns and grid-template-rows properties allows a grid item to inherit the grid definition of its parent grid container.",
  "description_html": "The <code>subgrid</code> value for the <code>grid-template-columns</code> and <code>grid-template-rows</code> properties allows a grid item to inherit the grid definition of its parent grid container.",
  "group": "grid",
  "name": "Subgrid",
  "spec": "https://drafts.csswg.org/css-grid-2/#subgrids",
  "status": {
    "baseline": "low",
    "baseline_low_date": "2023-09-15",
    "support": {
      "chrome": "117",
      "chrome_android": "117",
      "edge": "117",
      "firefox": "71",
      "firefox_android": "79",
      "safari": "16",
      "safari_ios": "16"
    }
  }
}

The groups export provides data on feature groupings with the following structure:

id: The unique identifier for the group. For example, CSS features have an ID of"css". Note: this is not a property within the groups object. It's the object key itself.
name: The human-readable name of the group.
parent: The ID of the group's parent group. This is not available if the group doesn't have a parent.

Examples

The following examples show how to use the web-features package to get the data you need to build Baseline tooling.

Look up the Baseline status for a specific feature

import { features } from 'web-features';

function getBaselineStatus (featureId) {
  return features[featureId]?.status.baseline;
}

This example represents the most direct use case for the web-features package, where you specify a feature's ID to get its Baseline data available in the status.baseline property. This property tells you if a feature is Limited availability, Newly available, or Widely available. In the latter two cases, you also have access to dates that describe when the feature reached a certain Baseline threshold.

Look up the Baseline status for a specific BCD key

BCD stands for browser-compat-data, a project maintained by MDN to catalog support for features across browsers. A BCD key corresponds to a granular feature, like a specific CSS property value or a behavioral subfeature defined by the spec.

The web-features project groups related BCD keys into the compat_features array for each feature. Sometimes you need the Baseline status of one BCD key, rather than the overall Baseline status for the entire feature. For example, if you build a CSS linter and need to know if a property-value pair is compatible across major browsers, the feature-level data is too coarse. This happens because the package aggregates each feature over all its constituent BCD keys, and some keys have better browser support than others.

To look up the Baseline status of a BCD key, inspect the status.by_compat_key property of the feature object (available in web-features 3.6.0 and later):

import { features } from 'web-features';

function getBaselineStatus (featureId, bcdKey) {
  return features[featureId]?.status.by_compat_key[bcdKey];
}

For example, the output of getBaselineStatus('outline', 'css.properties.outline') is:

{
  "baseline": "low",
  "baseline_low_date": "2023-03-27",
  "support": {
    "chrome": "94",
    "chrome_android": "94",
    "edge": "94",
    "firefox": "88",
    "firefox_android": "88",
    "safari": "16.4",
    "safari_ios": "16.4"
  }
}

Sort features by their Baseline status

This example iterates through every feature in the features object and sorts each one into an array by its Baseline status.

import { features } from "web-features";

const webFeatures = Object.values(features);

const widelyAvailable = webFeatures.filter(feature => {
  return feature.status.baseline === 'high';
});

const newlyAvailable = webFeatures.filter(feature => {
  return feature.status.baseline === 'low';
});

const limitedAvailability = webFeatures.filter(feature => {
  return feature.status.baseline === false;
});

This example illustrates how to work with the status.baseline property in your tooling. For example, you could use this approach in a web application to display a list of all web features by their Baseline status.

Find all features within a group

So far, all the examples shown use the features export, but the groups export organizes all features logically within groups. This means you could, for example, find all features that are part of View Transitions:

import { features, groups } from 'web-features';

const groupKeys = Object.keys(groups);
const featuresData = Object.values(features);

const viewTransitionsGroup = groupKeys.find(groupKey => {
  return groupKey === 'view-transitions';
});

const viewTransitionsFeatures = featuresData.filter(feature => {
  return feature.group === viewTransitionsGroup;
});

The intersection between the features and group exports lets you narrow your search for web features by the group they belong to.

Putting it all together

You can use the lookups to build useful tools, for example to create a CSS linter.

CSS linters evaluate at-rules, pseudo-elements, properties, and property-value pairs. For your Baseline linter, look up the status of each token by its BCD key, not by its parent feature.

A parser like CSSTree tokenizes CSS, breaking a stylesheet into an abstract syntax tree (AST). The following example shows a CSS rule that uses a generic class selector and a style declaration:

.foo {
  word-break: auto-phrase;
}

The AST would look something like this:

{
  "type": "StyleSheet",
  "children": [
    {
      "type": "Rule",
      "prelude": {
        "type": "SelectorList",
        "children": [
          {
            "type": "Selector",
            "children": [
              {
                "type": "ClassSelector",
                "name": "foo"
              }
            ]
          }
        ]
      },
      "block": {
        "type": "Block",
        "children": [
          {
            "type": "Declaration",
            "important": false,
            "property": "word-break",
            "value": {
              "type": "Value",
              "children": [
                {
                  "type": "Identifier",
                  "name": "auto-phrase"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

When you find a property declaration as you walk through the AST, map that property name to its corresponding BCD key to check its Baseline status. BCD categorizes CSS properties under the css.properties object, so the corresponding BCD key is css.properties.word-break.

Then, find the feature associated with that BCD key and look up its status.

// Assuming we only know the BCD key and not the feature ID.
const bcdKey = 'css.properties.word-break';
const [featureId, feature] = Object.entries(features).find(([id, feature]) =>
  feature.compat_features?.includes(bcdKey)
) || [];
const status = feature?.status.by_compat_key[bcdKey];

The Baseline status for the word-break property is as follows:

{
  "baseline": "high",
  "baseline_high_date": "2018-03-30",
  "baseline_low_date": "2015-09-30",
  "support": {
    "chrome": "44",
    "chrome_android": "44",
    "edge": "12",
    "firefox": "15",
    "firefox_android": "15",
    "safari": "9",
    "safari_ios": "9"
  }
}

The "high" Baseline status indicates the property is widely available, so your linter does not need to issue a warning. Next, examine the property's value.

The AST shows that the value of this property is auto-phrase. To get the corresponding BCD key, add the value to the parent property's BCD key: css.properties.word-break.auto-phrase.

Note: This method only works for values that the property's specification names. Generic value types like numbers or color names don't have their own BCD keys. If web-features does not return data for a given BCD key, there is nothing to validate, so ignore it.

In this case, web-features shows that the status of the word-break: auto-phrase property-value pair is not Baseline:

{
  "baseline": false,
  "support": {
    "chrome": "119",
    "chrome_android": "119",
    "edge": "119"
  }
}

Use the information in this linter example to warn the developer that this property-value pair is not Baseline. This warning ensures that the developer knows it won't work as expected across the major browser engines.

Real-world examples

The previous examples show basic uses of the web-features package. There are already a number of tools taking advantage of this data. For example:

eslint-css uses the web-features package in its use-baseline rule to lint for specific features.
The hovercards in Visual Studio Code use the web-features package to show Baseline information for CSS features and HTML features.
MDN uses the web-features data in the banners on most feature pages (for example, abs()) to communicate their Baseline status.

There are more examples out there of how this data source can be used to build Baseline tools—and we hope that your project becomes one of them!

Getting started with measuring Web Vitals

Tue, 09 Sep 2025 07:00:00 GMT

Collecting data on your site's Web Vitals is the first step towards improving them. A well-rounded analysis will collect performance data from both real-world and lab environments. Measuring Web Vitals requires minimal code changes and can be accomplished using free tooling.

Measure Web Vitals using RUM data

Real User Monitoring (RUM) data, also known as field data, captures the performance experienced by a site's actual users. RUM data is what Google uses to determine whether a site meets the recommended Core Web Vitals thresholds.

Getting started

If you don't have a RUM setup, the following tools will quickly provide you with data about the real-world performance of your site. These tools are all based on the same underlying dataset (the Chrome User Experience Report), but have slightly different use cases:

Chrome DevTools integrates with the CrUX dataset in the live metrics view of the Performance panel. By comparing your local experience against real-user experiences on the same page, you can make a more informed decision about where to focus your debugging efforts. If you're looking for a single action to take in order to get started with measuring and improving your site's Web Vitals, we recommend using the Chrome DevTools Performance panel.
PageSpeed Insights (PSI) reports on the aggregate page-level and origin-level performance over the past 28 days. In addition, it provides suggestions on how to improve performance. PSI is available on the web and as an API.
Search Console reports performance data on a per-page basis. This makes it well-suited for identifying specific pages that need improvement. Unlike PageSpeed Insights, Search Console reporting includes historical performance data. Search Console can only be used with sites that you own and have verified ownership of.
CrUX Vis is a prebuilt dashboard that surfaces CrUX history data for a URL or origin of your choosing (where available in the CrUX dataset). It is built on top of the CrUX History API and the setup process takes about a minute. Compared to PageSpeed Insights and Search Console, CrUX Vis includes more data example, LCP subparts, navigation types, and so forth.
CrUX Vis is a historical dashboard that surfaces CrUX data for an origin or URL of your choosing. It is built on top of CrUX History API. Compared to PageSpeed Insights and Search Console, CrUX Vis reporting includes more details—for example, navigation types and LCP and RTT data is available in CrUX Vis.

It's worth noting that although the tools listed previously are well-suited for "getting started" with measuring Web Vitals, they can be useful in other contexts as well. In particular, both CrUX and PSI are available as an API and can be used to build dashboards and other reporting.

Collect RUM data

Although CrUX-based tools are a good starting point for investigating Web Vitals performance, we strongly recommend supplementing it with your own RUM. RUM data that you collect yourself can provide more detailed and immediate feedback on your site's performance. This makes it easier to identify issues and test possible solutions.

You can collect your own RUM data by using a dedicated RUM provider, or, by setting up your own tooling.

Dedicated RUM providers specialize in collecting and reporting RUM data. To use Core Web Vitals with these services, ask your RUM provider about enabling Core Web Vitals monitoring for your site.

If you don't have a RUM provider, you may be able to augment your existing analytics setup to collect and report on these metrics by using the web-vitals JavaScript library. This method is explained in more detail next.

The web-vitals JavaScript library

If you're implementing your own RUM setup for Web Vitals, the easiest way to collect Web Vitals measurements is to use the web-vitals JavaScript library. web-vitals is a small, modular library (~2KB) that provides a convenient API for collecting and reporting each of the field-measurable Web Vitals metrics.

The metrics that make up Web Vitals are not all directly exposed by the browser's built-in performance APIs—but rather built on top of them. For example, Cumulative Layout Shift (CLS) is implemented using the Layout Instability API. By using web-vitals, you don't need to worry about implementing these metrics yourself; it also ensures that the data you collect matches the methodology and best practices for each metric.

For more information on implementing web-vitals, refer to the documentation and the Best practices for measuring Web Vitals in the field guide.

Data aggregation

It is essential that you report the measurements collected by web-vitals. If this data is measured but not reported, you'll never see it. The web-vitals documentation includes examples showing how to send the data to a generic API endpoint, Google Analytics, or Google Tag Manager.

If you already have a favorite reporting tool, consider using that. If not, Google Analytics is free and can be used for this purpose.

When considering which tool to use, it is helpful to think about who will need to have access to the data. Businesses typically achieve the biggest performance wins when the whole company, rather than a single department, is interested in improving performance. See Fixing website speed cross-functionally to learn how to get buy-in from different departments.

Data interpretation

When analyzing performance data, it's important to pay attention to the tails of the distribution. RUM data often reveals that performance varies widely—some users have fast experiences, others have slow experiences. However, using the median to summarize data can mask this behavior.

With regards to Web Vitals, Google uses the percentage of "good" experiences, rather than statistics like medians or averages, to determine whether a site or page meets the recommended thresholds. Specifically, for a site or page to be considered as meeting the Core Web Vitals thresholds, 75% of page visits should meet the "good" threshold for each metric.

Measure Web Vitals using lab data

Lab data, also known as synthetic data, is collected from a controlled environment, rather than actual users. Unlike RUM data, lab data can be collected from pre-production environments and therefore incorporated into developer workflows and continuous integration processes. Examples of tools that collect synthetic data are Lighthouse and WebPageTest.

Considerations

There will always be discrepancies between RUM data and lab data—particularly if the network conditions, device type, or location of the lab environment differs significantly from that of users. However, when it comes to collecting lab data on Web Vitals metrics in particular, there are a couple specific considerations that are important to note:

Largest Contentful Paint (LCP) measured in lab environments can be different to those measured in the field with RUM data due to delays in loading the page (through redirects, latency connecting to the server, or uncached data), different content shown to different users depending on screen, or due to other reasons (including, cookie banners, personalization).
Cumulative Layout Shift (CLS) measured in lab environments can be artificially lower than the CLS observed in RUM data. Many lab tools only load the page—they don't interact with it. As a result, they only capture layout shifts that occur during initial page load. By contrast, the CLS measured by RUM tools captures unexpected layout shifts that occur throughout the entire lifespan of the page.
Interaction to Next Paint (INP) can't be measured in lab environments because it requires user interactions with the page. As a result, Total Blocking Time (TBT) is the recommended lab proxy for INP. TBT measures the "total amount of time between First Contentful Paint and Time to Interactive during which the page is blocked from responding to user input". Although INP and TBT are calculated differently, they are both reflections of a blocked main thread during the bootstrap process. When the main thread is blocked, the browser is delayed in responding to user interactions.

Tooling

These tools can be used to gather lab measurements of Web Vitals:

Chrome DevTools measures and reports the Core Web Vitals for a given page in the live metrics view of the Performance panel. This view provides developers with real-time performance feedback as they make code changes.
Lighthouse Lighthouse reports on LCP, CLS, and TBT, and also highlights possible performance improvements. Lighthouse is available in Chrome DevTools, as an npm package, and can also be incorporated into continuous integration workflows using Lighthouse CI.
WebPageTest includes Web Vitals as a part of its standard reporting. WebPageTest is useful for gathering information on Web Vitals under particular device and network conditions.

Largest Contentful Paint (LCP)

Thu, 04 Sep 2025 07:00:00 GMT

Published: August 8, 2019, Last updated: September 4, 2025

Largest Contentful Paint (LCP) is an important, stable Core Web Vital metric for measuring perceived load speed because it marks the point in the page load timeline when the page's main content has likely loaded—a fast LCP helps reassure the user that the page is useful.

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 don't work well 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 isn't 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 don't identify when the main content of the page has loaded.

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 is rendered.

What is LCP?

LCP reports the render time of the largest image, text block, or video visible in the viewport, relative to when the user first navigated to the page.

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.

A good LCP value is 2.5 seconds or less.

To learn more about the research and methodology behind this recommendation, see: Defining the Core Web Vitals metrics thresholds.

What elements are considered?

As specified in the Largest Contentful Paint API, the types of elements considered for Largest Contentful Paint are:

<img> elements (the first frame presentation time is used for animated content such as GIFs or animated PNGs)
<image> elements inside an <svg> element
<video> elements (the poster image load time or first frame presentation time for videos is used—whichever is earlier)
An element with a background image loaded using the url() function, (as opposed to a CSS gradient)
Block-level elements containing text nodes or other inline-level text element children.

Note that restricting the elements to this limited set was intentional in order to reduce complexity. Additional elements (like the full <svg> support) may be added in the future as more research is conducted.

As well as only considering some elements, LCP measurements use heuristics to exclude certain elements that users are likely to see as "non-contentful". 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 don't 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 LCP 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 don't 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 text elements, LCP considers only the smallest rectangle that can contain all text nodes.

For all elements, LCP doesn't consider margins, paddings, or borders applied using CSS.

When is LCP 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>.

An element can only be considered the largest contentful element after it has rendered and is visible to the user. Images that haven't yet loaded aren't considered "rendered". Neither are text nodes using web fonts during the font block period. In such cases, a smaller element might be reported as the largest contentful element, but as soon as the larger element finishes rendering, another PerformanceEntry is created.

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 the largest contentful element is removed from the viewport, or even from the DOM, it remains the largest contentful element unless a larger element is rendered.

For analysis purposes, you should only report the most recently dispatched PerformanceEntry to your analytics service.

Caution: Since users can open pages in a background tab, it's possible that largest-contentful-paint entries won't be dispatched until the user focuses the tab, which can be much later than when they first loaded it. Google tools that measure LCP don't report this metric if the page was loaded in the background, as it does not reflect the user-perceived load time.

Load time versus render time

For security reasons, the render timestamp of images was not originally exposed for cross-origin images that lack the Timing-Allow-Origin header. Instead, only their load time was exposed (since this is already exposed through many other web APIs).

The load time will usually be slightly after the resource download ends (responseEnd in Resource Timing) as it takes time for the browser to process the resource after the download completes, even before it starts to render it. However, where the LCP resource is preloaded, or the rendering is delayed, there can be a larger gap between the load time and the render time.

This can lead to the seemingly impossible situation where LCP is reported by web APIs as earlier than FCP. This is not the case but only appears so due to this security restriction.

This was resolved in late 2024 and a slightly coarsened render time is available from Chrome 133 even when Timing-Allow-Origin is not provided.

When possible, it's still recommended to set the Timing-Allow-Origin header, so your metrics will be more accurate, particular for browsers that don't include this recent change.

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 don't 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:

An LCP timeline from cnn.com.

An LCP timeline from techcrunch.com.

In both of the timelines, 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 LCP occurring before the page fully loads.

An LCP timeline from instagram.com.

In this example, the Instagram logo is loaded relatively early and it remains the largest element even as other content is progressively shown.

Note: In the first frame of the Instagram timeline, you may notice the camera logo does not have a green box around it. That's because it's an <svg> element, and <svg> elements are not considered LCP candidates at this time (though <img src="...svg"> elements are, as are individual <image> elements within <svg> elements). The first LCP candidate is the text in the second frame.

An LCP timeline from google.com.

In this 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});

Warning: This code shows how to log largest-contentful-paint entries to the console, but measuring LCP in JavaScript is more complicated. For details, see Differences between the Metric and the API.

In the previous 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.
The API measures LCP from navigation start, but for prerendered pages LCP should be measured from activationStart since that corresponds to the LCP time as experienced by the user.

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—note the iframe issue is not covered):

import {onLCP} from 'web-vitals';

// Measure and log LCP as soon as it's available.
onLCP(console.log);

Refer to the source code for onLCP() for a complete example of how to measure LCP in JavaScript.

Note: In some cases (such as cross-origin iframes) it's not possible to measure LCP in JavaScript. See the limitations section of the web-vitals library for details.

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

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.

How to choose your Baseline target

Tue, 20 May 2025 07:00:00 GMT

Published: May 20, 2025

When a web platform feature is implemented in every browser, it becomes Baseline Newly available. After 30 months, that feature then becomes Baseline Widely available, which is a threshold in which most websites can adopt features without compatibility concerns. This guide explains how to use Baseline, and by using data available from your website's users, how to select a Baseline target.

What is a Baseline target?

A Baseline target is a grouping of web features that developers can choose to support, based on their Baseline status. There are two types of Baseline targets: moving targets and fixed targets.

Moving targets, such as Baseline Widely available or Baseline Newly available, are targets where the set of features contained may change over time. Moving targets make sense in cases where you want the set of supported features to evolve automatically as new browser versions are released.

Fixed targets are those where the set of features does not change over time. In general, fixed targets are based on calendar years. For example, Baseline 2023 is a fixed target that contains the set of web features that became Baseline Newly available in 2023. Baseline 2023 wouldn't include features that became Baseline after 2023, which means the set of Baseline 2023 features never changes.

Fixed targets make sense in cases where predictability and determinism are paramount, but they can become out of date over time, so when using fixed targets it's a good idea to re-evaluate your target regularly.

Why choose a target?

Adoption of features on the web is held back because of compatibility concerns—and that holds the web back from being as good as it could be. Baseline not only brings clarity to the question of feature support in browsers, but it can be helpful in how it clarifies the question of when you can use certain features. By choosing a target that reflects your audience and requirements you can feel confident in using features within that target group—without needing to check individual features one by one.

Use data to select your Baseline target

Knowing the right Baseline target to select should be, when possible, a data-driven decision. When you have the data in front of you, which target to select becomes an easier and much more informed decision.

If you have Real User Monitoring data for your site, you can learn how Baseline targets map to your users. For example, if you use Google Analytics, a free way to get this information is by using the Google Analytics Baseline Checker.

To use this tool, you'll need to authenticate using your Google Account and allow the tool to have read-only permission to view your Google Analytics data. From there, select the Google Analytics property you want Baseline target data generated for. After completing these steps, you'll receive output similar to the following:

The output of the Google Analytics Baseline Checker tool. The tool segments real user support for each Baseline target. Note how older Baseline targets have greater support amongst real users.

We're starting to see other tools implement support for Baseline, that can give you a dynamic view of how much of your audience supports a given target. For example, RUMvision includes a dashboard that shows how much of your audience has support for each Baseline year.

What if my analytics or RUM provider doesn't have a Baseline target report yet?

If you are using an analytics or RUM tool that doesn't provide a Baseline target report yet but does have data on browser versions, you can join your real-world data with browser version mappings from the baseline-browser-mapping module. The module provides a Javascript function - getAllVersions() - that maps browsers by name and version to their Baseline year and support status for Widely available. These mappings can be provided as arrays, keyed objects or as a CSV. For example, the Google Analytics Baseline Checker uses this module to join analytics data with Baseline targets.

The outputs of this function are also available as hosted JSON or CSV files which are updated on a daily basis. The all_versions_with_supports.csv file contains data that you can match to your analytics providers browser version data with the following fields:

browser: the name of the browser as used in baseline-browser-mapping
version: the version of the browser. Some browsers use only a major version number, others use a major.minor version number.
year: the Baseline year feature set that this browser version supports. If a browser version was released before Baseline support can be determined in July 2015, this field will contain pre_baseline
supports: this field contains widely or newly for browser versions that support those feature sets, and is empty for versions that don't support either of those feature sets. All browser versions that support Newly available also support Widely available.
release_date: the date this browser version was released, where available.
engine: The engine name for browsers that are downstream of a core Baseline browser. Only Blink-based browsers are included, but other browser engines may be represented in future.
engine_version: the Chromium version that this browser version implements. This is used to determine which Baseline feature set the downstream version supports.

This file is updated frequently as new browser versions are released and the support status of different browsers change. Make sure you refresh the data on a daily basis.

What if I don't have support data from real users?

You might find yourself in a situation where you can't get real user data when it comes to features that are Baseline. The good news is that you can get a general idea of support for different Baseline targets through RUM Archive Insights, even allowing you to filter down to the country level. While this data won't be specific to your website's users. It's a general informational tool that demonstrates the following assumptions are generally safe:

Newer Baseline targets—such as the current year or the year before—are likely to have the least amount of support among your users. Like any Baseline target, however, they will have better support as time passes.
Older Baseline targets—particularly Baseline Widely available—will be well-supported. When in doubt, Widely available is an excellent target which evolves as the 30 month window progresses through time.
Even older Baseline targets—those well beyond the 30 month Widely available window—will have the best support. While Widely available is a good default target, special use cases that require strict SLAs.

It's likely that, even if you're selecting a Baseline target that is over five years old, you're able to adopt features that you aren't using right now. In the best case scenario, you might already be using these features, but with polyfills that you might not need.

How do I enforce a chosen Baseline target in my project?

Browserslist is a commonly used method of targeting the browsers you want to support. It's used in bundlers and other associated tools such as Babel and PostCSS to decide whether certain bits of code need to be transformed or even polyfilled.

It's now possible to use Baseline with Browserslist so that, when you select a Baseline target, you can specify it as a valid Browserslist query. This ensures that the tools in your project transform code according to the target you've selected. For more information, read Use Baseline with Browserslist for more information.

What about features that don't meet my Baseline target?

After selecting a Baseline target, you might have features that you want to use, but don't fall inside that target. Baseline doesn't tell you what you should do here, and whether you want to consider using these features depends on the type of website you are building and the expected audience.

For example, ecommerce or B2B websites may be willing to have a lower support threshold and handle issues as their users support them, whereas government websites may require a high support threshold. One important rule of thumb here is that not all web features fail the same way. There's a lot of ways to categorize features on how they fail, but one way to bucket features that might be useful goes something like this:

Enhancement: If the feature is used in an unsupported browser, the experience is not broken. The experience could possibly be degraded, but may not likely be noticeable to the user. Example: loading="lazy".
Additive: The feature provides some additive benefits that may be noticeable—such as changes in page styling or some functionality. The difference may not be noticeable to users if the feature is unsupported, barring comparison in a browser that does support it. Example: Subgrid
Critical: If the feature is unsupported, the user will have a negative user experience—possibly even one that's broken altogether. Example: File System Access API used as a central and necessary feature.

You might also find that particular features outside of your target have better support than you think. It's possible to understand how many of your users have support for a particular feature. Can I Use has the ability to check support for individual features against your analytics data. RUMvision also has the ability to drill down and explore feature level data if that's helpful to you.

In this way, you can use your Baseline target to reduce the number of features that you need to carefully consider. Everything inside your target you don't need to worry about. If there are one or two features outside your target that would be especially useful—you have the tools to explore further and decide whether to polyfill or use as a progressive enhancement.

Conclusion

Every web application has different requirements—from an ecommerce site that can tolerate more incompatibility concerns, to a government website that absolutely must be available and operational to as many users as possible. These are calculations you have to make on your own, and it's not a goal of Baseline to tell you what decisions to make when it comes to adopting new web features, but more a matter of how.

Help users manage passkeys effectively

Thu, 15 May 2025 07:00:00 GMT

Published: May 15, 2025

Passkeys are rapidly emerging as a more secure, easier, and faster alternative to passwords, offering enhanced security and user convenience. To fully realize the potential of passkeys, careful consideration must be given to the user experience surrounding their management. This document outlines guidelines and optional features for designing an intuitive, secure, and robust passkey management system.

Manage multiple passkeys

Let users add multiple passkeys and use more than one provider. But don't let them add more than one passkey for the same account with the same provider. If a user loses access to one provider, such as when the platform doesn't support it, or the user loses access to it, they can still sign in with another passkey from a different provider. This setup lowers the risk of account lockouts. Make sure your database supports storing multiple passkeys per user.

Display a list of registered passkeys

Your website or app should display registered passkeys in a list with key details to help users manage them effectively. This screenshot illustrates how such a dedicated passkey management page might look. It shows how a user can create passkeys across multiple platforms, and provides a centralized place to manage them.

Example of a passkey management page showing good practices.

Here are some of the common details and features websites and apps can display about a passkey:

Passkey name: Display the passkey name which was given at the time of registration. Ideally this name matches the passkey provider it was created on based on the AAGUID. If no matching passkey provider is found, naming it after the device information based on the user agent string should be fine.
Passkey provider logo: Display the passkey provider logo. This helps the user identify the passkey they want to manage.
Timestamp of when the passkey was created and used the last time: Recording and displaying the passkey creation timestamp and last usage timestamp can also help the user identify the passkey they want to manage.
Non-sync indicator: Passkeys are synced by default, but the passkey providers sync capability is still evolving. It's a common confusion when a passkey doesn't sync despite the user's expectation. Showing a passkey's incapability of sync can help users clarify this confusion.
Delete button: Allow users to delete the passkey. See Allow deleting a passkey for more details.
Edit button: Many users appreciate being able to rename a passkey. For example, when there are multiple passkeys from the same passkey provider but with different provider accounts. Imagine saving multiple passkeys to different Google Accounts. By allowing the user to rename the passkey, they can change it to a name they like.
Last sign-in browser, OS or IP address: Optionally providing details about last sign-in helps the user identify suspicious sign-ins. The browser, OS or the IP address (or location) used to sign-in can be great information.

Allow deleting a passkey

Allow users to delete a passkey. This helps them tidy up the list, for example, when a user switches to a new device but the associated passkey is bound to the older device. It's also helpful when an attacker hijacks a user account and creates a passkey for future use.

Signal the updated list of passkeys

Deleting a passkey removes its credential entry and public key from the server database. This way, the passkey will disappear from the registered passkey list and it will appear to the user that the passkey is deleted. However, in reality, it's only removed from the server, and the passkey stored to the passkey provider still remains, which can cause confusion. The next time the user tries to sign in, the removed passkey will still appear as a sign in option. But, authenticating with it will fail, because the matching public key is already deleted from the server.

To avoid confusion, it's important to keep the passkey on a passkey provider and the public key on the server consistent. You can achieve this by signaling the updated list of passkeys to the passkey provider. If the browser and the passkey provider support the Signal API, they can update the list of passkeys and delete unnecessary passkeys. If they don't support the API, encourage the user to delete the passkey manually.

Delete the last passkey

If a user attempts to delete their last remaining passkey for a given account, make sure they understand that they will have to sign in with another option with more friction and potentially lesser protection. If this is their only sign-in method for your site, they won't be able to sign in again. Inform users how they can sign in next time, such as using a backup method if available or prompting them to register another passkey before proceeding. It's a good chance to collect feedback why they chose not to use a passkey.

Allow creation of new passkeys

While there are opportunities to create passkeys throughout a user's journey (like right after sign in), it's crucial to have a central hub where users can always go to create new passkeys, delete passkeys and manage passkeys. A passkey management screen is the best place for that.

To create a passkey user flow, follow the Create a passkey for passwordless logins Developer's Guide. For advanced security, consider allowing users to create a passkey on a hardware security token. You can expect users who are willing to manage passkeys to be more knowledgeable or experienced, so allowing them to create a passkey on their security key provides improved flexibility.

To allow saving passkeys to a hardware security token, leave authenticatorSelection.authenticatorAttachment unset instead of setting it to "platform" on a passkey creation request. This way, the browser accepts both platform (device) and roaming authenticators (a security key) without the user experience being significantly different from only allowing a platform authenticator. The option to create a passkey on a security key appears as a secondary option.

Checklist

Allow users to manage passkeys in a passkey management page.
Support registering multiple passkeys.
Allow users to add new and flexible types of passkeys on the management page.
Display the passkey name.
Indicate whether a passkey is syncable or non-syncable.
Allow users to remove a public key from the server.
Signal the list of passkeys when an associated public key is removed from the server.

Other UX guides

General passkey UX guides
Android guides
- User authentication with passkeys

How the Core Web Vitals metrics thresholds were defined

Wed, 07 May 2025 07:00:00 GMT

The research and methodology behind Core Web Vitals thresholds

Published: May 21, 2020, Last updated: May 7, 2025

Core Web Vitals are a set of field metrics that measure important aspects of real-world user experience on the web. Core Web Vitals includes metrics, as well as target thresholds for each metric, which help developers qualitatively understand whether the experience of their site is "good", "needs improvement", or is "poor". This post will explain the approach used to choose thresholds for Core Web Vitals metrics generally, as well as how the thresholds for each specific Core Web Vitals metric were chosen.

Refresher: Core Web Vitals metrics and thresholds

The Core Web Vitals are three metrics: Largest Contentful Paint (LCP), Interaction to Next Paint (INP), and Cumulative Layout Shift (CLS). Each metric measures a different aspect of user experience: LCP measures perceived load speed and marks the point in the page load timeline when the page's main content has likely loaded; INP measures responsiveness and quantifies the experience users feel when trying to interact with the page; and CLS measures visual stability and quantifies the amount of unexpected layout shift of visible page content.

Each Core Web Vitals metric has associated thresholds, which categorize performance as either "good", "needs improvement", or "poor":

	Good	Poor	Percentile
Largest Contentful Paint	≤2500 ms	>4000 ms	75
Interaction to Next Paint	≤200 ms	>500 ms	75
Cumulative Layout Shift	≤0.1	>0.25	75

Core Web Vitals thresholds

Additionally, to classify the overall performance of a page or site, we use the 75th percentile value of all page views to that page or site. In other words, if at least 75 percent of page views to a site meet the "good" threshold, the site is classified as having "good" performance for that metric. Conversely, if at least 25 percent of page views meet the "poor" threshold, the site is classified as having "poor" performance. So, for example, a 75th percentile LCP of 2 seconds is classified as "good", while a 75th percentile LCP of 5 seconds is classified as "poor".

Criteria for the Core Web Vitals metric thresholds

In this section, we'll look at the criteria for evaluating Core Web Vitals metric thresholds. The subsequent sections will go into more detail on how these criteria were applied to select the thresholds for each metric. In future years we anticipate making improvements and additions to the criteria and thresholds to further improve our ability to measure great user experiences on the web.

High-quality user experience

Our primary goal is to optimize for the user and their quality of experience. Given this, we aim to ensure that pages that meet the Core Web Vitals "good" thresholds deliver a high quality user experience.

To identify a threshold associated with high-quality user experience, we look to human perception and HCI research. While this research is sometimes summarized using a single fixed threshold, we find that the underlying research is typically expressed as a range of values. For example, research on the amount of time users typically wait before losing focus is sometimes described as 1 second, while the underlying research is actually expressed as a range, from hundreds of milliseconds to multiple seconds. The fact that perception thresholds vary depending on user and context is further supported by aggregated and anonymized Chrome metrics data, which shows that there is not a single amount of time users wait for a web page to display content before aborting the page load. Rather, this data shows a smooth and continuous distribution. For a more in depth look at human perception thresholds and relevant HCI research, see The Science Behind Web Vitals.

In cases where relevant user experience research is available for a given metric and there is reasonable consensus on the range of values in the literature, we use this range as an input to guide our threshold selection process. In cases where relevant user experience research is unavailable, such as for a new metric like Cumulative Layout Shift, we instead evaluate real-world pages that meet different candidate thresholds for a metric, to identify a threshold that results in a good user experience.

Achievable by existing web content

Additionally, to ensure that site owners can succeed in optimizing their sites to meet the "good" thresholds, we require that these thresholds are achievable for existing content on the web. For example, while zero milliseconds is an ideal LCP "good" threshold, resulting in instant loading experiences, a zero millisecond threshold is not practically achievable in most cases, due to network and device processing latencies. Thus, zero milliseconds is not a reasonable LCP "good" threshold for Core Web Vitals.

When evaluating candidate Core Web Vitals "good" thresholds, we verify that those thresholds are achievable, based on data from the Chrome User Experience Report (CrUX). To confirm that a threshold is achievable, we require that at least 10% of origins meet the "good" threshold. Additionally, to ensure that well-optimized sites are not misclassified due to variability in field data, we also verify that well-optimized content consistently meets the "good" threshold.

Conversely, we establish the "poor" threshold by identifying a level of performance that only a minority of origins are not meeting. Unless there is research available relevant to defining a "poor" threshold, by default the worst-performing 10-30% of origins are classified as "poor".

Whether to have the same or different criteria per device

Mobile and desktop usage typically have very different characteristics as to device capabilities and network reliability. This heavily impacts the "achievability" criteria and so suggests we should consider separate thresholds for each.

However, users' expectations of a good or poor experience is not dependent on device, even if the achievability criteria is. For this reason the Core Web Vitals recommended thresholds are not segregated by device and the same threshold is used for both. This also has the added benefit of making the thresholds simpler to understand.

Additionally, devices don't always fit nicely into one category. Should this be based on device form factor, processing power, or network conditions? Having the same thresholds has the side benefit of avoiding that complexity.

The more constrained nature of mobile devices means that most of the thresholds are therefore set based on mobile achievability. They more likely represent mobile thresholds—rather than a true joint threshold across all device types. However, given that mobile is often the majority of traffic for most sites, this is less of a concern.

Final thoughts on criteria

When evaluating candidate thresholds, we found that the criteria were sometimes in conflict with one another. For example, there can be a tension between a threshold being consistently achievable and it ensuring consistently good user experiences. Additionally, given that human perception research typically provides a range of values, and user behavior metrics show gradual changes in behavior, we found there is often no single "correct" threshold for a metric.

Thus, our approach for the Core Web Vitals has been to choose thresholds that best meet the criteria, while recognizing that there is no one perfect threshold and that we may sometimes need to choose from multiple reasonable candidate thresholds. Rather than asking "what is the perfect threshold?" we instead focused on asking "which candidate threshold best achieves our criteria?"

These are also broad thresholds that we can apply across the whole of the web. Many sites would benefit from optimizing even beyond the "good" thresholds and and should seek to correlate with their individual business metrics.

Choice of percentile

As noted earlier, to classify the overall performance of a page or site, we use the 75th percentile value of all visits to that page or site. The 75th percentile was chosen based on two criteria. First, the percentile should ensure that a majority of visits to a page or site experienced the target level of performance. Second, the value at the chosen percentile shouldn't be overly impacted by outliers.

These goals are somewhat at odds with one another. To satisfy the first goal, a higher percentile is typically a better choice. However, with higher percentiles, the likelihood of the resulting value being impacted by outliers also increases. If a few visits to a site happen to be on flaky network connections which result in excessively large LCP samples, we don't want our site classification to be decided by these outlier samples. For example, if we were evaluating the performance of a site with 100 visits using a high percentile such as the 95th, it would take just 5 outlier samples for the 95th percentile value to be affected by the outliers.

Given these goals are a bit at odds, after analysis, we concluded that the 75th percentile strikes a reasonable balance. By using the 75th percentile, we know that most visits to the site (3 of 4) experienced the target level of performance or better. Additionally, the 75th percentile value is less likely to be affected by outliers. Returning to our example, for a site with 100 visits, 25 of those visits would need to report large outlier samples for the value at the 75th percentile to be affected by outliers. While 25 of 100 samples being outliers is possible, it is much less likely than for the 95th percentile case.

Largest Contentful Paint

The LCP thresholds were set with the following quality of experience and achievability considerations.

Quality of experience

1 second is often cited as the amount of time a user will wait before they begin to lose focus on a task. On closer inspection of relevant research, we found that 1 second is an approximation to describe a range of values, from roughly several hundred milliseconds to several seconds.

Two commonly cited sources for the 1 second threshold are Card and others and Miller. Card defines a 1-second "immediate response" threshold, citing Newell's Unified Theories of Cognition. Newell explains immediate responses as "responses that must be made to some stimulus within very approximately one second (that is, roughly from ~0.3sec to ~3sec)." This follows Newell's discussion on "real-time constraints on cognition", where it is noted that "interactions with the environment which evoke cognitive considerations take place on the order of seconds" which range from roughly 0.5 to 2-3 seconds. Miller, another commonly cited source for the 1 second threshold, notes "tasks which humans can and will perform with machine communications will seriously change their character if response delays are greater than two seconds, with some possible extension of another second or so."

Miller and Card's research describes the amount of time a user will wait before losing focus as a range, from roughly 0.3 to 3 seconds, which suggests our LCP "good" threshold should be in this range. Additionally, given that the existing First Contentful Paint "good" threshold is 1 second, and that the Largest Contentful Paint typically occurs after First Contentful Paint, we further constrain our range of candidate LCP thresholds, from 1 second to 3 seconds. To choose the threshold in this range that best meets our criteria, we look at the achievability of these candidate thresholds next.

Achievability

Using data from CrUX, we can determine the percentage of origins on the web that meet our candidate LCP "good" thresholds.

	1 second	1.5 seconds	2 seconds	2.5 seconds	3 seconds
phone	3.5%	13%	27%	42%	55%
desktop	6.9%	19%	36%	51%	64%

% of CrUX origins classified as "good" for candidate LCP thresholds as of April 2020

While less than 10% of origins meet the 1 second threshold, all other thresholds from 1.5 to 3 seconds satisfy our requirement that at least 10% of origins meet the "good" threshold, and are thus still valid candidates.

In addition, to ensure the chosen threshold is consistently achievable for well-optimized sites, we analyze LCP performance for top-performing sites across the web, to determine which thresholds are consistently achievable for these sites. Specifically, we aim to identify a threshold that is consistently achievable at the 75th percentile for top performing sites. We find that the 1.5 and 2 second thresholds are not consistently achievable, while 2.5 seconds is consistently achievable.

To identify a "poor" threshold for LCP, we use CrUX data to identify a threshold met by most origins:

	3 seconds	3.5 seconds	4 seconds	4.5 seconds	5 seconds
phone	45%	35%	26%	20%	15%
desktop	36%	26%	19%	14%	10%

% of CrUX origins classified as "poor" for candidate LCP thresholds as of April 2020

For a 4 second threshold, roughly 26% of phone origins, and 21% of desktop origins, would be classified as poor. This falls in our target range of 10-30%, so we conclude that 4 seconds is an acceptable "poor" threshold.

Thus, we conclude that 2.5 seconds is a reasonable "good" threshold, and 4 seconds is a reasonable "poor" threshold for Largest Contentful Paint.

Interaction to Next Paint

The INP thresholds were set with the following quality of experience and achievability considerations.

Quality of experience

Research is reasonably consistent in concluding that delays in visual feedback of up to around 100 ms are perceived as being caused by an associated source, such as a user input. This suggests that an ideal Interaction to Next Paint "good" threshold would be close to this.

Jakob Nielsen's commonly cited Response Times: The 3 Important Limits defines 0.1 second as the limit for having the user feel that the system is reacting instantaneously. Nielsen cites Miller and Card, who cites Michotte's 1962 The Perception of Causality. In Michotte's research, experiment participants are shown "two objects on a screen. Object A sets off and moves towards B. It stops at the moment when it comes into contact with B, while the latter then starts and moves away from A." Michotte varies the time interval between when Object A stops and when Object B starts to move. Michotte finds that, for delays up to roughly 100 ms, participants have the impression that Object A causes the motion of Object B. For delays from roughly 100 ms to 200 ms, the perception of causality is mixed, and for delays over 200 ms, the motion of Object B is no longer seen as having been caused by Object A.

Similarly, Miller defines a response threshold for "Response to control activation" as "the indication of action given, ordinarily, by the movement of a key, switch or other control member that signals it has been physically actIvated. This response should be…perceived as a part of the mechanical action induced by the operator. Time delay: No more than 0.1 second" and later "the delay between depressing a key and visual feedback should be no more than 0.1 to 0.2 seconds".

More recently, in Towards the Temporally Perfect Virtual Button, Kaaresoja and others investigated the perception of simultaneity between touching a virtual button on a touchscreen and subsequent visual feedback indicating the button was touched, for various delays. When the delay between button press and visual feedback was 85ms or less, participants reported the visual feedback appeared simultaneously with the button press 75% of the time. Additionally, for delays of 100 ms or less, participants reported a consistently high perceived quality of the button press, with perceived quality falling off for delays of 100 ms to 150 ms, and reaching very low levels for delays of 300 ms.

Given this, we conclude that research points to 100 ms as a "good" Interaction to Next Paint threshold for Web Vitals. Additionally, given users reported low quality levels for delays of 300 ms or more, ideally this would be the "poor" threshold.

Achievability

Using data from CrUX, we determine that the majority of origins on the web meet the 200 ms INP "good" threshold at the 75th percentile:

	100 ms	200 ms	300 ms	400 ms	500 ms
phone	12%	56%	76%	88%	92%
desktop	83%	96%	98%	99%	99%

% of CrUX origins classified as "good" for candidate INP thresholds as of May 2022

We also spent extra attention looking at achievability of passing INP for lower-end mobile devices, where those formed a high proportion of visits to sites. This further confirmed the suitability of a 200 ms threshold.

Taking into consideration the 100 ms threshold supported by research into the quality of experience and the achievability criteria, we conclude that 200 ms is a reasonable threshold for good experiences

To identify a "poor" threshold for LCP, we use CrUX data to identify a threshold met by most origins:

	100 ms	200 ms	300 ms	400 ms	500 ms
phone	88%	44%	24%	12%	8%
desktop	17%	4%	2%	1%	1%

% of CrUX origins classified as "poor" for candidate INP thresholds as of May 2022

This suggests we can have a "poor" threshold of 300 ms.

However, unlike LCP and CLS, INP has an inverse correlation with popularity—the more popular sites are often more complex, resulting in more likelihood of higher INP. When we look at the top 10,000 sites—which form the vast majority of internet browsing—we see a more complex picture emerge:

	100 ms	200 ms	300 ms	400 ms	500 ms
phone	97%	77%	55%	37%	24%
desktop	48%	17%	8%	4%	2%

% of CrUX origins in top 10,000 classified as "poor" for candidate INP thresholds as of May 2022

On mobile, a 300 ms "poor" threshold would classify the majority of popular sites as "poor" stretching our achievability criteria, while 500 ms fits better in the range of 10-30% of sites. It should also be noted that the 200 ms "good" threshold is also tougher for these sites, but with 23% of sites still passing this on mobile this still passes our 10% minimum pass rate criteria.

For this reason we conclude a 200 ms is a reasonable "good" threshold for most sites, and greater than 500 ms is a reasonable "poor" threshold.

Cumulative Layout Shift

The CLS thresholds were set with the following quality of experience and achievability considerations.

Quality of experience

Cumulative Layout Shift (CLS) is a new metric that measures how much the visible content of a page shifts around. Given CLS is new, we are not aware of research that can directly inform the thresholds for this metric. Thus, to identify a threshold that is aligned with user expectations, we evaluated real-world pages with different amounts of layout shift, to determine the maximum amount of shift that is perceived as acceptable before causing significant disruptions when consuming page content. In our internal testing, we found that levels of shift from 0.15 and higher were consistently perceived as disruptive, while shifts of 0.1 and lower were noticeable but not excessively disruptive. Thus, while zero layout shift is ideal, we concluded that values up to 0.1 are candidate "good" CLS thresholds.

Achievability

Based on CrUX data, we can see that nearly 50% of origins have CLS of 0.05 or lower.

	0.05	0.1	0.15
phone	49%	60%	69%
desktop	42%	59%	69%

% of CrUX origins classified as "good" for candidate CLS thresholds as of April 2020

While the CrUX data suggests that 0.05 might be a reasonable CLS "good" threshold, we recognize that there are some use cases where it is difficult to avoid disruptive layout shifts. For example, for third-party embedded content, such as social media embeds, the height of the embedded content is sometimes not known until it finishes loading, which can lead to a layout shift greater than 0.05. Thus, we conclude that, while many origins meet the 0.05 threshold, the slightly less stringent CLS threshold of 0.1 strikes a better balance between quality of experience and achievability. It is our hope that, going forward, the web ecosystem will identify solutions to address layout shifts caused by third party embeds, which would allow for using a more stringent CLS "good" threshold of 0.05 or 0 in a future iteration of Core Web Vitals.

Additionally, to determine a "poor" threshold for CLS, we used CrUX data to identify a threshold met by most origins:

	0.15	0.2	0.25	0.3
phone	31%	25%	20%	18%
desktop	31%	23%	18%	16%

% of CrUX origins classified as "poor" for candidate CLS thresholds as of April 2020

For a 0.25 threshold, roughly 20% of phone origins, and 18% of desktop origins, would be classified as "poor". This falls in our target range of 10-30%, so we concluded that 0.25 is an acceptable "poor" threshold.

High DPI images for variable pixel densities

Mon, 14 Apr 2025 07:00:00 GMT

Published: August 22, 2012, Last updated: April 14, 2025

With so many devices on the market, there's a very wide range of screen pixel densities available. Application developers need to support a range of pixel densities, which can be quite challenging. On the mobile web, the challenges are compounded by several factors:

Large variety of devices with different form factors.
Constrained network bandwidth and battery life.

In terms of images, the goal for web developers is to serve the best quality images as efficiently as possible. Here, we cover some useful techniques to do this now and in the future.

Avoid images when possible

Before assuming you need to include an image, remember that the web has numerous powerful technologies that are largely resolution- and DPI-independent. Specifically, text, SVG, and much of CSS "just works" because of the automatic pixel scaling feature of the web with devicePixelRatio.

That said, you can't always avoid raster images. For example, you may be given assets that would be quite hard to replicate in pure SVGs or CSS. You may be dealing with a photograph. While you could convert an image into an SVG automatically, vectorizing photographs makes little sense because scaled-up versions usually don't look good.

History of pixel density

In the early days, computer displays had a pixel density of 72 or 96 dots per inch (DPI).

Displays gradually improved in pixel density, largely driven by the advance of mobile devices, as users generally hold their phones closer to their faces making pixels more visible. By 2008, 150dpi phones were the new norm. Increased display density continued, and today's phones have 300dpi displays.

In practice, low density images should look the same on new screens as they did on old ones, but compared to the crisp imagery high density users are used to seeing, the low density images look jarring and pixelated. The following is a rough simulation of how a 1x image looks on a 2x display. In contrast, the 2x image looks quite good.

Baboons at differing pixel densities.
1x pixels	2x pixels

Pixels on the web

When the web was designed, 99% of displays were 96dpi and few provisions were made for variations. Now that we have a large variation in screen sizes and densities, we need a standard way to make images look good across them all.

The HTML specification tackled this problem by defining a reference pixel that manufacturers use to determine the size of a CSS pixel.

Using the reference pixel, a manufacturer can determine the size of the device's physical pixel relative to the standard or ideal pixel. This ratio is called the device pixel ratio.

Calculate the device pixel ratio

Suppose a mobile phone has a screen with a physical pixel size of 180 pixels per inch (ppi). Calculating the device pixel ratio takes three steps:

Compare the actual distance at which the device is held to the distance for the reference pixel.

Per the spec, we know that at 28 inches, the ideal is 96 pixels per inch. With a mobile phone, we know people's faces are closer to their devices than with laptops and desktop computers. For the following equations, we estimate that distance to be 18 inches.
Multiply the distance ratio against the standard density (96ppi) to get the ideal pixel density for the given distance.

idealPixelDensity = (28/18) * 96 = 150 pixels per inch (approximately)
Take the ratio of the physical pixel density to the ideal pixel density to get the device pixel ratio.

devicePixelRatio = 180/150 = 1.2

One reference angular pixel, to illustrate how the device pixel ratio is calculated.

So now when a browser needs to know how to resize an image to fit the screen, according to the ideal or standard resolution, the browser refers to the device pixel ratio of 1.2. This means for every ideal pixel, this device has 1.2 physical pixels. The formula to go between ideal (as defined by the web spec) and physical (dots on device screen) pixels is the following:

physicalPixels = window.devicePixelRatio * idealPixels

Historically, device vendors have tended to round devicePixelRatios (DPRs). Apple's iPhone and iPad report DPR of 1, and their Retina equivalents report 2. The CSS specification recommends that

the pixel unit refer to the whole number of device pixels that best approximates the reference pixel.

One reason why round ratios can be better is because they may lead to fewer sub-pixel artifacts.

However, the reality of the device landscape is much more varied, and Android phones often have DPRs of 1.5. The Nexus 7 tablet has a DPR of ~1.33, which was arrived at by a calculation similar to the previous example. Expect to see more devices with variable DPRs in the future. Because of this, you should never assume that your clients have integer DPRs.

HiDPI image techniques

There are many techniques for solving the problem of showing the best quality images as fast as possible, broadly falling into two categories:

Optimizing single images.
Optimizing selection between multiple images.

Single image approaches: use one image, but do something clever with it. These approaches have the drawback that you must inevitably sacrifice performance, since you have to download HiDPI images, even on older devices with lower DPI. Here are some approaches for the single image case:

Heavily compressed HiDPI image
Totally awesome image format
Progressive image format

Multiple image approaches: use multiple images, but do something clever to pick which to load. These approaches have inherent overhead for the developer to create multiple versions of the same asset and then figure out a decision strategy. Here are the options:

JavaScript
Server side delivery
CSS media queries
Built-in browser features (image-set(), <img srcset>)

Heavily compressed HiDPI image

Images already comprise a whopping 60% of bandwidth spent downloading an average website. By serving HiDPI images to all clients, we increase this number. How much bigger can it grow?

I ran some tests which generated 1x and 2x image fragments with JPEG quality at 90, 50 and 20.

From this small, unscientific sampling, it seems that compressing large images provides a good quality-to-size tradeoff. To my eye, heavily compressed 2x imagery actually looks better than uncompressed 1x pictures.

That said, serving low-quality, highly compressed 2x imagery to 2x devices is worse than serving higher quality ones, and that approach would incur image quality penalties. If you compare quality: 90 images to quality: 20 images, there's a drop in how crisp the image is and increased graininess. Artifacts with quality:20 may not be acceptable where high quality images are important (for example, a photo viewer application) or for app developers that are unwilling to compromise.

This comparison was made entirely with compressed JPEGs. It's worth noting that there are many tradeoffs between the widely implemented image formats (JPEG, PNG, GIF), which brings us to…

WebP: Totally awesome image format

WebP is a pretty compelling image format that compresses very well while keeping high image fidelity.

One way is to check for WebP support is using JavaScript. Load a 1px image with data-uri, wait for either loaded or error events fired, and then verify that the size is correct. Modernizr ships with such a feature detection script, which is available with Modernizr.webp.

A better way of doing this, however, is directly in CSS using the image() function. So if you have a WebP image and JPEG fallback, you can write the following:

#pic {
  background: image("foo.webp", "foo.jpg");
}

There are a few problems with this approach. First, image() is not at all widely implemented. Secondly, while WebP compression blows JPEG out of the water, it's still a relatively incremental improvement – about 30% smaller based on this WebP gallery. Thus, WebP alone isn't enough to address the high DPI problem.

Progressive image formats

Progressive image formats like JPEG 2000, Progressive JPEG, Progressive PNG and GIF have the (somewhat debated) benefit of seeing the image come into place before it's fully loaded. They may incur some size overhead, though there is conflicting evidence about this. Jeff Atwood claimed that progressive mode "adds about 20% to the size of PNG images, and about 10% to the size of JPEG and GIF images". However, Stoyan Stefanov claimed that for large files, progressive mode is more efficient (in most cases).

At first glance, progressive images look very promising in the context of serving the best quality images as fast as possible. The idea is that the browser can stop downloading and decoding an image once it knows that additional data won't increase the image quality (ie. all of the fidelity improvements are sub-pixel).

While connections are quick to terminate, they are often expensive to restart. For a site with many images, the most efficient approach is to keep a single HTTP connection alive, reusing it for as long as possible. If the connection is terminated prematurely because one image has been downloaded enough, the browser then needs to create a new connection, which can be really slow in low latency environments.

One workaround to this is to use the HTTP Range request, which lets browsers specify a range of bytes to fetch. A smart browser could make a HEAD request to get at the header, process it, decide how much of the image is actually needed, and then fetch. Unfortunately HTTP Range is poorly supported in web servers, making this approach impractical.

Finally, an obvious limitation of this approach is that you don't get to choose which image to load, only varying fidelities of the same image. As a result, this doesn't address the "art direction" use case.

Use JavaScript to decide which image to load

The first and most obvious approach to deciding which image to load is to use JavaScript in the client. This approach lets you find out everything about your user agent and do the right thing. You can determine device pixel ratio with window.devicePixelRatio, get screen width and height, and even potentially do some network connection sniffing with navigator.connection or issuing a fake request, like the foresight.js library does. Once you've collected all of this information, you can decide which image to load.

There are approximately one million JavaScript libraries that use this technique. Unfortunately, none of them are particularly outstanding.

One big drawback is that you delay image loading until after the look-ahead parser has finished. This essentially means that images won't even start downloading until after the pageload event fires. More on this in Jason Grigsby's article.

Decide what image to load on the server

You can defer the decision to the server-side by writing custom request handlers for each image you serve. Such a handler would check for Retina support based on User-Agent (the only piece of information shared with the server). Then, based on whether the server-side logic wants to serve HiDPI assets, you load the appropriate asset (named according to some known convention).

Unfortunately, the User-Agent doesn't necessarily provide enough information to decide whether a device should receive high or low quality images. And, any solution that uses the User-Agent to make style decisions should be avoided.

Use CSS media queries

Being declarative, CSS media queries let you state your intention, and let the browser do the right thing on your behalf. In addition to the most common use of media queries—matching device size—you can also match devicePixelRatio. The associated media query is device-pixel-ratio, and has associated min and max variants, as you might expect.

If you want to load high DPI images and the device pixel ratio exceeds a threshold, here's what you might do:

#my-image { background: (low.png); }

@media only screen and (min-device-pixel-ratio: 1.5) {
  #my-image { background: (high.png); }
}

It gets a little more complicated with all of the vendor prefixes mixed in, especially because of large differences in placement of "min" and "max" prefixes:

@media only screen and (min--moz-device-pixel-ratio: 1.5),
    (-o-min-device-pixel-ratio: 3/2),
    (-webkit-min-device-pixel-ratio: 1.5),
    (min-device-pixel-ratio: 1.5) {

  #my-image {
    background:url(high.png);
  }
}

With this approach, you regain the benefits of look-ahead parsing, which was lost with the JavaScript solution. You also gain the flexibility of choosing your responsive breakpoints (for example, you can have low, mid and high DPI images), which was lost with the server-side approach.

Unfortunately it's still a little unwieldy, and leads to strange looking CSS or requires preprocessing. Also, this approach is restricted to CSS properties, so there's no way to set an <img src>, and your images must all be elements with a background. Finally, by relying strictly on device pixel ratio, you can end up in situations where your High-DPI mobile phone ends up downloading a massive 2x image asset while on an EDGE connection. This isn't the best user experience.

As image-set() is a CSS function, it doesn't address the problem for <img> tags. Enter @srcset, which addresses this issue. The next section goes deeper into image-set and srcset.

Browser features for high DPI support

Ultimately, how you approach high DPI support depends on your particular requirements. All of the aforementioned approaches have drawbacks.

Now that image-set and srcset are widely supported, they're the best solutions. There are additional best practices that can bring us closer for older browsers.

How are these two different? Well, image-set() is a CSS function, appropriate for use as a value of the background CSS property. srcset is an attribute specific to <img> elements, with similar syntax. Both of these tags let you specify image declarations, but the srcset attribute lets you also configure which image to load based on viewport size.

Best practices for image-set

The image-set() syntax takes one or more comma separated image declarations, which consist of a URL string or url() function followed by the appropriate resolution. For example:

image-set(
  url("image1.jpg") 1x,
  url("image2.jpg") 2x
);

/* You can also include image-set without `url()` */
image-set(
  "image1.jpg" 1x,
  "image2.jpg" 2x
);

This tells the browser is that there are two images to choose from. One image is optimized for 1x displays and the other for 2x displays. The browser then gets to choose which one to load, based on a variety of factors, which might even include network speed, if the browser is smart enough.

In addition to loading the correct image, the browser scales it accordingly. In other words, the browser assumes that 2 images are twice as large as 1x images, and so scales the 2x image down by a factor of 2, so that the image appears to be the same size on the page.

Instead of specifying 1x, 1.5x or Nx, you can also specify a certain device pixel density in DPI.

If you're concerned about older browsers that don't support the image-set property, you can add a fallback to ensure an image is displayed. For example:

/* Fallback support. */
background-image: url(icon1x.jpg);
background-image: image-set(
  url(icon1x.jpg) 1x,
  url(icon2x.jpg) 2x
);

image-set(
  url(icon1x.jpg) 1x,
  url(icon2x.jpg) 2x
);

This sample code loads the appropriate asset in browsers that support image-set and falls back to the 1x asset otherwise.

At this point, you may be wondering why not just polyfill (that is, build a JavaScript shim for) image-set() and call it a day? As it turns out, it's quite difficult to implement efficient polyfills for CSS functions. (For a detailed explanation why, see this www-style discussion).

Image srcset

In addition to the declarations that image-set provides, the srcset element also takes width and height values which correspond to the size of the viewport, attempting to serve the most relevant version.

<img alt="my awesome image"
  src="banner.jpeg"
  srcset="banner-HD.jpeg 2x, banner-phone.jpeg 640w, banner-phone-HD.jpeg 640w 2x">

This example serves banner-phone.jpeg to devices with viewport width under 640px, banner-phone-HD.jpeg to small screen high DPI devices, banner-HD.jpeg to high DPI devices with screens greater than 640px, and banner.jpeg to everything else.

Use image-set for image elements

It may be tempting to replace your img elements with <div>s with backgrounds and use the image-set approach. This does work, with caveats. The drawback here is that the <img> tag has long-time semantic value. In practice, this is important for accessibility and web crawlers.

You could use the content CSS property, which automatically scales the image based on devicePixelRation. For example:

<div id="my-content-image"
  style="content: -webkit-image-set(
    url(icon1x.jpg) 1x,
    url(icon2x.jpg) 2x);">
</div>

Polyfill srcset

One handy feature of srcset is that it comes with a natural fallback. In the case where the srcset attribute is not implemented, all browsers know to process the src attribute. Also, since it's just an HTML attribute, it's possible to create polyfills with JavaScript.

This polyfill comes with unit tests to ensure that it's as close to the specification as possible. In addition, there are checks in place that prevent the polyfill from executing any code if srcset is implemented natively.

Conclusion

The best solution for high-DPI images is to opt for SVGs and CSS. However, this isn't always a realistic solution, especially for image-dense websites.

Approaches in JavaScript, CSS, and server-side solutions have their strengths and weaknesses. The most promising approach is to use image-set and srcset.

To summarize, my recommendations are as follows:

For background images, use image-set with the appropriate fallbacks for browsers that don't support it.
For content images, use a srcset polyfill, or fallback to using image-set (see above).
For situations where you're willing to sacrifice image quality, consider using heavily compressed 2x images.

Optimize Largest Contentful Paint

Mon, 31 Mar 2025 07:00:00 GMT

A step-by-step guide on how to break down LCP and identify key areas to improve.

Published: April 30, 2020, Last updated: March 31, 2025

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.

A good LCP value is 2.5 seconds or less.

A number of factors can affect how quickly the browser can 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 by using the Chrome User Experience Report (CrUX) which collect anonymous data from real Chrome users for millions of websites.

Using Chrome DevTools CrUX LCP data

The Performance panel of Chrome DevTools shows your local LCP experience next to the page or origin's CrUX LCP in the live metrics view, and in the Insights of a performance trace including a breakdown of the LCP subpart timings (that we will explain shortly).

Local and field LCP in the Chrome DevTools Performance panel live metrics and trace views.

By layering field data onto the Performance panel, you can assess whether a page has any real-user LCP issues and adapt your local environment settings to better reproduce and debug those issues.

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.

CrUX data shown in PageSpeed Insights.

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

You can toggle these in the controls at the top and top right-hand side of this section. If a URL doesn't have enough data to be shown at the URL level, but does have data for the origin, PageSpeed Insights always shows the origin data.

When PageSpeed Insights doesn't have URL-level data, it shows origin-level data.

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 multiple 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 in agreement with real user data provided by CrUX. If Lighthouse and CrUX disagree, then CrUX likely provides a more accurate picture of your user experience. Make sure your CrUX data is for your page, not the full origin, before you act on it.

If both Lighthouse and CrUX show LCP values that need improvement, the Lighthouse section can provide valuable guidance on ways to improve LCP. Use the LCP filter to only show audits relevant to LCP as follows:

Lighthouse diagnostics and suggestions for improving 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:

Lighthouse's breakdown of LCP elements.

LCP resource types and subparts are also available in CrUX.

We will delve into these subparts 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 section presents a methodology for how to break down LCP into its most critical subparts 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 before, 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.

A waterfall diagram showing the loading times for a webpage's HTML and the resources the LCP needs.

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 subparts:

Time to First Byte (TTFB): The time from when the user initiates loading the page until the browser receives the first byte of the HTML document response.
Resource load delay: The time between TTFB and when the browser starts loading the LCP resource. If the LCP element doesn't require a resource load to render (for example, if the element is a text node rendered with a system font), this time is 0.
Resource load duration: The duration of time it takes to load the LCP resource itself. If the LCP element doesn't require a resource load to render, this time is 0.
Element render delay: The time between when the LCP resource finishes loading and the LCP element rendering fully.

The same waterfall diagram, with the four LCP subparts overlaid on the timeline.

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

When optimizing LCP, it's helpful to try to optimize these subparts 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 won't 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 duration, but it wouldn't actually improve LCP because the time would just shift to the element render delay subpart:

Shortening the resource load duration increases the element render delay without reducing LCP.

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 subparts in order to achieve the best LCP outcomes.

Optimal subpart times

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

Of the four subparts, 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 subpart	% of LCP
Time to first byte	~40%
Resource load delay	<10%
Resource load duration	~40%
Element render delay	<10%
TOTAL	100%

Note that these time breakdowns are guidelines, not strict rules. 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 subpart 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.

On this page, the LCP resource starts loading well after the style sheet that loads first. There's room for improvement here.

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 using <link rel="preload"> in the HTML markup (or using a Link header).
The LCP element is a text node that requires a web font to render, and the font is loaded using <link rel="preload"> in the HTML markup (or using 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 using 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 be discoverable from the HTML source. In cases where the resource is only referenced from an external CSS or JavaScript file, the LCP resource should be preloaded with a high fetch priority, 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 don't recognize that the resource is important, or if it determines that other resources are more important.

For example, you can delay your LCP image using HTML if you set loading="lazy" on your <img> element. Using lazy loading means that the resource won't 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 using 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. However, setting a high priority on more than one or two images makes priority setting unhelpful in reducing LCP.

You can also lower the priority of images that might be early in the document response but aren't visible due to styling, such as images in carousel slides that aren't 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):

The LCP resource now starts loading at the same time as the style sheet.

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

Style sheets loaded from the HTML markup will block rendering of all content that follows them, which is good, since you generally don't want to render unstyled HTML. However, if the style sheet 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:

The image and the style sheet start loading at the same time, but the image can't render until the style sheet is ready.

To fix this, your options are to either:

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

In general, inlining your style sheet is only recommended if your style sheet is small since inlined content in the HTML cannot benefit from caching in subsequent page loads. If a style sheet 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 style sheet 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 style sheet 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 style sheet 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 won't 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 advice from earlier, 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 duration

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 four 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).

Image CDNs in particular are especially helpful 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 duration 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 duration to essentially zero!

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 won't 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 visitors arriving through multiple redirects, such as from advertisements or shortened links. Always 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 don't result in different pages.

For specific guidance on optimizing TTFB, consult the optimize TTFB guide.

Monitor LCP breakdown in JavaScript

The timing information for all of the LCP subparts discussed earlier is available to you in JavaScript through a combination of the following performance APIs:

Many RUM products already calculate the subparts using these APIs. The web-vitals library also includes these LCP subpart timings in the attribution build and its code can be referenced for how to calculate these in JavaScript.

Chrome DevTools, and Lighthouse also measures these subparts as shown in the previous screenshots, saving you the need to calculate them manually in JavaScript when using those tools.

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.

Permission UX

Wed, 26 Mar 2025 07:00:00 GMT

The natural step after getting a PushSubscription and saving it our server is to trigger a push message, but there is one thing I flagrantly glossed over. The user experience when asking for permission from the user to send them push messages.

Sadly, very few sites give much consideration to how they ask their user for permission, so let's take a brief aside to look at both good and bad UX.

Common patterns

There have been a few common patterns emerging that should guide and help you when deciding what is best for your users and use case.

Value proposition

Ask users to subscribe to push at a time when the benefit is obvious.

For example, a user has just bought an item on an online store and finished the checkout flow. The site can then offer updates on the delivery status.

There are a range of situations where this approach works:

A particular item is out of stock, would you like to be notified when it's next available?
This breaking news story will be regularly updated, would you like to be notified as the story develops?
You're the highest bidder, would you like to be notified if you are outbid?

These are all points where the user has invested in your service and there is a clear value proposition for them to enable push notifications.

Owen created a mock of a hypothetical airline website to demonstrate this approach.

After the user has booked a flight it asks if the user would like notifications of flight delays.

Note that this is a custom UI from the website.

Another nice touch to Owen's demo is that if the user clicks to enable notifications, the site adds a semi-transparent overlay on the entire page when it shows the permission prompt. This draws the users attention to the permission prompt.

The alternative to this example, the bad UX for asking permission, is to request permission as soon as a user lands on the airline's site.

This approach provides no context as to why notifications are needed or useful to the user. The user is also blocked from achieving their original task (i.e. book a flight) by this permission prompt.

Double Permission

You may feel that your site has a clear use case for push messaging and as a result want to ask the user for permission as soon as possible.

For example instant messaging and email clients. Showing a message for a new message or email is an established user experience across a range of platforms.

For these category of apps, it's worth considering the double permission pattern.

First show a dialog that your website controls, explaining the value for your site's use case. The dialog can then offer buttons to trigger or forego the necessary permission request. If the user provides a positive signal, request permission, triggering the real browser permission prompt.

With this approach you display a custom prompt in your web app which first provides context. By doing this, the user can chose to enable or disable without your website running the risk of being permanently blocked because the user was annoyed by an unexpected permission prompt. If the user selects enable on the custom UI, display the actual permission prompt, otherwise hide your custom dialog and respect the user's choice.

Settings Panel

You can move notifications into a settings panel, giving users an easy way to enable and disable push messaging, without the need of cluttering your web app's UI.

A good example of this is the Google I/O site. When you first load up the Google I/O site, you aren't asked to do anything, the user is left to explore the site.

After a few visits, clicking the menu item on the right reveals a settings panel allowing the user to set up and manage notifications.

Clicking on the checkbox displays the permission prompt. No hidden surprises.

After the permission has been granted, the checkbox is checked and the user is good to go. The great thing about this UI is that users can enable and disable notifications from one location on the website.

Passive approach

One of the easiest ways to offer push to a user is to have a button or toggle switch that enables / disables push messages in a location on the page that is consistent throughout a site.

This doesn't drive users to enable push notifications, but offers a reliable and easy way for users to opt in and out of engaging with your website. For sites like blogs that might have some regular viewers as well as high bounce rates, this is a solid option as it targets regular viewers without annoying drive-by visitors.

On my personal site, I have a toggle switch for push messaging in the footer.

It's fairly out of the way, but for regular visitors it should get enough attention from readers wanting to get updates. One-time visitors are completely unaffected.

If the user subscribes to push messaging, the state of the toggle switch changes and maintains state throughout the site.

The bad UX

Those are some of the common practices I've noticed on the web. Sadly, there is one very common bad practice.

The worst thing you can do is to show the permission dialog to users as soon as they land on your site.

They have zero context on why they are being asked for a permission, they may not even know what your website is for, what it does or what it offers. Blocking permissions at this point out of frustration is not uncommon, this pop-up is getting in the way of what they are trying to do.

Remember, if the user blocks the permission request, your web app can't ask for permission again. To get permission after being blocked, the user has to change the permission in the browser's UI and doing so is not easy, obvious or fun for the user.

No matter what, don't ask for permission as soon as the user opens your site, consider some other UI or approach that has an incentive for the user to grant permission.

Offer a way out

In addition to considering the UX to subscribe a user to push, please consider how a user should unsubscribe or opt out of push messaging.

The number of sites that ask for permission as soon as the page loads and then offer no UI for disabling push notifications is astounding.

Your site should explain to your users how they can disable push. If you don't, users are likely to take the nuclear option and block permission permanently.

Where to go next

Code labs

How to think about Baseline and polyfills

Tue, 18 Mar 2025 07:00:00 GMT

Published: March 18, 2025

Polyfills have long been a part of the web developer experience, as they attempt to provide support for web features that aren't supported in all browsers. It would seem that polyfills are an indispensable tool in the web developer's toolkit, but it's nearly impossible to distill such a complex area of concern into a single, definitive statement.

Knowing when to use a polyfill for a feature depends on its availability across browsers, and Baseline can be helpful in making that determination. While Baseline doesn't tell you whether or not you should use polyfills, the clarity it brings to the availability of web platform features gives you an opportunity to be more selective, as excessive polyfills in an application can have significant drawbacks.

What are polyfills?

A polyfill is code that evaluates support for a feature in a browser, and—if the feature is unsupported—it will use JavaScript to attempt to provide that missing functionality.

An early example of a polyfill is Matchmedia.js, which used JavaScript to detect and provide support for the matchMedia method. matchMedia lets developers evaluate whether a media query matches the state of the current viewport in JavaScript. By loading a polyfill to provide the missing feature, it became possible to use the matchMedia method in any browser—but this polyfill is now no longer necessary, as matchMedia is available in nearly every browser in use.

While adding support for unsupported features is advantageous in some ways, the disadvantages of polyfills often go overlooked. As the number of polyfills increase in a web application, they can begin to have negative impacts.

What are the disadvantages of polyfills?

A feature that's polyfilled always has a cost compared to the same feature that's supported in a browser, and these costs add up as you add more polyfills:

Polyfills are written in JavaScript, and any additional JavaScript in a web application can affect performance. Negative impacts can include render blocking, and blocking the main thread due to the additional long tasks that JavaScript can introduce through additional parsing and compiling work.
Polyfills can also impact accessibility if they don't adhere to the specification of features they attempt to emulate. Some features modify the accessibility tree in ways that polyfills don't or can't.
Compared to features implemented directly in browsers, polyfills may not have the ability to faithfully reproduce all aspects of the features they try to provide. This can lead to situations where the user experience is impacted in unexpected ways, or restricts how much of the feature is usable.

A good example of a polyfill that comes with some of these disadvantages is the container queries polyfill. Container queries let you apply CSS rules based on the state of an HTML element itself, as opposed to media queries, which let you apply CSS to elements based on the state of the viewport. This polyfill uses the ResizeObserver and MutationObserver JavaScript APIs to mimic the capabilities of container queries. In particular, ResizeObserver callbacks occur just before the browser draws a new frame, which increases presentation delay, an important consideration when optimizing a page's Interaction to Next Paint (INP).

Beyond performance, there are some aspects of container queries that a polyfill can't provide. While it's true that not every polyfill results in user experience problems or incomplete implementations of web features, the more of them you use, the more likely your application will be impacted in a negative way.

Where does Baseline come in?

It used to be difficult to evaluate whether a particular web feature was safe to use, even though data sources such as browser-compat-data have been used by various tools to help developers make these difficult decisions. Can I Use is a popular web feature support matrix that uses this data.

Baseline goes a step further by providing clear and consistent messaging about which web features are supported across all browsers through three status indicators:

Limited availability: The feature is not supported across all major browsers.
Newly available: The feature has emerged in all major browsers within the last 30 months.
Widely available: The feature has been supported in all major browsers for more than the last 30 months.

Baseline does not consider polyfills as a part of its messaging. For example, if a feature has Limited availability, but is polyfillable for all browsers, that feature is never assumed to be either Newly or Widely available. The determining factor for whether a feature is Newly or Widely available is if a given feature is fully implemented in all major browsers. This communicates to developers which features are safe to use—and that informs developers on whether they should use a polyfill.

Determine your Baseline threshold

The main advantage of Baseline is that it reduces the number of things you need to worry about in your developer workflow. If you decide to adopt anything that has passed the Widely available line without worrying about polyfills, that means the only features you need to consider the status of are those outside of that line. Baseline can then help you decide what to do with Newly available features.

A feature becomes Newly available when supported by all target browsers, but that doesn't automatically mean that you can use the feature on day one and expect that every browser used by every user supports it. Most browsers now update themselves, but it takes time for all users to receive those updates. One factor to consider is when a device's browser version is tied to its operating system version. In these cases, there's a point at which a given user can no longer receive operating system updates until they replace their device.

Baseline features are grouped in yearly sets—for example, Baseline 2025, Baseline 2024, and so on—until enough time passes in which those features become part of the Widely available set. By coupling this information with information about your users, you can now make informed decisions about whether to use a Newly available feature, or use it with a polyfill.

The best data source for determining a Baseline threshold is the one for your website. Tools in this space are evolving to include data for Baseline thresholds. RUMvision is a product that provides this information.

RUMvision's solution can show you how many users support web features. You can use it to search for distinct features to give you more data in your decisions on which ones to use.

In RUMvision's case, you can search not just for support of discrete features, but you can also see which percentage of users support a given Baseline feature set by year.

If you don't have RUM data for your site yet, RUM Insights gives you a broad view of the support of each Baseline feature set. One pattern you'll notice is that Baseline thresholds within the Widely available window are supported by 98% or more of all users, with the earliest thresholds achieving near 100% support by users.

How you determine feature support is your call, but generally speaking, the closer you get to 100% of users, the more confidence you can have that you can use Baseline web features without the need for a polyfill. As a general rule if 98% or 99% of users support a feature in their browser of choice, you can likely use the feature safely—but you still need to think about what that means for a minority of users.

When and when not polyfill a missing feature

The decision to use a polyfill is subjective, and it depends completely on your web application's requirements. However, knowing that there are potential user experience disadvantages to using them, you should strive to use as few of them as possible. Knowing whether a feature has reached Baseline Newly or Widely available should inform this decision.

Say you're looking to use a Baseline Newly available, but you have data that tells you that 95% of your users currently support the feature. This means that 5%—or one in every twenty users—will be using a browser that doesn't support the feature. This doesn't mean you should automatically reach for a polyfill, because whether you need a polyfill depends on the feature, and what the impact is if it's missing for a user.

While this can be a difficult call to make, it might help you to think about the potential negative user experience impacts that may result for users in browsers that don't support the feature you're looking to use, and whether those impacts warrant the use of a polyfill.

This evaluation criteria classifies features into three categories:

Enhancement: The feature enhances the user experience in a way that doesn't result in visual changes or reduced functionality if it's unsupported. If the feature is missing for a user, they'll likely not notice. You very likely don't need to polyfill these features if they're missing.
Additive: The feature provides an additive benefit that may impact how a web page looks or functions, but not in a way that surfaces serious problems. In fact, the user may not even notice unless they compare the same experience in a different browser that supports the feature. If a polyfill is available, lean towards not using it, especially if you're already polyfilling many other features, as adding additional polyfills will only worsen performance.
Critical: The feature provides necessary functionality that, if missing in the user's browser, will result in a broken experience due to JavaScript evaluation and runtime errors, broken layouts, and other unacceptable outcomes. In this case, you decide to polyfill the feature, or avoid using it and figure out a different workaround.

It can be tricky to figure out which features fall into which category, but here are some practical examples:

Good examples of enhancement features are those related to performance. Features such as fetchpriority, HTTP/3 and others can improve the performance of a page. This is good for improving the user experience, but if the user uses a browser that doesn't support them, they won't experience adverse or even noticeable effects in many cases. Product stakeholders may be okay with the overwhelming majority of users gaining a benefit, so long as the vast minority are not left out in the cold.
Examples of additive features are those that enhance the visual appeal of a page. Color spaces and functions and subgrid are good examples of additive features that users may not notice if they're missing. In this case, some project stakeholders may have concerns about brand integrity if such functionality is missing for some users, but could be convinced that adoption of such features is okay if the experience is not utterly broken.
Adoption of critical features are non-negotiable. One example of such a feature might be the HTML <datalist> element, which if absent, could create a suboptimal user experience. Expect that project stakeholders won't accept adoption of features that will break the user experience in some browsers.

Generally speaking, here's how you can evaluate which feature falls into which category by its Baseline status:

If a feature is Widely available you shouldn't reach for a polyfill—unless you have data about your users that explicitly tell you otherwise.
If a feature is Newly available it has a very good likelihood of being supported broadly, but user support data should be used to determine which Baseline threshold is best to adhere to to minimize nuisances or unacceptable outcomes, with the understanding that support will improve to nearly 100% over time.
If a feature is Limited availability it has the highest likelihood of creating a broken experience for some users, and therefore should be approached with caution, even if a polyfill is available.

Should I ever use Limited availability features?

The answer to this question is yes, but with some important caveats:

Baseline features that have Limited availability are never guaranteed to become Newly available and beyond. You must very carefully consider what this means for the user experience.
If you decide to adopt Limited availability features alongside polyfills, understand that you are passing on additional bytes to users unless you conditionally load those polyfills so that only those users who need them, get them. Even then, users who need them are still incurring a performance cost.
Beyond the performance cost, users who require polyfills for Limited availability features may experience issues if a polyfill for a feature can't faithfully replicate the functionality of its natively implemented equivalent. This can impact functionality, and in some cases, even accessibility.
Limited availability features are also subject to changes in their specified behavior. In particular, any feature only implemented in one browser may have to change when other browsers start to implement support. This means that your code, and any polyfill can fall out of sync with such changes.

Unless your users are locked to a single browser engine, using Baseline Newly and especially Widely available features is the recommended approach. Doing so means you will generally spend less time thinking about feature support, and more time using them, and spending the time you save on solving other problems.

Conclusion

The rules for whether or not you should use polyfills as you adopt web platform features aren't clear-cut. Like anything you do on the web, it requires careful thought while weighing benefits and risks. To review, a rough set of rules to approach the problem are:

Understand that while polyfills are advantageous in some ways, they represent potential performance and accessibility costs, and may be unable to faithfully replicate unimplemented web features.
Determine your Baseline threshold with data from your users, if possible. If that's not possible, the Baseline Widely available set of features is a good starting point, and consider using RUM insights data to make informed decisions.
With that data, assess how many users could be impacted if their browser doesn't support features you're looking to use, and assess the severity of that impact.
Communicate with project stakeholders to determine what features are acceptable and appropriate to use for your project's goals and business needs.
If you must use Limited availability features, assess your audience and the risk for using them. Unless your users are locked to using a single browser engine, you can't guarantee compatibility, even with a polyfill.

These reasons are why polyfills are not included as a part of Baseline. The role of Baseline is to inform you of which features are supported in all major browser engines. You'll still need to know how many of your users can use Baseline features, and make decisions based on your users and the needs of your project. Baseline Widely available is a good default, and will often have the broadest web feature support for users in many cases.

The web platform is maturing in its capabilities faster than ever before, and there is a growing opportunity to use more of it as more features become interoperable and more broadly supported as time passes. This will provide you with more opportunities to use more web platform features with less polyfills.

How to query the Web Platform Dashboard for Baseline tooling

Tue, 04 Mar 2025 08:00:00 GMT

Published: March 4, 2025

Baseline was originated by the Chrome team and is now defined by the WebDX Community Group. Baseline brings clarity to features that are interoperable between browsers. It's designed to help you identify what features you can use—or can't use—across all major browser engines. However, you need a way to identify what those features are.

Thankfully, you have the ability to query which features are Baseline Newly or Widely available using the Web Platform Dashboard—which is powered by the web-features npm package. You can also access this information using its HTTP API to integrate Baseline data into your tooling workflow, and this guide explains how.

The Web Platform Dashboard's relevant Baseline query grammar

The Web Platform dashboard uses a specific query grammar to help you search web feature support. You can use this query grammar directly on the dashboard itself.

A listing of features on the Web Platform Dashboard. The list is based on a search that shows only Baseline Newly available features using the baseline_status:newly search query.

As you type in the search box at the top of the page, you'll be presented with a number of query parameters you can use to filter web features.

The search box on the Web Platform Status Dashboard will reveal available query parameters as you type. In this case, the autocomplete suggests Baseline-related parameters to filter by Baseline status, or even a date range.

The query grammar is expressive, giving you a lot of flexibility in how to filter the web features that are displayed on the dashboard. The following screenshot shows how the id query parameter can be used to narrow down to a specific feature:

The id parameter in this example has a value of html, which indicates support for the <html> element, which is (unsurprisingly) Baseline Widely available.

The query grammar is documented—but knowing all of it is not required to find Baseline data for features. You can use any of these options on the dashboard, but here are some that are especially useful:

baseline_status: Use this parameter to filter features by three enumerated values:
- limited: Returns features that have limited browser support. If you filter by this value, you'll only receive features that have not reached any Baseline status.
- newly: Returns features that are Baseline Newly available.
- widely: Returns features that are Baseline Widely available, which are features that have been Baseline for at least 30 months. These are features that you can expect to use without worrying about browser support or polyfills.
baseline_date: Uses a YYYY-MM-DD..YYYY-MM-DD format to specify an upper and lower bound for when features reached Baseline. For example, to find all features in the span of a year, use a value like 2024-01-01..2025-01-01.
id: The identifier for a given feature. These identifiers are defined in the web-features package. For example, the feature entry for Promise.try() maps to an ID of promise-try.
group: One of many enumerated group names for features. This is useful criteria if you only want to query for a certain subset of web platform features. For example, you could filter to a list of CSS features with a value of css.

While the dashboard frontend is certainly useful, it rests on top of an HTTP API that you can query directly. For example, here's an endpoint that gets all Baseline features that are Newly available:

https://api.webstatus.dev/v1/features?q=baseline_status:newly

Note: There are also logical query modifiers, such as AND and OR keywords, or negation using the - operator. Consult the full querying documentation for more information.

The JSON response structure

The JSON response you receive from the HTTP API has a consistent shape for every feature. The response returned contains a data property at the top level. This property contains an array of all matching features. While this isn't exhaustive list of all the fields available in the JSON response, here are some useful ones when it comes to Baseline:

baseline: Contains general information about the Baseline status of a given feature, with the following subfields:
- status: The Baseline status for a feature. Values can be either limited, newly, or widely. Note: this will be the only subfield if status has a value of limited.
- low_date: This indicates the date on which the given feature became Baseline Newly available. This field only appears if status is either newly or widely.
- high_date: This indicates the date on which the given feature became Baseline Widely available. This field is only available if status is widely.
feature_id: The ID for the feature. For example, for CSS grid, this would be a value of "grid".
name: The formatted name of the feature. This can be similar to feature_id in some cases, but is usually different. For example, the feature_id value for Promise.try() is "promise-try", whereas the name field for the same feature is "Promise.try()".
spec: This field contains a subfield named links, which is an array of links to specifications and other resources.

There are other fields, often containing information about when specific supporting browsers implemented the feature at which version, data about Web Platform Tests, and other things you may or may not care about.

Example queries

Now that you have a quick explanation of some of the available query parameters, take a look at some example queries that you can use in your tools and scripts to select web status features that could be useful for your workflow.

Get data for a single feature

A good way to get familiar with the API is to start with a basic example that gets data for a single web feature.

// Specify and encode the query for a query string:
const query = encodeURIComponent('id:grid');

// Construct the URL:
let url = `https://api.webstatus.dev/v1/features?q=${query}`;

// Fetch the resource:
const response = await fetch(url);

if (response.ok) {
  // Convert the response to JSON:
  const { data } = await response.json();

  // Log data for each feature to the:
  console.log(data);
}

In this case, we specify an id parameter with a value of grid to get feature support information for CSS grid, which is Baseline Widely available. You could use this information, for example, to detect usage of the feature and let users know that they can use it in all modern browser engines without worrying about support.

This is just a start, though, and the HTTP API can do much more for you than get data for a single feature.

Get all Baseline Newly and Widely available features

Say you'd like to have a script that pulls in all features that are either Baseline Newly or Widely available. This could be useful, for example, if you have a script that runs on some interval and you'd like to get an updated list that changes as features emerge from limited availability to either Baseline status:

const query = encodeURIComponent('-baseline_status:limited');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Note: Take notice of the use of -baseline_status:limited for the query. This excludes any feature with a status of limited. An equivalent query would be baseline_status:newly AND baseline_status:widely.

This query doesn't get all Baseline Newly and Widely available features, but only the first 100. If the number of features retrieved exceeds this, there is a metadata field at the top level of the JSON response that can contain up to two subfields:

next_page_token: A string containing a token you can add to the query string of the GET request to the backend. When you use it and re-fetch data from the webstatus.dev backend, it will return the next batch of matching features. Note: This field will be unavailable if the current query returns less than 100 results, or if the current query is at the end of the result set.
total: An integer indicating the total number of features available for the current query.

These fields are useful for pagination. With them, we can try the following code to get all of the results for a query that returns a large amount of data:

async function queryWebStatusDashboard (query, token) {
  const urlBase = 'https://api.webstatus.dev/v1/features?q=';
  let queryUrl = `${urlBase}${encodeURIComponent(query)}`;

  if (token) {
    queryUrl += `&page_token=${encodeURIComponent(token)}`;
  }

  const response = await fetch(queryUrl);

  if (response.ok) {
    const { data, metadata } = await response.json();

    console.log(data);

    // See if there's a page token in this query:
    if ('next_page_token' in metadata) {
      const { next_page_token } = metadata;
      queryWebStatusDashboard(query, next_page_token);
    } else {
      console.log('All results collected');
    }
  }
}

// Make the first query, and if there are more
// than 100 entries, the function will run
// recursively until all features are fetched
queryWebStatusDashboard('-baseline_status:limited');

Get all Baseline Newly available CSS features

Say you're an engineer with a special focus on CSS, and you're interested to know which CSS features become Baseline Newly available features. This is a perfect use case for the group query value, as well as how to use the AND operator when querying webstatus.dev:

const query = encodeURIComponent('baseline_status:newly AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

When specifying a value of css for group, you can query for all Baseline Newly available features. If you wanted to expand the scope to include Baseline Widely available CSS features as well, you could use the approach from the last code sample and use the negation operator with a query such as -baseline_status:limited AND group:css'.

Note: For an enumerated list of all possible group values, consult the web-features GitHub repository.

Another field you can query is the snapshot field, which is useful for finding JavaScript features that are part of a specific set of ECMAScript features. The following code checks for all Baseline Newly available features that are part of the ecmascript-2023 snapshot:

const query = encodeURIComponent('baseline_status:newly AND snapshot:ecmascript-2023');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

Get all Baseline features within a date range

The baseline_date field can be queried to find all features that became Baseline within a specific date range:

const query = encodeURIComponent('baseline_status:widely AND baseline_date:2022-01-01..2022-12-31 AND group:css');
let url = `https://api.webstatus.dev/v1/features?q=${query}`;
const response = await fetch(url);

if (response.ok) {
  const { data } = await response.json();

  console.log(data);
}

The preceding code sample will query for CSS features that became Baseline Widely available at any point in 2022. The query syntax for baseline_date lets you specify a beginning and ending date, separated by ...

Conclusion

The queries in this guide are meant to be a starting point for you to begin experimenting with how to query the webstatus.dev backend. With any number of available query parameters, you should be able to get results that are specific to your application.

Knowing how to query the Web Platform Dashboard's HTTP API gives you the ability to build tools that might be useful for your work, and keep you informed as to whether the features you want to use for your project have broad enough browser support. This means you can build web applications using modern browser features that you can safely use, providing a much more enjoyable developer experience.

Core Web Vitals workflows with Google tools

Fri, 28 Feb 2025 08:00:00 GMT

Combine Google tools to audit, improve and monitor your website effectively.

Published: May 28, 2020

Core Web Vitals are a set of metrics that assess the user experience on criteria such as load performance, responsiveness to user input, and layout stability.

A workflow for improving Core Web Vitals for your website will be explored in this guide, but where that workflow begins depends on whether you're collecting your own field data. Where it ends may depend on which of Google's tools you'll find useful in diagnosing and fixing user experience problems.

Core Web Vitals are best measured in the field

Core Web Vitals are specifically designed to measure how users experience your website—they are user centric metrics. Lab-based tools such as Lighthouse are diagnostic tools to highlight potential performance problems and best practices. Lab-based tools are run under certain, predefined conditions and may not reflect the real-life Core Web Vitals measurements your users experience.

For example, Lighthouse is a lab-based tool that runs tests with simulated throttling in a simulated desktop or mobile environment. While such simulations of slower network and device conditions are helpful when trying to diagnose performance problems, they're just a single slice of the large variety in network conditions and device capabilities, and so may not reflect what users on your sites are experiening.

Lab-based tools like Lighthouse also typically do a "cold load" of a web page as a totally new visitor. This is often the slowest load, but in real life, visitors may have some assets cached if they have visited before, or when they are browsing around the site. New visitors, and tools, also may experience the site differently with cookie banners or other content present to them.

In short, while lab-based tools can give an indication of potential performance problems and help you debug and iterate, they may not represent how many of your visitors actually experience your website. Use field data for measuring real-world performance, and lab-based tools like Lighthouse for diagnostics of how to improve it. See also the When to use Lighthouse section.

Google measures Core Web Vitals through the Chrome User Experience Report (CrUX). This is a public dataset collected from real Chrome users. It is the backbone of many Google and third-party tools which report a site's Core Web Vitals.

CrUX has its limitations, though. It can often tell you when there is a problem, but often has insufficient data to tell you why.

Collect your own field data if possible

The best dataset for improving website performance in the field is the one you build. That starts with collecting field data from your website's visitors. How you do this depends on the size of your organization, and whether you want to pay for a third-party solution or create your own.

Paid solutions will almost certainly measure Core Web Vitals (and other performance metrics) and usually provide a variety of tools to dig into the resulting data. In large organizations with significant resources, this may be the preferred method.

However, you may not be part of a large organization—or even one with the means to afford a third-party solution. In these cases, Google's web-vitals library will help you gather all Web Vitals. However, you'll be responsible for how that data is reported, stored, and analyzed.

If you're already using Google Analytics, but you haven't started collecting your own field data, there may be an opportunity for you to use the web-vitals library to send Web Vitals collected in the field to Google Analytics and use the BigQuery exports of GA4 to report on the data.

Understand Google's tools

Regardless of whether you're collecting your own field data, there are several Google tools that may be useful in analyzing Core Web Vitals. Before establishing a workflow, a high-level overview of each tool can help you to understand which tools may—or may not—be best for you.

Chrome User Experience Report (CrUX)

As mentioned previously, CrUX is a public dataset of field data gathered from a segment of real Google Chrome users from millions of websites. It includes Core Web Vital metrics and other metrics for websites with sufficient traffic.

CrUX is available as a monthly BigQuery dataset at the origin level, or as a daily API at the URL or origin-level, provided a URL or origin has enough samples in the CrUX dataset. The CrUX data is available through various CrUX tools for both programmatic access and visual tools for use by uses.

When to use CrUX

Even if you gather your own field data, CrUX is still useful. Though CrUX represents a subset of Chrome users, it's helpful to compare your website's field data to see how it aligns with its CrUX data. There are advantages and disadvantages to each, which can result in differences. If you don't gather any field data for your website, CrUX is especially valuable to provide a high-level overview—provided your website is represented in its dataset.

You can use CrUX directly, or using another tool (including those mentioned below). Using the CrUX dataset directly, either using BigQuery or the API, is useful to expose data that is not shown in other tools—for example country-level data is often not available on other tools, or to view the additional metrics in CrUX which again are often not surfaced in other tooling.

When not to use CrUX

CrUX only represents Chrome users, and even then, only a subset of Chrome users. A full RUM solution can include more experiences across Chrome and other browsers where they support the Web Vital metrics.

Websites that don't receive enough traffic are not represented in the CrUX dataset. If this is the case for you, you'll need to gather your own field data to understand how your website performs in the field, as CrUX won't be an option. Alternatively, you will need to depend on lab data, but with the limitations that it may not be representative as described previously.

Since the data CrUX provides is a rolling average over the previous 28 days, it's not an ideal tool during development, as it will take a fair amount of time for improvements to be reflected in the CrUX dataset.

Finally, as a public dataset, CrUX is limited to how much information it can make available, and how this data can be queried. Capturing your own RUM data lets you gather more details (for example, the LCP element), and segment the data more to identify problems. Do logged in users experience better or worse Core Web Vitals than logged out users? Do users with a slow LCP have a particular LCP element? Which interactions are causing high FID and INP values?

PageSpeed Insights (PSI)

PSI is a tool that reports field data from CrUX and lab from Lighthouse for a given page. See those individual sections for more details.

When to use PSI

PSI is great for assessing CrUX performance at the page level or origin-level, for both mobile and desktop users. It's a good choice for an initial overview of Core Web Vitals for a page or site. It also lets you view Core Web Vitals data for other sites like competitors.

PSI also provides Lighthouse data, which gives useful recommendations to improve your Core Web Vitals—if the metrics align. Where these don't align, Lighthouse recommendations may be less relevant.

Since Lighthouse is run from the server, it can form a more consistent baseline than running Lighthouse from DevTools.

When not to use PSI

PSI is only available for public URLs. It cannot be used on development sites that are not publicly accessible.

CrUX data is only available when sites meet certain eligibility criteria, including site popularity thresholds. PSI is less useful when CrUX data is not available for a page or origin as it can only show the Lighthouse lab data in these cases.

Similarly, if you only have origin-level CrUX data rather than the specific URL being tested, then this also limits its usefulness of correlating the origin-level field data to the page-level lab diagnostics. Having the origin-level field data is still very useful information to have as a summary of the site's performance and the Lighthouse audits may help, but extra caution should be used in this case.

Finally, where page-level data is available in CrUX, but differs from the Lighthouse lab data, recommendations from Lighthouse may be of limited value. This can happen particularly for post-load CLS issues, and for interactivity Core Web Vitals (FID and INP) where lab-based audits are less useful.

Search Console

Search Console measures your site's search traffic and performance, including Core Web Vitals. It is only available to site owners who have confirmed their ownership of the site.

A valuable feature of Search Console is that it groups similar pages (for example, pages that use the same template) into a single group assessment. Search Console also includes a Core Web Vitals report based on field data from CrUX.

When to use Search Console

Search Console is well-suited for both developers and those in non-developer roles to assess both search and page performance in ways other Google tools don't. Its presentation of CrUX data and grouping of pages by similarity offers novel insight into how performance improvements impact entire categories of pages.

When not to use Search Console

Search Console may not be a fit for projects that use different third-party tools which group pages by similarity, or if a website isn't represented in the CrUX dataset.

Page grouping can also be somewhat confusing when the example pages in a group have different characteristics than the rest of the group—for example, if the group fails particular Core Web Vitals overall, but the example pages all seem to pass the same Core Web Vitals. This can happen when a group contains a long tail or seldomly visited pages that may be slower to load, as they're less likely to be cached. When there are sufficient volumes of these pages in the long tail, they can influence the group's overall pass rate.

Lighthouse

Lighthouse is a lab tool that provides specific opportunities for improving page performance. Lighthouse user flows also allow developers to script interaction flows for performance testing beyond page load.

Lighthouse-CI is a related tool that runs Lighthouse during project builds and deploys to assist with performance regression testing. It presents a Lighthouse report along with pull requests, and tracks performance metrics over time.

When to use Lighthouse

Lighthouse is excellent for finding performance improvement opportunities during development in both local and staging environments. Lighthouse CI is similarly useful in the build and deploy phases to staging and production environments, where performance regression testing is needed to preserve good user experiences.

When not to use Lighthouse

Lighthouse (or Lighthouse CI) is not a substitute for field data. Lighthouse is primarily a diagnostic tool listing potential issues and best practices from a predefined page load. The recommendations it surfaces may not always match the performance experienced by your users.

While Lighthouse can be used to diagnose production sites through tools like PageSpeed Insights, Lighthouse would ideally be used in development and continuous integration environments to address performance issues before they reach production.

The audits that Lighthouse provides are also available through "insights" in the Performance panel in Chrome DevTools, which provides a more in-depth analysis of a page's performance.

The Performance panel in Chrome DevTools

Chrome DevTools is a collection of in-browser development tools, including the Performance panel. The Performance panel is a lab tool that consists of two "modes":

When the Performance panel is first opened a Live Metrics screen provides current Core Web Vitals metric, with the ability to import field data from CrUX. It is useful as a "live" view of performance as you interact with the page to attempt to uncover performance issues—particularly for post-load issues you might see with the CLS and INP metrics.

Secondly, the Performance panel allows developers to capture a profile (or trace) of all page activity during page load or a recorded time period. This view offers deep insight into everything it observes across dimensions such as network, rendering, painting, and scripting activity, as well as a page's Core Web Vitals. It also includes insights, similar to those provided by Lighthouse.

When to use the Performance panel

The Performance panel should be used by developers to gain deep insight into a particular page performance.

The live metrics view can be used to quickly understand the current performance characteristics of the page, and also spot potential problems as the page is interacted with.

The trace view is particularly useful to debug responsiveness issues affecting INP. Once a poorly responding interaction is identified and repeatable, the Performance panel can provide a wealth of data as to what is going on in the browser to help understand the issue, from main thread blocking, to JavaScript call stacks, to rendering work.

When not to use the Performance panel

The Performance panel is a developer tool that primarily provides lab data—though with some field context from CrUX. It's not a substitute for field data.

The trace view contains a lot of debugging information, but because of that, it can be difficult to understand for novice developers or those in non-developer roles. However the live metrics view that the panel opens with, addresses this by providing an easier to use interface for those not requiring the full detail.

A three step workflow for ensuring your website's Core Web Vitals stay healthy

When working to improve the user experience, it's best to think of the process as a continuous cycle. For improving Core Web Vitals and other performance metrics, one approach could be:

Evaluate website health and identify pain points.
Debug and optimize.
Monitor with continuous integration tools to catch and prevent regressions.

Three step workflow

Step 1: Evaluate website health and identify opportunities for improvement

It is best to start with field data to evaluate website health.

Use PageSpeed Insights to view overall Core Web Vitals experience metrics on the origin, and specific information on an individual URL.
Search Console can be useful to identify pages which need improvement where its page grouping feature works well for your site.
If you have RUM data, then that is often the best option to be able to identify particular pages or traffic segments with issues.

Whether you analyze field data you collect yourself or CrUX data, this first step is vital. If you're not gathering field data, CrUX data may be enough to guide you—again, provided your website is represented in the dataset.

Analyze site performance with PageSpeed Insights

PageSpeed Insights displays the CrUX data covering the last 28 days of user experience data at the 75th percentile. This means that if 75% of user experiences meet the threshold set for a given metric, then the experience is considered "good".

If you have a specific page in mind to look at the performance of, then use that. For an overall view of a site when you first start optimizing, you may want to start with the home page, as it is typically one of the most popular pages on many sites.

Concentrate on the what your real users are experiencing section of PSI initially. You will see up to four views of the data: mobile and desktop for the URL entered and the whole origin. Compare these and see how they differ. Mobile is typically less performant than desktop since it is a more resource-constrained device operating under potentially less stable network conditions. If the URL and origin data are significantly different, then try to understand why: home pages are often the first pages visited (that is, a landing page) so can be slower than the origin users take the full brunt of an unprimed browser cache. Subsequent pages will likely load faster, as any shared assets will be cached, bringing down the aggregate origin-level data.

PSI also shows all three Core Web Vitals (LCP, CLS, and INP) plus the diagnostic TTFB and FCP metrics. Are any of the Core Web Vitals failing, and by how much? This will indicate where to concentrate your efforts.

Understand the relationships between these numbers—particularly for LCP. If LCP is slow, as it is in this example, then look at TTFB and FCP which are both milestones to that metric. In this example we have a 1.8 second TTFB, which is going to make it very tough to meet the 2.5 second recommended threshold for good LCP. This suggests either a slow backend (server issues or a lack of CDN), slower networks, or redirects delaying the first HTML bytes. Look at the Optimize TTFB guide for more information. FCP takes another second on top of that, which again may be indicative of slower networks. LCP is not long after FCP in this example suggesting the LCP resource is well optimized once the page itself loads. CrUX also now shows more diagnostic information in resource types and subparts, which also helps you diagnose LCP issues.

For CLS, look at the CrUX CLS and the Lighthouse CLS scores to see if this is a load CLS issue (which Lighthouse will catch and advise on), or a post-load CLS issue that Lighthouse won't catch. More for information see the Optimize CLS guide.

For responsiveness, look at the INP scores. Look at the TBT audits in Lighthouse to see if a lot of JavaScript processing is happening during the initial page load, which is likely to impact INP. INP can be a tricky metric to improve, so consult the Optimize INP guide for more information.

Identify poorly performing pages in Search Console

While PSI is useful when you have a specific URL you want to test or the site as a whole, Search Console can help target your efforts to particular types of pages. This is particularly useful if many pages share common themes or technologies and Search Console can successfully identify these.

The Core Web Vitals report in Search Console shows the big picture of your website's performance, but you can still drill down into specific pages that need attention. With Search Console, you can also:

Identify individual page groups that need improvement, and those that provide a good user experience.
Get granular data on performance by URL grouped by status, metric, and groups of similar web pages (such as product detail pages on an ecommerce website).
Get detailed reports that bucket URLs in each user experience quality category for both mobile and desktop.

Once you have some specific pages to look at, you can use PSI as explained previously to gather further understanding of the issues for those pages.

Step 2: Debug and optimize

In step 1, you should have identified pages which require performance improvements, and also which of the Core Web Vitals metrics you want to improve. You can use the Google tooling to get further information to understand the root cause to identify the issue.

Look at Lighthouse audits get high-level guidance for the page
Use the Performance panel live metrics view to analyze Core Web Vitals in real time.
Use the Performance panel tracing to debug performance issues and test code changes.

For more detailed guidance, see these guides:

Uncover opportunities with Lighthouse

PageSpeed Insights runs Lighthouse for you. It is also possible to run Lighthouse from Chrome DevTools, which is useful to validate fixes locally, though the Peformance Panel (covered next) is a more comprehensive tools for identifying and fixing performance issues locally.

A key point is to validate that the Lighthouse audit replicates the issues you are trying to solve (for example, slow LCP, or CLS issues). Out of the box, Lighthouse only assesses the user experience during page load. Since it's a lab tool, it also excludes INP in favor of TBT.

When the Lighthouse metrics suggest a similar problem as the one you are trying to solve, the wealth of information in its audits can help identify issues and suggest solutions.

You can filter the audits to just the Core Web Vitals you are interested in to focus on fixes for issues related to a specific metric:

Lighthouse filter options

For INP, use the TBT audits to identify issues that can potentially affect those metrics, but be aware that without interactions, Lighthouse is limited in how much it can diagnose.

Analyze in real time with the Chrome DevTools live metrics screen

The Chrome DevTools live metrics screen in the Performance panel shows Core Web Vitals in real time during page load and while browsing a page. Because of this, it can capture INP as well as layout shifts that occur after load. It is also possible to see more detailed information on each metric:

Live metrics view in Chrome DevTools Performance panel

This view gives a lot of helpful information to help identify performance issues, and can even pull in field information from CrUX. For even more information you can drill down with a trace.

Drill down with the Performance panel

The Performance panel in Chrome DevTools lets you record a profile (or trace) of all page behavior during a recorded period of time.

Chrome DevTools Performance Panel trace

Performance insights are available in the Insights side panel. This also shows the Core Web Vital metrics along with the field values for those when available.

The Layout Shifts track highlights layout shifts and clicking on these provides more details about the elements that shifted for debugging CLS.

Key timings—such as LCP—are shown in the Timings available at the bottom of the trace. Click these for more details.

Long Tasks (that can lead to INP issues) are also highlighted with red triangles in the flame chart.

These features—as well as information in other parts of the Performance panel—can help you determine whether fixes are having any effect on a page's Core Web Vitals.

Debug Core Web Vitals in the field

Lab tools can't always identify the cause of all Core Web Vitals issues affecting your users. This is one reason why it's so important to collect your own field data, as it takes factors into account that lab data cannot.

See debug performance in the field for more information.

Step 3: Monitor for changes

Google's tools for monitoring changes

Once you have fixed any issues, you want to ensure they have the required effect and that new issues don't disrupt your Core Web Vitals. This requires monitoring for performance issues as part of developer workflow to prevent performance issues being released to production, and monitoring the field data regularly to ensure this is the case.

Monitor for performance requisitions in Continuous Integration (CI) environments

Lighthouse-CI lets you automatically run Lighthouse audits on code commits to prevent performance regressions entering code. This can check performance timings (which are subject to variability), or for just the performance audits, as a linting tool to prevent bad practices in the code.

View website health trends with field data

While you should aim to catch and fix all performance issues before they make it to production, monitoring your field data using RUM is essential to find any that slip through. There are many commercial RUM products available that can help with this. The web-vitals JavaScript library can automate a website's field data collection, and optionally use this data to power custom dashboards and alerting systems.

For sites without a RUM solution, you can use the various CrUX tools as a basic trend analysis of field data.

Conclusion

Ensuring fast and delightful user experiences requires a performance-first mindset and adoption of a workflow to ensure progress. With the right tools and processes to audit, debug, and monitor, building great user experiences and staying within the thresholds defined for good Core Web Vitals is within your reach.

ruby-align is Baseline Newly available

Fri, 21 Feb 2025 08:00:00 GMT

Published: Feb 21, 2025

The HTML <ruby> element lets you display phonetic annotations or other supplemental information above or beside base text. It is commonly used in East Asian languages.

A <ruby> element consists of two main parts, ruby base which is the main text and ruby text which is the annotation text, marked up with the <rt> element.


<ruby>
  絵文字
  <rt>emoji</rt>
</ruby>

English pronunciation as an annotation over Japanese base text.

`ruby-align`

The ruby-align CSS property controls the alignment of ruby base text and ruby annotation text. The property accepts one of the keyword values, space-around, space-between, start, and center.

Image showing use-case for ruby-align property.

Prefetch resources to speed up future navigations

Sat, 08 Feb 2025 08:00:00 GMT

Learn about rel=prefetch resource hint and how to use it.

Published: Sep 12, 2019, Last updated: Feb 8, 2025

Research shows that faster load times result in higher conversion rates and better user experiences. If you have insight into how users move through your website and which pages they will likely visit next, you can improve load times of future navigations by downloading the resources for those pages ahead of time.

This guide explains how to achieve that with <link rel=prefetch> that lets you implement prefetching in an efficient way.

Improve site performance with `rel=prefetch`

Adding <link rel=prefetch> to a web page tells the browser to download some of the resources (like scripts or CSS files), that the user might need in the future:

<link rel="prefetch" href="/css/styles.css">

The prefetch hint consumes extra bytes for resources that are not immediately needed, so this technique needs to be applied thoughtfully; only prefetch resources when you are confident that users will need them. Consider not prefetching when users are on slow connections. You can detect that with the Network Information API.

Use cases

Prefetch has many use cases to speed up web pages by downloading resources in advance.

Prefetch subsequent pages

Prefetch HTML documents when subsequent pages are predictable, so that when a link is clicked, the page is loaded instantly.

For example, in a product listing page, you can prefetch the page for the most popular product in the list. In some cases, the next navigation is even easier to anticipate—on a shopping cart page, the likelihood of a user visiting the checkout page is usually high which makes it a good candidate for prefetching.

While prefetching resources does use additional bandwidth, it can improve most performance metrics. Time to First Byte (TTFB) will often be much lower, as the document request results in a cache hit. Because TTFB will be lower, subsequent time-based metrics will often be lower as well, including Largest Contentful Paint (LCP) and First Contentful Paint (FCP).

Prefetch static assets

Prefetch static assets, like scripts or stylesheets, when subsequent sections the user might visit can be predicted. This is especially useful when those assets are shared across many pages.

For example, Netflix takes advantage of the time users spend on logged-out pages, to prefetch React, which will be used once users sign in. Thanks to this, they reduced Time to Interactive by 30% for future navigations.

At the time of this writing, it is possible to share prefetched resources among pages served from different origins. When Double-keyed HTTP cache ships, this will only work for top-level navigations and same-origin subresources, but it won't be possible to reuse prefetched subresources among different origins. This means that, if a.com prefetches the resource b.com/library.js, it won't be available in c.com cache. Some browsers, such as WebKit-based ones, already partition caches and HTML5 storage for all third-party domains.

The effect of prefetching static assets on performance metrics depends on the resource being prefetched:

Prefetching images can significantly lower LCP times for LCP image elements.
Prefetching stylesheets can improve both FCP and LCP, as the network time to download the style sheet will be eliminated. Since stylesheets are render blocking, they can reduce LCP when prefetched. In cases where the subsequent page's LCP element is a CSS background image requested using the background-image property, the image will also be prefetched as a dependent resource of the prefetched style sheet.
Prefetching JavaScript will allow the processing of the prefetched script to occur much sooner than if it were required to be fetched by the network first during navigation. This can have an effect on a page's Interaction to Next Paint (INP). In cases where markup is rendered on the client using JavaScript, LCP can be improved through reduced resource load delays, and client-side rendering of markup containing a page's LCP element can occur sooner.
Prefetching web fonts that are not already used by the current page, can eliminate layout shifts. In cases where font-display: swap; is used, the swap period for the font is eliminated, resulting in faster rendering of the text and eliminating layout shifts. If a future page uses the prefetched font and the page's LCP element is a block of text using a web font, LCP for that element will also be faster.

Prefetch on-demand JavaScript chunks

Code-splitting your JavaScript bundles lets you initially load only parts of an app and lazy-load the rest. If you're using this technique, you can apply prefetch to routes or components that are not immediately necessary but will likely be requested soon.

For example, if you have a page that contains a button that opens a dialog which contains an emoji picker, you can divide it into three JavaScript chunks—home, dialog and picker. Home and dialog could be initially loaded, while the picker could be loaded on-demand. Tools like webpack allow you to instruct the browser to prefetch these on-demand chunks.

How to implement `rel=prefetch`

The simplest way to implement prefetch is adding a <link> tag to the <head> of the document:

<head>
  ...
  <link rel="prefetch" href="//css/styles.css">
  ...
</head>

You can also initiate prefetching with the Link HTTP header:

Link: </css/style.css>; rel=prefetch

A benefit of specifying a prefetch hint in the HTTP Header is that the browser doesn't need to parse the document to find the resource hint, which can offer small improvements in some cases.

Note: prefetch is supported in all modern browsers except Safari. You can implement a fallback technique for Safari with XHR requests or the Fetch API.

Prefetch JavaScript modules with webpack magic comments

webpack lets you prefetch scripts for routes or functions you're reasonably certain users will visit or use soon.

The following code snippet lazy-loads a sorting function from the lodash library to sort a group of numbers that will be submitted by a form:

form.addEventListener("submit", e => {
  e.preventDefault()
  import('lodash.sortby')
    .then(module => module.default)
    .then(sortInput())
    .catch(err => { alert(err) });
});

Instead of waiting for the 'submit' event to take place to load this function, you can prefetch this resource to increase the chances of having it available in the cache by the time the user submits the form. webpack allows that using the magic comments inside import():

form.addEventListener("submit", e => {
   e.preventDefault()
   import(/* webpackPrefetch: true */ 'lodash.sortby')
         .then(module => module.default)
         .then(sortInput())
         .catch(err => { alert(err) });
});

This tells webpack to inject the <link rel="prefetch"> tag into the HTML document:

<link rel="prefetch" href="1.bundle.js">

The performance benefits of prefetching on-demand chunks is a bit nuanced, but generally speaking, you could expect to see faster responses to interactions which depend on those on-demand chunks, as they will be immediately available. Depending on the nature of the interaction, this could impart a benefit to a page's INP.

Prefetching in general also factors into overall resource prioritization. When a resource is prefetched, it is done so at the lowest possible priority. Thus, any prefetched resources won't contend for bandwidth for resources needed by the current page.

Smart prefetching with quicklink and Guess.js

You can also implement smarter prefetching with libraries that use prefetch under the hood:

quicklink uses Intersection Observer API to detect when links come into the viewport and prefetches linked resources during idle time. Bonus: quicklink weighs less than 1 KB!
Guess.js uses analytics reports to build a predictive model that is used to smartly prefetch only what the user is likely to need.

Both quicklink and Guess.js use the Network Information API to avoid prefetching if a user is on a slow network or has Save-Data turned on.

Prefetch under the hood

Resource hints are not mandatory instructions and it's up to the browser to decide if, and when, they get executed.

You can use prefetch multiple times in the same page. The browser queues up all hints and requests each resource when it's idle. In Chrome, if a prefetch has not finished loading and the user navigates to the destined prefetch resource, the in-flight load is picked up as the navigation by the browser (other browser vendors might implement this differently).

Prefetching takes place at the 'Lowest' priority, so prefetched resources don't compete for bandwidth with the resources required in the current page.

Prefetched files are stored in the HTTP Cache if the resource is cacheable, otherwise it will be discarded and not be used.

Conclusion

Using prefetch can greatly improve web performance of a site by downloading future needed resources in advance. prefetch is supported in most modern browsers. This technique requires loading extra bytes that might not be used, so be mindful when you use it; only do it when necessary, and ideally, only on fast networks.

Debug layout shifts

Fri, 07 Feb 2025 08:00:00 GMT

Learn how to identify and fix layout shifts.

Published: Mar 11, 2021, Last updated: Feb 7, 2025

The first part of this article discusses tooling for debugging layout shifts, while the second part discusses the thought process to use when identifying the cause of a layout shift.

Tooling

You can debug Layout Shifts using the Layout Instability API, or with tooling like DevTools that summarizes data from this API in a more easily digestible format.

Layout Instability API

The Layout Instability API is the browser mechanism for measuring and reporting layout shifts. All tools for debugging layout shifts, including DevTools, are ultimately built upon the Layout Instability API. However, using the Layout Instability API directly is a powerful debugging tool due to its flexibility.

Usage

The same code snippet that measures Cumulative Layout Shift (CLS) can also serve to debug layout shifts. The following snippet logs information about layout shifts to the console. Inspecting this log will provide you information about when, where, and how a layout shift occurred.

let cls = 0;
new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    if (!entry.hadRecentInput) {
      cls += entry.value;
      console.log('Current CLS value:', cls, entry);
    }
  }
}).observe({type: 'layout-shift', buffered: true});

When running this script be aware that:

The buffered: true option indicates that the PerformanceObserver should check the browser's performance entry buffer for performance entries that were created before the observer's initialization. As a result, the PerformanceObserver will report layout shifts that happened both before and after it was initialized. Keep this in mind when inspecting the console logs. An initial glut of layout shifts can reflect a reporting backlog, rather than the sudden occurrence of numerous layout shifts.
To avoid impacting performance, the PerformanceObserver waits until the main thread is idle to report on layout shifts. As a result, depending on how busy the main thread is, there may be a slight delay between when a layout shift occurs and when it is logged in the console.
This script ignores layout shifts that occurred within 500 ms of user input and therefore don't count towards CLS.

Information about layout shifts is reported using a combination of two APIs: the LayoutShift and LayoutShiftAttribution interfaces. Each of these interfaces are explained in more detail in the following sections.

LayoutShift

Each layout shift is reported using the LayoutShift interface. The contents of an entry look like this:

duration: 0
entryType: "layout-shift"
hadRecentInput: false
lastInputTime: 0
name: ""
sources: (3) [LayoutShiftAttribution, LayoutShiftAttribution, LayoutShiftAttribution]
startTime: 11317.934999999125
value: 0.17508567530168798

The previous entry indicates a layout shift during which three DOM elements changed position. The layout shift score of this particular layout shift was 0.175.

These are the properties of a LayoutShift instance that are most relevant to debugging layout shifts:

Property	Description
`sources`	The `sources` property lists the DOM elements that moved during the layout shift. This array can contain up to five sources. In the event that there are more than five elements impacted by the layout shift, the five largest (as measured by impact on layout stability) sources of layout shift are reported. This information is reported using the LayoutShiftAttribution interface (explained in more detail below).
`value`	The `value` property reports the layout shift score for a particular layout shift.
`hadRecentInput`	The `hadRecentInput` property indicates whether a layout shift occurred within 500 milliseconds of user input.
`startTime`	The `startTime` property indicates when a layout shift occurred. `startTime` is indicated in milliseconds and is measured relative to the time that the page load was initiated.
`duration`	The `duration` property will always be set to `0`. This property is inherited from the `PerformanceEntry` interface (the `LayoutShift` interface extends the `PerformanceEntry` interface). However, the concept of duration does not apply to layout shift events, so it is set to `0`. For information on the `PerformanceEntry` interface, refer to the spec.

LayoutShiftAttribution

The LayoutShiftAttribution interface describes a single shift of a single DOM element. If multiple elements shift during a layout shift, the sources property contains multiple entries.

For example, the following JSON corresponds to a layout shift with one source: the downward shift of the <div id='banner'> DOM element from y: 76 to y:246.

// ...
  "sources": [
    {
      "node": "div#banner",
      "previousRect": {
        "x": 311,
        "y": 76,
        "width": 4,
        "height": 18,
        "top": 76,
        "right": 315,
        "bottom": 94,
        "left": 311
      },
      "currentRect": {
        "x": 311,
        "y": 246,
        "width": 4,
        "height": 18,
        "top": 246,
        "right": 315,
        "bottom": 264,
        "left": 311
      }
    }
  ]

The node property identifies the HTML element that shifted. Hovering on this property in DevTools highlights the corresponding page element.

The previousRect and currentRect properties report the size and position of the node.

The x and y coordinates report the x-coordinate and y-coordinate respectively of the top-left corner of the element
The width and height properties report the width and height respectively of the element.
The top, right, bottom, and left properties report the x or y coordinate values corresponding to the given edge of the element. In other words, the value of top is equal to y; the value of bottom is equal to y+height.

If all properties of previousRect are set to 0 this means that the element has shifted into view. If all properties of currentRect are set to 0 this means that the element has shifted out of view.

Caution: Layout Instability API does not ignore elements that shifted but were not visible due to another element being positioned in front of them. Use display: none, visibility: hidden, or opacity: 0 to avoid layout shifts in cases where you need to run layout on some elements before you make them visible to the user.

One of the most important things to understand when interpreting these outputs is that elements listed as sources are the elements that shifted during the layout shift. However, it's possible that these elements are only indirectly related to the "root cause" of layout instability. Here are a few examples.

Example #1

This layout shift would be reported with one source: element B. However, the root cause of this layout shift is the change in size of element A.

Example #2

The layout shift in this example would be reported with two sources: element A and element B. The root cause of this layout shift is the change in position of element A.

Example #3

The layout shift in this example would be reported with one source: element B. Changing the position of element B resulted in this layout shift.

Example #4

Although element B changes size, there is no layout shift in this example.

Check out a demo of how DOM changes are reported by the Layout Instability API.

DevTools

DevTools has a number of tools to help debug layout shifts.

Performance panel

The live metrics view of the Performance panel lets you interact with the page and monitor the CLS score to identify interactions causing large layout shfts.

The live metrics view of the Performance Panel allows monitoring of a web page's CLS score while interacting with the page.

Once you can reliable reproduce a layout shift, you can perform a trace to get even more details:

After recording a new trace in the Performance panel, the Layout Shifts track of the results is populated with purple bars displaying a Layout Shift clusters. Clicking the diamonds shows an animation of the shift and details in the Summary panel.

Layout shifts are highlighted in the Layout shifts track. The purple line groups shifts into shift clusters with the diamonds showing individual shifts in that cluster. The size of the diamond is proportional to the size of the shift allowing you to hone in on the largest shifts.

Clicking on a shift shows a pop up with an animation of the shift and highlights the elements shift in purple.

Additionally, the Summary view for a Layout Shift record includes the start time, the shift score as well as the elements shifted. This is particularly helpful to get more detail on load CLS issues since this is easily replicated with a reload performance profile.

This also links to the Layout shift culprits insight displayed in the Insights panel on the left, which shows the total CLS at the top, as well as possible reasons for layout shifts.

For more information on using the Performance panel, refer to Performance Analysis Reference.

Highlight layout shift regions

Highlighting layout shift regions can be a helpful technique for getting a quick, at-a-glance feel for the location and timing of the layout shifts occurring on a page.

To enable Layout Shift Regions in DevTools, go to Settings > More Tools > Rendering > Layout Shift Regions then refresh the page that you want to debug. Areas of layout shift will be briefly highlighted in purple.

Thought process for identifying the cause of layout shifts

You can use the following steps to identify the cause of layout shifts regardless of when or how the layout shift occurs. These steps can be supplemented with running Lighthouse—however, keep in mind that Lighthouse can only identify layout shifts that occurred during the initial page load. In addition, Lighthouse also can only provide suggestions for some causes of layout shifts—for example, image elements that don't have explicit width and height.

Identify the cause of a layout shift

Layout shifts can be caused by the following events:

Changes to the position of a DOM element
Changes to the dimensions of a DOM element
Insertion or removal of a DOM element
Animations that trigger layout

In particular, the DOM element immediately preceding the shifted element is the element most likely to be involved in "causing" layout shift. Thus, when investigating why a layout shift occurred consider:

Did the position or dimensions of the preceding element change?
Was a DOM element inserted or removed before the shifted element?
Was the position of the shifted element explicitly changed?

If the preceding element did not cause the layout shift, continue your search by considering other preceding and nearby elements.

In addition, the direction and distance of a layout shift can provide hints about root cause. For example, a large downward shift often indicates the insertion of a DOM element, whereas a 1 px or 2 px layout shift often indicates the application of conflicting CSS styles or the loading and application of a web font.

In this example, font swapping caused page elements to shift upwards by five pixels.

These are some of the specific behaviors that most frequently cause layout shift events:

Changes to the position of an element (that aren't due to the movement of another element)

This type of change is often a result of:

Stylesheets that are loaded late or overwrite previously declared styles.
Animation and transition effects.

Changes to the dimensions of an element

This type of change is often a result of:

Stylesheets that are loaded late or overwrite previously declared styles.
Images and iframes without width and height attributes that load after their "slot" has been rendered.
Text blocks without width or height attributes that swap fonts after the text has been rendered.

The insertion or removal of DOM elements

This is often the result of:

Insertion of ads and other third-party embeds.
Insertion of banners, alerts, and modals.
Infinite scroll and other UX patterns that load additional content above existing content.

Animations that trigger layout

Some animation effects can trigger layout. A common example of this is when DOM elements are 'animated' by incrementing properties like top or left rather than using CSS's transform property. Read How to create high-performance CSS animations for more information.

Reproduce layout shifts

You can't fix layout shifts that you can't reproduce. One of the simplest, yet most effective things you can do to get a better sense of your site's layout stability is take 5-10 minutes to interact with your site with the goal triggering layout shifts. Keep the console open while doing this and use the Layout Instability API to report on layout shifts.

For hard to locate layout shifts, consider repeating this exercise with different devices and connection speeds. In particular, using a slower connection speed can make it easier to identify layout shifts. In addition, you can use a debugger statement to make it easier to step through layout shifts.

new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    if (!entry.hadRecentInput) {
      cls += entry.value;
      debugger;
      console.log('Current CLS value:', cls, entry);
    }
  }
}).observe({type: 'layout-shift', buffered: true});

Articles

Files and directories patterns

Files and directories patterns

Preload responsive images

Responsive images overview

Preload overview

imagesrcset and imagesizes

Use cases

Preload dynamically-injected responsive images

Preload background images using image-set

Practical effects of preloading responsive images

Preload and <picture>

Preload and type

Effects on Largest Contentful Paint (LCP)

Back/forward cache

Browser compatibility

bfcache basics

How the "cache" works

The bfcache and iframes

The bfcache and Single Page Apps (SPA)

APIs to observe bfcache

Observe when a page is restored from bfcache

Observe when a page is entering bfcache

Optimize your pages for bfcache

Never use the unload event

Use Permission Policy to prevent unload handlers being used on a page

Only add beforeunload listeners conditionally

Minimize use of Cache-Control: no-store

Update stale or sensitive data after bfcache restore

Ads and bfcache restore

Avoid window.opener references

Close open connections before the user navigates away

Test to ensure your pages are cacheable

How bfcache affects analytics and performance measurement

Measure your bfcache hit ratio

Performance measurement

Impact on Core Web Vitals

Additional Resources

Lazy loading video

Using the loading attribute

Use the preload attribute to lazy-load video that doesn't autoplay

For video acting as an animated GIF replacement

Lazy loading libraries

Rendering on the Web

Terminology

Rendering

Performance

Server-side rendering

Static rendering

Server-side rendering versus static rendering

Client-side rendering

Rehydration combines server-side and client-side rendering

A rehydration problem: one app for the price of two

Stream server-side rendering and rehydrate progressively

Partial rehydration

Trisomorphic rendering

SEO considerations

Conclusion

Credits

Why is CrUX data different from my RUM data?

Benefits of supplementing CrUX with a RUM solution

Deeper analysis to investigate issues

Correlate with other business metrics

Collect other performance data

Differences between two sets of field data

Lab data versus field data

Populations

Included browsers

Opted-in users

Included sites

Devices

Sampling

Aggregation of data

Timespan

Aggregation of statistics

Differences in metrics

Metrics measured

Metric differences across browsers

Metrics timing

Single-page applications

`imagesrcset` and `imagesizes`

Preload and `<picture>`

Preload and `type`

Never use the `unload` event

Only add `beforeunload` listeners conditionally

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

Avoid `window.opener` references

Using the `loading` attribute

Use the `preload` attribute to lazy-load video that doesn't autoplay

Negotiate a base `font-size` based on user preferences

Option two: let `clamp()` do the work

How to ensure `font-size` values are responsive to zoom

How to ensure `font-size` values are responsive to user defaults

Typographic scales with `pow()`

01. Super Centered: `place-items: center`

02. The Deconstructed Pancake: `flex: <grow> <shrink> <baseWidth>`

03. Sidebar Says: `grid-template-columns: minmax(<min>, <max>) …)`

04. Pancake Stack: `grid-template-rows: auto 1fr auto`

05. Classic Holy Grail Layout: `grid-template: auto 1fr auto / auto 1fr auto`

06. 12-Span Grid: `grid-template-columns: repeat(12, 1fr)`

07. RAM (Repeat, Auto, MinMax): `grid-template-columns(auto-fit, minmax(<base>, 1fr))`

08. Line Up: `justify-content: space-between`

09. Clamping My Style: `clamp(<min>, <actual>, <max>)`

10. Respect for Aspect: `aspect-ratio: <width> / <height>`

Mix colors with `color-mix()`

Signal support for light and dark themes with the `color-scheme` property

Set "light" and "dark" variants with the `light-dark()` function

Register custom properties with `@property`

Debug high TTFB in the field with `Server-Timing`

Use `103 Early Hints` for render-critical resources

A modal `<dialog>`

Use the `showModal()` method to open a modal `<dialog>`

`popover`, rising to the top

Style the `::backdrop`