Short guide to using CSS Regions

Guide to CSS Regions.md

Guide to CSS Regions

Introduction

CSS Regions are a mechanism used in web pages to separate content from its layout. Regions can be used to visually flow content from one element to another regardless of the content's original location in the DOM tree.

Concepts

region chain, named flow, overset

Workflow

CSS selectors are used to match elements and pull them into a named flow by using the flow-into CSS property. This pulls the elements out from the normal document flow and hides them.

The elements pulled into the named flow can be made to show up again in other parts of the document by using the flow-from CSS property. These parts of the document, either other elements or boxes generated by CSS, become regions.

All the regions that pull content from the same named flow form a region chain. The content that doesn't fit into a region continues to render in the next region from the region chain.

Example

<style>
  #content {
    /* pull the element into a named flow */
    flow-into: myFlow;
  }

  .region{
    /* show the content from the named flow */
    flow-from: myFlow;
  }
</style>

<div id="content">...</div>

<!-- The #content div show up distributed across .region divs-->
<div class="region"></div>
<div class="region"></div>

CSS Properties

flow-into: <ident>

flow-from: <ident>

Working with CSS Regions and JavaScript

CSS Regions expose a JavaScript API at the DOM level, called a CSS Object Model (CSSOM), which can be used to observe named flows, regions and the interactions between them.

These are just a few use cases for using the Regions CSSOM:

Add regions to fit the content of a named flow

describe use case here

Check if a region is empty or full

describe use case here

Remove unused, empty regions

describe use case here

Regions CSSOM Reference

Named Flows

document.getNamedFlows() {NamedFlowList}

• Returns a list of NamedFlow objects representing named flows available on the page. See NamedFlow.

NamedFlow {Object}

• An instance of the named flow which holds elements collected using CSS.

NamedFlow.getContent() {NodeList}

• Returns a list of elements collected into the named flow using the flow-into CSS property.

NamedFlow.getRegions() {???}

• Returns a list of Region objects which pull content from the named flow.

NamedFlow.overset {Boolean}

• Boolean property; true if the content of the named flow doesn't fully fit in the regions associated to it. More regions are required.

NamedFlow.firstEmptyRegionIndex {Number\Integer}

• The index from the list returned by NamedFlow.getRegions() which points to the first region that did't get any content from the named flow. That region is empty. All other regions after this index are also empty. If the value is -1, then none of the regions from the region chain are empty.

Regions

Region {Object}

• An instance of the box that pulls content from a named flow. A region can be either a DOM element or any other box generated through CSS, such as a grid cell. Only block element can be regions. CSS pseudo-elements can't be regions.

Regions.regionOverset {String}

• Represents the state of a region in relation to the content inside it:
  • 'empty' means there's no content in the region
  • 'fit' means the content fit in this region and it doesn't need to flow to another region in order to be fully rendered.
  • 'overset' means the content did not fully fit in this region and needs more regions in order to be fully rendered.

Region.getRegionFlowRanges()

Region.getComputedRegionStyle()

Events

regionoversetchange {Event}

• Event thrown by a NamedFlow object after the regionOverset property changes on any of its regions. Also thrown when regions are are added or removed from the named flow.

Example

flow = document.getNamedFlows().item('myFlow')
flow.addEventListener('regionoversetchange', function(){
  // Do something after a region's regionOverset propery has changed.
})

regionfragmentchange {Event}

• Event thrown by a NamedFlow object after the layout of content has changed inside any of its regions. This includes moving, shifting, resizing and so forth. If the content layout causes a regionOverset property to change on any of the regions, the regionoversetchange event will also be thrown.

Thank you for this document. It is really useful.