Published: May 01, 2026
Chrome is launching an origin trial from Chrome 148 for the Container Timing performance API.
Metrics like Largest Contentful Paint (LCP) provide a high-level overview of when a page is likely to be considered "loaded" by the user by looking at the paint time of the largest bit of content. However, sites might also be interested in when particular parts of the page are loaded, and not just the "largest" part.
Element Timing lets sites mark up elements with an elementtiming attribute to understand when they load, whether they are the LCP element or not. However, like LCP, it is limited to measuring the render times of individual elements.
Container Timing extends the Element Timing concept to measure "blocks of content" (or "containers"). This lets you understand when an entire component was available to the user such as widgets, cards, sections of content, sidebars... whatever! It provides additional performance information for sites that want the extra insights it can provide.
Container Timing, developed by Bloomberg and implemented in Chrome by Igalia, is available behind a flag for Chrome users and other Chromium-based browsers and is also available for sites to test in the field through an origin trial.
An origin trial is one of the final steps of launching an API where developers can enable the feature on their sites before it's launched by default to test it, and inform the team whether it is working as expected and proving useful. It also lets developers suggest any changes to the API design before launch.
How the Container Timing API works
Like Element Timing, Container Timing works by adding an attribute (containertiming) to various HTML elements to indicate to the browser that these elements should be measured:
<div containertiming="my-component">
<h2>Title</h2>
<div>...</div>
</div>
A PerformanceObserver then lets you observe paints within that container in the same way as other performance metrics:
<script>
const observer = new PerformanceObserver((entryList) => {
for (const entry of entryList.getEntries()) {
console.log("Container painted:", entry.identifier);
console.log("First render:", entry.firstRenderTime);
console.log("Latest paint:", entry.startTime);
console.log("Painted area:", entry.size);
console.log("Last painted element:", entry.lastPaintedElement);
}
});
observer.observe({ type: "container", buffered: true });
</script>
As new elements are painted in the container, new performance entries are emitted with updated information. Since new elements can be added throughout the life of the page, there is no single completion point. This is similar to LCP, which is typically measured at the end of the page, when navigating away.
These performance metrics can then be sent back to analytics for monitoring and analysis.
Child containers can also be ignored with the containertiming-ignore attribute:
<div containertiming="main-content">
<main>...</main>
<!-- This aside and its children will be ignored -->
<aside containertiming-ignore>...</aside>
</div>
Demo
The following CodePen shows the Container Timing API in action:
You can also see this in action in the following video if your browser does not support the Container Timing API:
What updates count for Container Timing?
The intent of Container Timing is to capture when the container is loaded with all child elements. It is not intended to measure every single future paint—many of which may arrive much later as the user interacts with the container or the page. For this reason, similar to LCP and Element Timing, Container Timing depends on "contentful paints" and also does not emit entry new paint entries for elements that have already been counted as having a contentful paint.
For example, if a container is initially rendered with just a background color, or containing only non-contentful elements (for example, skeleton screens) then no container entry will be emitted until some content is added to the container.
For an update example, updating text on an existing element in the container won't result in a new container entry for that update because only the first paint of content for an element is considered. However, if text is added to an empty element, or an additional new element is added for that text then a new container entry will be emitted because this will be the first paint of that element.
Feature-detecting Container Timing support
The containertiming attribute won't cause issues for unsupporting browsers, so does not need to be feature-detected.
The PerformanceObserver will ignore any new entries, but they can cause warnings in DevTools, so it is best practice to feature-detect before adding an observer with code such as:
if (typeof PerformanceContainerTiming !== "undefined") {
// Container Timing is supported
}
Best practices
There are some best practices to follow for optimal use of Container Timing:
- Set attributes early: Add the
containertimingattribute in the HTML document, or before the element is added to the document for complete tracking. Adding the attribute afterward with JavaScript may result in missed paints. - Use meaningful identifiers: Choose descriptive names for the
containertimingattribute to make analytics easier. - Strategic placement: Apply
containertimingto semantic sections that matter for your metrics, for example,hero-section,product-grid,checkout-form. Not every container needs to be measured. - Ignore irrelevant content: Use
containertiming-ignoreon child elements that shouldn't affect your component metrics such as ads or decorative elements.
How to enable Container Timing?
The Container Timing API can be enabled from Chrome 147 using the chrome://flags/#enable-experimental-web-platform-features flag and from the command line using the --enable-blink-features=ContainerTiming flag.
From Chrome 148 sites can register for an origin trial token and add this to their page to enable the feature automatically. This lets you test the API in the field on real users. Container Timing metrics can be recorded in analytics and analyzed to verify whether the API works as expected and gather insights.
Feedback and more details
Feedback on the Container Timing API should be raised as issues on GitHub.
There is also a specification making its way through the standardization process. For those interested in how this API works internally, Igalia has published a post on how the API was technically implemented.
Conclusion
It's great to see this API nearing release and we're excited to get it into the hands of developers to enable new insights into performance issues. We look forward to gathering feedback on the API and, if all goes well, launching it shortly after.