Largest Contentful Paint API

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The Largest Contentful Paint API provides perceived performance data that allows you to know exactly how long a user waits, after navigating to your page, before seeing the main content of the page in their browser viewport — in contrast to just knowing when the user can first see a loading indicator or background image or other such initial/early-loading content (which is what the related Paint Timing API provides).

Concepts and Usage

The key principle underlying the Largest Contentful Paint API is that by having data to help you minimize the time that users have to wait before they can see the site's main content, you can make the site feel more engaging and responsive (better performing) for your users.

See the perceived performance article for an introduction to the core concepts underlying both the Largest Contentful Paint API and the Paint Timing API.

The Largest Contentful Paint metric provides the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. The API supports the following elements:

Interfaces

LargestContentfulPaint

Reports details about the largest image or text paint before user input on a web page.

Examples

The following example shows an image and a large paragraph of text. An observer is registered to get the largest contentful paint while the page is loading.

<img src="large_image.jpg" />
<p id="large-paragraph">This is large body of text.</p>
const observer = new PerformanceObserver((list) => {
  let perfEntries = list.getEntries();
  let lastEntry = perfEntries[perfEntries.length - 1];
  // Process the latest candidate for largest contentful paint
});
observer.observe({entryTypes: ['largest-contentful-paint']});

Specifications

Specification
Largest Contentful Paint
# sec-largest-contentful-paint-interface

Browser compatibility

BCD tables only load in the browser

See also