Web Platform Team Blog

Making the web awesome

CSS Regions polyfill – better, smarter, fuller

We first started work on a CSS Regions prototype to give designers and developers a seamless and flexible way to flow content inside a chain of boxes. As the feature gained visibility, it became clear that people wanted to experiment outside the WebKit-based browsers. So about one year ago, we created a rather simple polyfill supporting only basic functionality. Today, we would like to introduce a much-improved CSS Regions polyfill library, created by Francois Remy.

What’s new

What’s new? Basically everything the new polyfill was re-written from scratch to make it more flexible and feature rich. Under the hood, it is based on a general-purpose CSS parser. This means it’s more robust and less likely to produce unexpected results if your CSS is odd-looking (minified, uglyfied and so on).

The most readily apparent difference from the old polyfill is that it drops the support for the −adobe− prefix and instead only supports the standard, non-prefixed form of the properties and APIs. If your stylesheets are future-proofed with the standard, non-prefixed syntax, the new polyfill is essentially a drop-in replacement: you don’t need to do anything else! 🙂 Also, all CSS properties are supported: along with flow−from and flow−into, region−fragment, break−before and break−after are supported (Keep in mind, Safari uses the old syntax for forced breaks inside regions, −webkit−region−break−before and −webkit−region−break−after).

Another notable addition is the support for the Regions CSSOM. This covers the NamedFlow interface, additions to the Element interface corresponding to the Region interface and support for the NamedFlow events (regionoversetchange and regionfragmentchange).

Unlike the old polyfill that required the Regions-specific code to be inlined within the HTML, the new polyfill fully supports external stylesheets. It also automatically updates the layout when the DOM is changed through JavaScript or when the viewport size changes through resizing or device rotation.

Also, unlike the old polyfill, the new polyfill doesn’t require the regions to have their size explicitly set.

What’s the catch?

This is a polyfill. It’s not the real deal and has some gotchas you should be aware of.

First of all, interactive content like form elements, contentEditable elements or user-interaction pseudo-classes (for example, :active, :hover) and JavaScript event listeners are something of a shot in the dark. The polyfill actually clones the contents of the named flow to move them through regions. This will likely cause interactive content to work in unexpected ways. Another effect of the content cloning is with the CSS cascade. The new DOM structure could make some selectors not apply anymore or new selectors to apply where they wouldn’t before.

This polyfill is doing the layout asynchronously. So, the user may experience content flickering, especially if scrolling before the page layout is complete. Especially with more complex layouts, auto-sizing can behave differently than a browser-native implementation.

Another missing piece is support for region styling – neither the standard ::region() pseudo-functional syntax nor the old and no longer standard @region syntax.

In terms of CSSOM, the NamedFlow.getRegionFlowRanges() is not implemented. Furthermore, the timing of the NamedFlow events is not guaranteed to be the same as a native, standards-compliant implementation. This means some events could be fired more often or with a delay when compared to a native, standard-compliant implementation.

Demo time

If you want to see the new polyfill in action you can check out the Regions samples hosted on CodePen. Where possible, we’ve converted the samples to render with the polyfill if the browser doesn’t support CSS Regions natively. Also, two important demos showing some of the major use cases of CSS Regions – the National Geographic Orphan Elephants demo and the Adaptive UI demo – are now polyfill-enabled so you can enjoy them on any browser, not just Safari.

How to get it

You can grab a copy from Francois Remy’s GitHub repository. There you will also find extensive documentation of what the polyfill does and how it does it.

Feel free to grab a copy, give it a run and, if something bugs you, don’t hesitate to file an issue or send out a pull request.


  1. March 10, 2014 at 10:20 am, Zach Saucier said:

    The National Geographic Orphan Elephants demo and the Adaptive UI demo links are broken (:

    • March 11, 2014 at 2:33 am, Andrei Bucur said:

      Thanks for the heads up! It should be fixed now :).