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.

We extend the Element interface as follows:

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

6.3. Container Timing Record

This specification defines an internal data structure used by the processing model:

6.4. Registering Container Roots

When an Element with a [^containertiming^] content attribute is connected to the document:

1. The user agent must register the element as a container root.

2. The user agent must initialize an empty painted region for the container root.

3. The user agent must track all paint operations within the container root’s subtree, excluding any ignored subtrees.

6.5. Handle Element Painted for Container Timing

Note: This algorithm is invoked for each image or text node that paints. The intersection rectangle should be computed using the intersection rect algorithm with the element as target and viewport as root, intersected with the visual viewport. For text nodes, the intersection rectangle is the smallest rectangle containing the border boxes of all text nodes in the set of owned text nodes, intersected with the visual viewport.

6.6. Emit Container Timing Entries

Note: Unlike some other paint timing APIs that may emit multiple entries per painted element, Container Timing accumulates painted regions for each container root and emits at most one PerformanceContainerTiming entry per container root per frame. This batching approach is more efficient and provides a holistic view of the container’s paint state.

6.7. Getting the parent container root Element

6.8. Contributes to Container Timing

An Element contributes to the container timing of a container root if all of the following are true:

• It is a descendant of the container root.

• It is not within an ignored subtree.

• It is not in a shadow tree.

6.9. Getting the container root Element

6.10. Maybe Update Last New Painted Area

Note: This algorithm reports any change to the painted region, regardless of size. Even a 1 pixel change in the painted area will result in a new PerformanceContainerTiming entry being queued. Developers who wish to filter out small changes may do so by comparing the size values between entries.

6.11. Create a Container Timing Entry

7. Security and Privacy Considerations

7.1. Cross-Origin Restrictions

The API respects cross-origin boundaries:

• Elements belonging to cross-origin iframes are not exposed to parent frames.

• No timing information crosses frame boundaries unless explicitly passed by the developer via postMessage.

7.2. Information Exposure

Most information provided by this API can already be estimated through existing APIs:

• Element Timing returns first rendering time for images and text.

• Paint Timing API provides related timestamps.

• The combination of these APIs could approximate container timing information, though less efficiently.

The API does not expose:

• Internal implementation details of the rendering engine

• Information about elements the developer doesn’t already have access to

• Timing information more granular than already available through existing Performance APIs

7.3. Timing Attacks

The API uses DOMHighResTimeStamp which may be subject to resolution limitations for security purposes, consistent with other Performance APIs.

7.4. Privacy Considerations

The API does not:

• Enable tracking users across sites

• Expose browsing history

• Provide information about user behavior beyond what the site already has access to through script execution

8. Acknowledgments

Many thanks for valuable feedback and advice from:

• Barry Pollard

• Michael Mocny

• Scott Haseley

• Sergey Chernyshev