Intent to Implement: CSS Layout API

Skip to first unread message

Jan 11, 2018, 2:11:12 PM1/11/18
to blink-dev

Contact emails


Design doc/Spec


Tag Review:

A design doc with be forthcoming, once we land some more foundational pieces (worklet infrastructure etc). This design doc will primarily focus on blink specific integration with the current layout engine.


We intend on implementing a subset of the current CSS Layout API, which will help inform the specification and research in this area, with the desire to ship this subset at a later date. We’d like to perform a significant amount of implementation before the next Houdini F2F in April.

We don’t currently intend to implement other ChildDisplayTypes other than block (this will mean that having a layout which performs line-by-line layout won’t be possible at this stage[1]). In addition we don’t currently intent to implement any of the block fragmentation primitives at this stage. Once parts of the LayoutNG project complete we’ll be able to add this functionality without imposing a large technical debt on the engine.

With this subset web developers will be able to implement various types of block/flex/grid-like layouts, for example masonry layouts, subgrid aware layouts, etc.

[1] After this initial implementation we’ll investigate the technical debt with and without LayoutNG for line-by-line layout.


Today web developers only have the predefined layout modes (grid/flex/table/block-flow). These are powerful, but typically are unsuited to polyfilling new layout features. Typically developers will find themselves using a combination of absolute positioning, to manually size and place elements, and MutationObservers to detect any changes they need to respond to.

The CSS Layout API provides a much easier/powerful primitive for achieve the same goal. The callbacks happen within the layout phase, instead of before/after.


Interoperability and Compatibility

The primary risk is that other browsers don’t implement this feature and it doesn’t become part of the wider web platform.

Another major risk is that browser layout engines aren’t completely interoperable with each other today. Under various circumstances engines will perform a different number of layout passes, and provide different inputs to a layout. We plan on trying to mitigate this risk by having a web platform test suite, which tests the desired output from layout. However we won’t be able to prescribe how many layout passes, and what types of inputs for every case. (This is a large existing source of frustration for web developers today).

We plan on upstreaming early to web-platform-tests while we develop this feature (in conjunction with updating the specification). A lot of edge cases (avoiding floats, tables, etc) will be covered by these tests, to try and mitigate the relatively high interoperability risk described above.

Edge: No signals

Firefox: No signals

Safari: No signals

Web developers:

 Positive: Web developers are broadly excited about having additional tools to polyfill/implement web layout features.

 Negative: Web developers are concerned that with these new primitives, browser vendors are less likely to implement various standards.


The CSS Layout API will be used like any other layout mode on the web today, setting the display property of an element. E.g. `display: layout(masonry);` It can be combined with the rest of the web’s layout modes. E.g. it will work when it is absolutely positioned etc.

This API has the ability to slow down the layout pass of the engine, (web developers will have the power to perform multi-pass layouts). If necessary we plan on mitigating this by falling back to block layout if a layout is deemed too expensive.


We expect that this feature won’t have broad adoption initially (this is similar to other new CSS features which typically only have broad adoption after most of the evergreen browsers support it). We may find people using it as a performance primitive (to replace expensive versions of existing layouts), or for visual effects which have a reasonable fallback on other browsers (e.g. a shape-inside, or line-clamp like feature).

We expect that people will build libraries on top of this feature with a simple interface exposed via custom CSS properties.


Most of the debugging features should work out of the box. Currently work is being investigated to pause javascript while in the middle of the render lifecycle, and this work will translate over to the CSS Layout API.

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?


Reply all
Reply to author
0 new messages