Intent to Implement: Display Locking


Contact emails

vmpstr@chromium.org, chrishtr@chromium.org


Short version: https://github.com/chrishtr/display-locking/blob/master/README.md

Long version: https://github.com/chrishtr/display-locking/blob/master/explainer.md

TAG review filed: https://github.com/w3ctag/design-reviews/issues/306


Display Locking is a proposal to add a script API which locks a DOM element for display. When an element is locked, its visual representation on the page does not change as a result of DOM mutations. Instead, the DOM is mutated and its structure can be inspected and modified in script.

When the lock is committed, a commit promise is returned and  the user-agent starts to process the needed steps for visual presentation cooperatively. That is, it performs style, layout, compositing, and paint steps without jank. When this process is done and the element (and its subtree) are ready to be displayed, the commit promise is resolved, giving the developer an opportunity to inspect DOM properties that are determined during layout, and possibly re-acquire the lock. If the lock is not re-acquired, the element and its subtree are presented to the screen.

While the element is locked, there are options of what is actually displayed to screen. If an element was in the DOM at the time of the lock acquisition, one option is to keep presenting the same visual state even though the subtree DOM might be mutated. If a new element is locked and inserted into the DOM, then the visual representation of the element and its subtree is blank. The following issues track progress on solidifying these steps:



WICG thread: https://discourse.wicg.io/t/proposal-display-locking/2905

WhatWG thread: https://github.com/whatwg/html/issues/4010


Websites frequently rely on dynamic content to present information. This means that DOM is often manipulated using script to present rich and dynamic content. There are cases when this can cause slow rendering phase updates, including script to update views, style updates, layout, and paint. This, in turn, causes jank or noticeable delay when presenting content, because rendering phase is updated synchronously with user interactions and requestAnimationFrame script.

The following are a few of the common patterns that can cause jank:

  • Resizing multi-pane UI with complex layout within each pane (e.g. IDEs)
  • Adding widgets with complex DOM.
  • Dynamically displaying content based on the current value of text input.
  • Measuring layout of otherwise hidden DOM with intent of sizing containers.

This proposal, if implemented, reduces the jank by allowing the patterns to be used while locking parts of the DOM. The locked subtrees, when processed cooperatively, do not contribute to jank.


Interoperability and Compatibility

This is a new feature, meaning that existing web content is unaffected by the new API. It should be easy to detect the availability of this feature. If a user-agent does not implement the API, then most common patterns can still be implemented although they may cause jank.

Edge: No signals

Firefox: No signals

Safari: No signals

Web developers: Positive (positive feedback from ReactJS and Polymer).


The cases outlined in examples are small modifications to otherwise regular JavaScript code, so it should be easy to adopt this feature. Conversely it should also be easy to stop using this feature, with the risk of increasing jank.


This feature should be easy to use as-is, or as a part of a library.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?


Link to entry on the feature dashboard


Requesting approval to ship?