Container Timing

at a glance

why it exists

The Element Timing API lets you observe when a single <img> or text block renders. But modern pages are built from components — a news card, a product widget, a comment thread — and what developers actually care about is when the whole component is ready, not just its headline image. Container Timing extends the same elementtiming / PerformanceObserver pattern to entire subtrees: mark a container with the containertiming attribute, and the browser reports the render timing of the container as a whole, tracking its constituent elements until all have painted.

shape of the API

Add the containertiming attribute to any element you want to measure. The attribute value becomes the identifier in the resulting PerformanceContainerTiming performance entry:

<section containertiming="product-card">
  <img src="product.jpg" alt="...">
  <h2>Product Name</h2>
  <p>Description...</p>
  <button>Add to cart</button>
</section>

PerformanceEntry properties

example

Observe container render metrics using a buffered PerformanceObserver:

const observer = new PerformanceObserver((entryList) => {
  for (const entry of entryList.getEntries()) {
    console.log(`Container "${entry.identifier}" rendered`);
    console.log('  First paint:', entry.firstRenderTime, 'ms');
    console.log('  Last paint:', entry.startTime, 'ms');
    console.log('  Painted area:', entry.size, 'px²');
    // entry is a PerformanceContainerTiming; entry.entryType is "container"
    console.log('  Entry type:', entry.entryType);
    console.log('  Last painted element:', entry.lastPaintedElement);
  }
});

observer.observe({ type: 'container', buffered: true });

Measuring multiple components

<!-- Mark each component you want to time -->
<div containertiming="hero-banner"> ... </div>
<ul containertiming="product-grid"> ... </ul>
<aside containertiming="sidebar-recs"> ... </aside>

// The observer receives separate entries for each identifier
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    sendMetric(`render_${entry.identifier}`, entry.startTime);
  }
});
observer.observe({ type: 'container', buffered: true });

Origin trial setup

<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">

browser support

see also

• WICG Container Timing specification
• Container Timing origin trial — Chrome for Developers
• WICG/container-timing — spec explainer on GitHub
• MDN: Element Timing API — the sibling API
• chromestatus — Container Timing (5110962817073152)
• chrome-platform-showcase — live demo