Container Timing API

1. Introduction

The Container Timing API enables monitoring when annotated sections of the DOM are displayed on screen and have finished their initial paint. A developer can mark subsections of the DOM with the containertiming attribute (similar to elementtiming for the Element Timing API) and receive performance entries when that section has been painted for the first time.

This API allows developers to measure the timing of various components in their pages. As developers increasingly organize their applications into components, there’s a growing demand to measure performance on subsections of an application or a web page.

Unlike Element Timing, it is not possible for the renderer to know when a section of the DOM has finished painting (there could be future changes, asynchronous requests for new images, slow loading buttons, etc.), so this API emits candidates in the form of PerformanceEntry objects when there has been an update.

2. Motivation

Developers want to measure when subsections of the DOM have been painted, such as tables, widgets, or other components, so they can track paint times and submit them to analytics. Current Web APIs don’t adequately support this:

• Element Timing is limited in what it can support and cannot be used for whole sections.

• Largest Contentful Paint (LCP) isn’t useful enough to time when specific parts of the page have loaded.

• User-space polyfills have significant drawbacks, such as:

  • Needing to mark elements before painting (requiring server-side changes or blocking rendering)

  • Requiring a MutationObserver to catch newly injected elements

  • Needing to run in the document head, increasing time to first paint

  • Can be less efficient at rectangle tracking compared to browser built-in 2D engines

Web authors know their domain better than anyone else and want to communicate the performance of their own content blocks in ways their users or organization would understand (e.g., "time to first tweet").

2.1. Life Cycle

However, once a region has been painted, subsequent paints of that same region will not generate new entries.

3. Usage Example

The following example demonstrates how to register a container root and observe its paint timings.

<div containertiming="foobar">
  <main>...</main>
  <aside>...</aside>
</div>

<script>
  const observer = new PerformanceObserver((list) => {
    let perfEntries = list.getEntries();
    for (const entry of perfEntries) {
      console.log('Container painted:', entry.identifier,
                  'at', entry.startTime,
                  'size:', entry.size);
    }
  });
  observer.observe({ entryTypes: ["container"] });
</script>

3.1. Ignoring Subtrees

<div containertiming="foobar">
  <main>...</main>
  <!-- Aside updates won't trigger container timing events -->
  <aside containertiming-ignore>...</aside>
</div>

4. Terminology

A container root is an Element that has the containertiming attribute.

An ignored subtree is a subtree rooted at an Element with the containertiming-ignore> attribute.

A painted region is a region (collection of rectangles) representing all the painted portions of a container root accumulated since it was first observed.

The container timing API provides timing information about when container roots are painted to the screen.

5. The PerformanceContainerTiming Interface

[Exposed=Window]
interface PerformanceContainerTiming : PerformanceEntry {
    readonly attribute DOMString identifier;
    readonly attribute DOMRectReadOnly intersectionRect;
    readonly attribute unsigned long long size;
    readonly attribute DOMHighResTimeStamp firstRenderTime;
    readonly attribute Element? lastPaintedElement;
    readonly attribute Element? rootElement;
};

PerformanceContainerTiming includes PaintTimingMixin;

Note: The user agent needs to maintain the container root records map so that removed content does not introduce memory leaks. In particular, it can tie the lifetime of the entries to weak pointers to the Elements so that they can be cleaned up sometime after the Elements are removed. Since the map is not exposed to web developers, this does not expose garbage collection timing.

6. Processing Model

Note: A user agent implementing the Container Timing API would need to include "container" in supportedEntryTypes for Window contexts. This allows developers to detect support for container timing.

6.1. Per-Document State

For each Document, the user agent must maintain a container root records map that maps container root Elements to Container Timing Record objects.

6.2. Extensions to the Element Interface

This section will be removed once the [DOM] specification had been modified.

partial interface Element {
    [CEReactions] attribute DOMString containertiming;
    [CEReactions] attribute DOMString? containertimingIgnore;
};