CSS Regions Module

Abstract

The CSS Regions module allows content to flow across multiple areas called regions. The regions do not necessarily follow the document order. The CSS Regions module provides an advanced content flow mechanism, which can be combined with positioning schemes as defined by other CSS modules such as the Multi-Column Module [CSS3COL] or the Grid Layout Module [CSS3-GRID-LAYOUT] to position the regions where content flows.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css3-regions” in the subject, preferably like this: “[css3-regions] …summary of comment…”

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This is a First Public Working Draft.

Table of contents

• 1. Introduction
  • 1.1. Named flows and regions
  • 1.2. Regions Styling
• 2. CSS Regions Model
  • 2.1. Named flows
  • 2.2. Regions
  • 2.3. Flow breaking rules
    • 2.3.1. Breaking a named flow and determining the current flow region
    • 2.3.2. Allowed region breaks
    • 2.3.3. Forced region breaks
    • 2.3.4. "Best" region breaks
  • 2.4. The Visual Formatting Model and Flows
    • 2.4.1. Normal flow
    • 2.4.2. Positioned flow
    • 2.4.3. Column flow
    • 2.4.4. Generated flow
  • 2.5. Relation to document events
• 3. Properties and Rules
  • 3.1. The ‘flow’ property
  • 3.2. The ‘content’ property
  • 3.3. The ‘content-order’ property
  • 3.4. Region flow break properties: ‘break-before’, ‘break-after’, ‘break-inside’
  • 3.5. The region-overflow property
  • 3.6. The @region rule
• 4. CSSOM View and CSS Regions
  • 4.1. The NamedFlow interface
  • 4.2. Extension to the Element interface
• 5. Integration with other specifications
  • 5.1. Region requirements
  • 5.2. Integration Examples
    • 5.2.1. CSS Grid Layout
    • 5.2.2. CSS Multi-Column Layout
    • 5.2.3. CSS Visual Formatting
• 6. Relation to other specifications
• 7. Conformance
• Acknowledgments
• References
  • Normative references
  • Other references
• Index
• Property index

1. Introduction

Capturing the complex layouts of a typical magazine, newspaper, or textbook requires capabilities beyond those available in existing CSS modules. This is the purpose of the CSS Regions module.

The CSS Regions module can be seen as an extension of the concept of multi-column elements. With CSS Multi-column layout [CSS3COL], columns share the same dimensions and define column boxes organized in rows. Content flows from one column to the next.

The multi-column model is an example of flowing content from one area to another, where the areas are the multi-column element's column boxes and the flow is made of the multi-column element's children.

However, for more complex layouts, content needs to flow from one area of the page to the next without limitation of the areas' sizes and positions. These arbitrary areas are the target of specific content flows. In this document these areas are called regions, and the content flows are called named flows. Regions are based on the rectangular geometry of the CSS box model. Elements in a named flow are taken out of the normal visual formatting and rendered in a chain of regions.

1.1. Named flows and regions

Consider the layout illustrated in figure 1.

Layout requiring sophisticated content flow

The designer's intent is to position an image in region ‘A’ and to flow an article's text from region ‘1’, to region ‘2’, ‘3’ and ‘4’.

The following code snippet shows the content to flow between the regions 1, 2, 3 and 4.

<div id="article">
<h1>Introduction</h1>
    <p>This is an example ...</p>
    
<h1>More Details</h1>
    <p>This illustrates ...</p>
    <p>Then, the example ...</p>
    <p>Finally, this ...</p>
</div>
        

CSS layout facilities can position and size regions as needed. However, there is no existing mechanism to associate the content with the regions so that content flows as intended. Figure 2 shows an example of the intended visual rendering of the content.

Sample rendering for desired layout

Since the CSS Regions module is independent of the layout of regions and the mechanism used to create them, the following assumes there is a CSS selector for the regions and, for the purpose of the example, the selectors for regions 1, 2, 3 and 4 show as ‘<region1_sel>’, ‘<region2_sel>’, ‘<region3_sel>’ and ‘<region4_sel>’ respectively. Such a selector could be an id selector (e.g., ‘#region_1’) or a grid cell selector (e.g., ‘#myGrid::grid-cell([cell-name])’) if using the CSS Grid Layout module, for example.

<style>

#article {
    flow: article_flow;
}

<region1_sel>, <region2_sel>, 
<region3_sel>, <region4_sel> {
    content: from-flow(article_flow);
}
</style>

The above stylesheet directs the ‘#article’ element to a named flow called ‘article_flow’ by setting the ‘flow’ property. Then, content is "poured" from that named flow into the desired regions by setting the regions' ‘content’ property to ‘from-flow(article_flow)’.

1.2. Regions Styling

Region styling allows content to be styled depending on the region it flows into. It is a form of context-based styling, similar to Media Queries [MEDIAQ] which enable or disable selectors depending on the rendering context. With region styling, additional selectors may apply depending on the region into which content flows.

In our example, the designer wants to make text flowing into region 1 larger, bold and dark blue. In addition, <h1> headers should be run-ins and crimson.

This design can be expressed with region styling as shown below.

<style>
/*
 * Default article styling.
 */
#article {
    color:#777;
    text-align: justify;
}

#article h1 {
    border-left: 1px solid #777;
    padding-left: 2ex;
}

/*
 * Additional styling to apply to content when it falls into 
 * region_1
 */
@region <region1_sel> {
    #article::region-lines {
        font-weight: bold;
        color: #0C3D5F;
        font-size: larger;
    }

    #article h1 {
        color: crimson;
        display: run-in;
        border: none;
        padding: 0px;
    }
}
</style>

The ‘@region’ rule for region 1 limits its selectors to content flowing into region 1. The following figure shows how the rendering changes if we do not increase the font size nor make it bold for content flowing into region 1. As more content can be fitted, more content is subject to the contextual selectors, resulting in more dark blue text into region 1.

The ‘::region-lines’ pseudo-element is described later in this specification.

Different rendering with a different region styling

2. CSS Regions Model

2.1. Named flows

In the CSS formatting model, elements can be in the normal flow or out of the (normal) flow. Boxes generated by elements in the normal flow are subject to their container box's normal layout scheme. Boxes generated by elements out of the normal flow are subject to a different layout scheme. For example, absolutely positioned elements are subject to absolute positioning into their containing block. This can be described by saying that the absolutely positioned elements are part of a special flow (called positioned flow) which is subject to a special layout by its container box (i.e., its container box positions it into the containing block's box).

In both cases, there is a notion of flow containing a sequence of elements and there is a notion of (block) container box into which the elements flow.

The CSS Regions module generalizes the concept of flow by adding the concept of a named flow. This module lets authors explicitly place elements into a named flow.

With this model, all elements are moved to a flow as part of the visual formatting. That flow may be the normal flow, a named flow or a positioned flow, for example. A flow gets formatted visually when associated with one or several elements' container box(es). When an flow is associated with container boxes, the boxes generated by the flow's elements are laid out according to the container box's layout scheme and the flow is subject to the ‘flow breaking rules’ described below.

A container's layout scheme is the strategy used by a container to position the boxes generated by its children and itself. Examples are the normal layout (block and inline formatting) ([CSS21]), table layout ([CSS21]), the multi-column layout ([CSS3COL]) or the grid layout ([CSS3-GRID-LAYOUT]).

2.2. Regions

A region is an element that generates a block container box and has an associated named flow (see the ‘content’ property).

A region‘s intrinsic width is zero.

2.3. Flow breaking rules

Breaking a named flow across multiple regions is similar to breaking a document’s content across multiple pages. One important difference is that page boxes are generated based on the available content whereas regions are a predefined set of recipients for the named flow content.

2.3.1. Breaking a named flow and determining the current flow region

The ‘content-order’ property defines how regions are organized in to a region chain.

Each region in turn consumes content from its associated named flow. This means that the named flow content is positioned in the current region until a region break occurs, at which point the current region becomes the next one in the region chain. If there is no more region in the region chain and there is still content in the flow, the positioning of the remaining content is controlled by the ‘region-overflow’ property on the last region in the chain.

The following sections define where region breaks may happen when positioning a named flow across regions in a region chain.

2.3.2. Allowed region breaks

In a named flow, region breaks can occur at the following places:

1. In the vertical margin between block-level boxes. When an unforced region break occurs here, the used values of the relevant ‘margin-top’ and ‘margin-bottom’ properties are set to ‘0’. When a forced region break occurs here, the used value of the relevant ‘margin-bottom’ property is set to ‘0’; the relevant ‘margin-top’ used value may either be set to ‘0’ or retained.
2. Between line boxes inside a block container box.
3. Between the content edge of a block container box and the outer edges of its child content (margin edges of block-level children or line box edges for inline-level children) if there is a (non-zero) gap between them.

These breaks are subject to the following rules:

• Rule A: Breaking at (1) is allowed only if the ‘break-after’ ‘break-before’ properties of all the elements generating boxes that meet at this margin allow it, which is when at least one of them has the value ‘always’, ‘left’, or ‘right’, or when all of them are ‘auto’.
• Rule B: However, if all of them are ‘auto’ and a common ancestor of all the elements has a ‘break-inside’ value of ‘avoid-region’, then breaking here is not allowed.
• Rule C: Breaking at (2) is allowed only if the number of line boxes between the break and the start of the enclosing block box is the value of ‘orphans’ or more, and the number of line boxes between the break and the end of the box is the value of ‘widows’ or more.
• Rule D: In addition, breaking at (2) or (3) is allowed only if the ‘break-inside’ property of the element and all its ancestors is ‘auto’.

If the above does not provide enough break points to keep content from overflowing the region boxes, then rules A, B and D are dropped in order to find additional breakpoints.

If that still does not lead to sufficient break points, rule C is dropped as well, to find still more break points.

2.3.3. Forced region breaks

A region break must occur at (1) if, among the ‘break-after’ and ‘break-before’ properties of all the elements generating boxes that meet at this margin, there is at least one with the value ‘always’, ‘left’, or ‘right’.

2.3.4. "Best" region breaks

CSS 2.1 does not define which of a set of allowed region breaks must be used; CSS 2.1 does not forbid a user agent from breaking at every possible break point, or not to break at all. But CSS 2.1 does recommend that user agents observe the following heuristics (while recognizing that they are sometimes contradictory):

• Break as few times as possible.
• Avoid breaking inside a replaced element.

2.4. The Visual Formatting Model and Flows

This section describes the flows to which elements formatted according to the CSS Visual Formatting Model and other layout modules (such as Multi-Column Layout [CSS3COL]) belong to.

In particular, this section describes the ‘generated flow’ where generated content of pseudo-elements is placed and several ‘auto flows’ where children of content elements are automatically placed.

2.4.1. Normal flow

In the CSS formatting model, elements are by default placed in the normal flow of their container. Also by default, a container element gets its content from its normal flow. This means that by default, a container element will visually format its children elements and will be the only container associated with its normal flow.

Note that floats and relatively positioned elements, in this model, are part of the same flow of content and flow into the same container but are positioned in different ways.

The normal flow is one of the auto flows.

2.4.2. Positioned flow

An absolutely positioned element is placed into the positioned flow of its container. The container positions this element into its containing block.

If a container has children in the normal flow and in the positioned flow, it applies different positioning schemes to each flow.

The positioned flow is one of the auto flows.

2.4.3. Column flow

Children of the multi-column element are placed in the element's column flow. The column boxes are then implicitly associated with the element's ‘column flow’. In this model, multiple regions (column boxes) get their content from a single flow (the element's ‘column flow’, which is the content of the element).

The column flow is one of the auto flows.

2.4.4. Generated flow

In the CSS formatting model, when the ‘::before’ or ‘::after’ pseudo-elements have their content property set to one of ‘<string>’, ‘<uri>’, ‘<counter>’, ‘attr(<identifier>)’, ‘open-quote’, ‘close-quote’, ‘no-open-quote’ or ‘no-close-quote’, they create a generated flow which they format visually.

2.5. Relation to document events

The CSS Region module does not alter in any way the normal processing of events in the document tree. In particular, if an event occurs on an element that is part of a named flow, the event's bubble and capture phases happen following the document tree order.

<script>
var region = ...; // get DOM reference to region

region.addEventListener('click', function (evt) {
    alert('I was able to capture an event from the flow content!');
}, true /* useCapture */);  
       
region.addEventListener('click', function (evt) {
    alert('I was able to see an event bubble from the flow content!');
}, false /* useCapture */);         
        

3. Properties and Rules

The main CSS Regions module properties are the ‘flow’ and ‘content’ properties. The ‘flow’ property places an element into a specific named flow or lets the automatic flow assignment take place. The ‘content’ property binds a region with a flow. When multiple regions are bound to the same flow, the ‘content-order’ property determines the order in which content flows into the sequence of regions. This sequences of regions is called a region chain.

The way in which the content is broken into segments that fit in a region can be controlled by the “break” properties. Finally, styling that is unique to the region can be specified by ‘region-style’ rules.

3.1. The ‘flow’ property

The ‘flow’ property places an element into a named flow or automatically places it in the appropriate flow (see the Visual Formatting Model and Flows section). Elements that belong to the same flow are laid out in the regions associated with that flow.

auto

The element is automatically moved to the appropriate flow according to the Visual Formatting Model and Flows definitions.

<string>

The element is placed (appended) to the flow with that name. The element is said to have a specified flow.

A named flow needs to be associated with one or more regions for its elements to be visually formatted. If no region is associated with a given named flow, the elements in the named flow are not rendered: they do not generate boxes and are not displayed.

The children of an element with a specified flow may themselves have a specified flow.

If an element has a the same specified flow value as one of its ancestors, it is moved out of its parent's normal flow and becomes a sibling of it's ancestor for the purpose of layout in the regions taking content from this flow.

The ‘flow’ property does not affect the CSS cascade and inheritance for the elements on which it is specified. The flow property affects the visual formatting of elements associated to a named flow and of regions getting their content from a named flow.

The containing block for absolutely positioned descendants of an element with a specified flow is the region into which the element is rendered.

All the elements participating inside a named flow are rendered as children of an anonymous block that spans across all the regions associated with the specified named flow. The elements flowed inside the same named flow are taken in document order.

Regions create a new stacking context, but inherit the floats that are already defined by the parent context.

<style>
#float {
    float: left;
    width: 100px;
    height: 300px;
}

#region1, #region2 {
    width: 200px;
    height: 200px;
    content: from-flow(body_text);
}

#content {
    flow: body_text;
}
</style>

<div id="float"></div>

<div id="region1"></div>
<div id="region2"></div>

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

3.2. The ‘content’ property

This specification extends the definition of the ‘content’ property and makes it applicable to all block elements and pseudo-elements.

none

For ‘::before’ and ‘::after’ pseudo-elements, the pseudo-element is not generated. For other elements, the element will not get any content for its visual formatting. If the children of the element are not directed to a flow referenced by another region, then they are not visually formatted. An element with its value set to ‘none’ is said to be disconnected

normal

Computes to ‘none’ for the ‘::before’ and ‘::after’ pseudo-elements. For other elements, the element uses the flow assigned to its children following the automatic flow assignment for the Visual Formatting Model..

<string>

Text content (see the section on strings).

<uri>

The value is a URI that designates an external resource (such as an image). If the user agent cannot display the resource it must either leave it out as if it were not specified or display some indication that the resource cannot be displayed.

<counter>

Counters may be specified with two different functions: ‘counter()’ or ‘counters()’. The former has two forms: ‘counter(name)’ or ‘counter(name, style)’. The generated text is the value of the innermost counter of the given name in scope at this pseudo-element; it is formatted in the indicated style (‘decimal’ by default). The latter function also has two forms: ‘counters(name, string)’ or ‘counters(name, string, style)’. The generated text is the value of all counters with the given name in scope at this pseudo-element, from outermost to innermost separated by the specified string. The counters are rendered in the indicated style (‘decimal’ by default). See the section on automatic counters and numbering for more information. The name must not be ‘none’, ‘inherit’ or ‘initial’. Such a name causes the declaration to be ignored.

open-quote and close-quote

These values are replaced by the appropriate string from the ‘quotes’ property.

no-open-quote and no-close-quote

Introduces no content, but increments (decrements) the level of nesting for quotes.

attr(X)

This function returns as a string the value of attribute X for the subject of the selector. The string is not parsed by the CSS processor. If the subject of the selector does not have an attribute X, an empty string is returned. The case-sensitivity of attribute names depends on the document language.

from-flow(<string>)

The element will visually format the available elements in the named flow with name <string>. If there is no flow with name <string>, then the element is disconnected and does not format any children visually. Multiple elements may be associated with the same named flow. See the ‘content-order’ property discussion to understand how content segments are associated with different regions.

3.3. The ‘content-order’ property

Defines the ordering of the chain of regions into which content flows. If region A and region B are in the same chain of regions and the ‘content-order’ of region A is lower than that of region B, then region A will precede region B in that chain: content will flow into region A before it flows into region B.

<float>

Specifies the region's priority in the chain it belongs to, i.e.., the chain of regions associated with the same content flow. Negative values are allowed.

If two or more regions with the same ‘from-flow( <name>)’ value for their ‘content’ property, they are first sorted according to their ‘content-order’ value. If multiple regions in have the same ‘content-order’ value, they are sorted according to the document order.

3.4. Region flow break properties: ‘break-before’, ‘break-after’, ‘break-inside’

When content is laid out in multiple regions, the user agent must determine where content breaks occur. The problem of breaking content into segments fitting in regions is similar to breaking content into pages or columns.

Each break ends layout in the current region and causes remaining pieces of content from the named flow to be visually formatted in the following region, in the order defined by the ‘content-order’ computed values. Note that there is no region break in the last region associated with a named flow.

The following extends the ‘break-before’, ‘break-after’ and ‘break-inside’ properties from the [CSS3COL] specification to account for regions. The additional values are described below.

These properties describe page, column and region break behavior before/after/inside the generated box. These values are normatively defined in [CSS3COL]:

auto

Neither force nor forbid a page/column break before (after, inside) the generated box.

always

Always force a page break before (after) the generated box.

avoid

Avoid a page/column break before (after, inside) the generated box.

left

Force one or two page breaks before (after) the generated box so that the next page is formatted as a left page.

right

Force one or two page breaks before (after) the generated box so that the next page is formatted as a right page.

page

Always force a page break before (after) the generated box.

column

Always force a column break before (after) the generated box.

avoid-page

Avoid a page break before (after, inside) the generated box.

avoid-column

Avoid a column break before (after, inside) the generated box.

This specification adds the following new values:

region

Always force a region break before (after) the generated box.

avoid-region

Avoid a region break before (after, inside) the generated box.

When a break splits a box, the box's margins, borders, and padding have no visual effect where the split occurs. However, the margin immediately after a forced page/column/region break will be preserved. A forced page/column/region break is a break that does not occur naturally.

Note: When the ‘avoid’ value is used, regions may overflow. In that case the ‘overflow’ property specified on the region element should be used to determine how to render the overflow.

3.5. The region-overflow property

The ‘region-overflow’ property controls the behavior of the last region associated with a named flow.

auto

Content flows as it would in a regular content element. If the content exceeds the container box, it is subject to the overflow property's computed value on the region element.

break

If the content fits within the region element, then this property has no effect. If the content does not fit within the region element, the content breaks as if flow was going to continue in a subsequent region. See the breaking rules section.

The following code sample illustrates the usage of the ‘region-overflow’ property.

<style>
#article {
    flow: "article";
}

#region_1, #region_2 {
    content: from-flow(article);
    region-overflow: break; /* or none */
    overflow: visible; /* or hidden */
}

</style>

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

<div id="region_1"></div>
<div id="region_2"></div>
        

‘flow: "article"’	region_1 and region_2	‘region-overflow: auto’ ‘overflow:visible’
	‘region-overflow: break’	‘region-overflow: auto’ ‘overflow:hidden’

Different values for the region-overflow property

3.6. The @region rule

An ‘@region’ rule contains style declarations specific to particular regions.

The ‘@region’ rule consists of the keyword ‘@region’ followed by a selector and a declarations block. The ‘@region’ rule and the selector constitute the region's ‘flow segment’ selector. The region's flow segment selector specifies which range of elements in the flow are subject to the following declaration blocks: it applies to the range (see [DOM-LEVEL-2-TRAVERSAL-RANGE]) from the region's flow that flow in the selected region(s).

Only elements that are fully in the ‘flow segment’ may match any of the selectors found in the style rule. If an element is split across regions, it will not be subject to region styling in any of the regions it is part of. However, it's children element or pseudo-elements may be.

In addition, the ‘::region-lines’ pseudo-element can be used to select the inline content of an element that falls into a particular region.

@region <selector> {
    ... CSS styling rules ...
}          

In the following example, the named flow ‘article_flow’ flows through ‘region_1’ and ‘region_2’.

<style>
    #div_1 {
        flow: "article_flow";
    }
    
    <region1_sel>, <region2_sel> {
        content: from-flow(article_flow);
    }

    /* region style RSA */
    @region <region1_sel>, <region2_sel> {
        p::region-lines {...}
        div {...}
        p {...}
    }
    
    /* region style RSB */
    @region <region1_sel> {
        p {...}
        #p_2::region-lines {...}
    }
        
</style>

<div id="div_1">
    <p id="p_1">...</p>
    <p id="p_2">...</p>
</div>

        

•  div div_1
•  paragraph p_1
•  paragraph p_2
•  range of flow that fits into region_1
•  range of flow that fits into region_2

The region style ‘RSA’ applies to flow content that fits in either ‘region_1’ or ‘region_2’.

The first rule set ‘p::region-lines {...}’ uses the ‘::regions-line’ pseudo-element. Since all the content is fitted in either ‘region_1’ or ‘region_1’, this rule set applies to all content lines.

The second rule set ‘div {...}’ applies to all <div> elements that fit fully into ‘region_1’ or ‘region_2’. In our example, there is no <div> in the flow that fits fully in a region, because div_1 is split between ‘region_1’ and ‘region_2’.

The third rule set ‘p {...}’ applies to all <p> elements that fit fully into ‘region_1’ or ‘region_2’. In our example, only p_1 fully fits in a region, ‘region_1’.

The region style ‘RSB’ applies to flow content that fits in ‘region_1’.

The first rule set ‘p {...}’ matches p_1 because that paragraph fully fits in ‘region_1’.

The second rule set ‘#p_2::region-lines {...}’ matches lines in p_2 that flow into ‘region_1’. These lines will be subject to the additional style.

The specificity of the selectors in a ‘@region’ rule is calculated as defined in the CSS Selectors module (see [SELECT]). In other words, the ‘@region’ rule adds an extra condition to the selector's matching, but does not change the selector's specificity. This is the same behavior as selectors appearing in ‘@media’ rules declaration blocks (see [MEDIAQ]), where the rule does not influence the selectors' specificity.

Consequently, selectors that match a given element (as describe above), participate in the CSS Cascading order as defined in [CSS21].

4. CSSOM View and CSS Regions

Since content may flow into multiple regions, authors need a way to determine if there are enough regions to flow all the content from a named flow. This is especially important considering that the size of regions may change depending on the display context. For example, flowing the same content on a mobile phone with a small screen may require more regions than on a large desktop display.

Here is another example where creating more regions might be needed. If the user may change the font size of text flowing through regions, new regions may be needed to accommodate for the additional space required to fit the larger text or some may need to be removed for smaller text.

The CSS OM View ([CSSOM-VIEW]) specification defines extensions to the Element interface that would let an author find out if the last region overflows its content boundaries (by comparing its ‘scrollHeight’ with its ‘contentHeight’). However, this assumes the region is a document element, which may not always be the case. For example, as described in a later section, a grid cell (see [CSS3-GRID-LAYOUT]) may be a region, but it is a pseudo-element, not an document element. Therefore, it is not possible to access its ‘scrollHeight’ or ‘contentHeight’.

4.1. The NamedFlow interface

This specification adds a method to the Document interface to access the document's named flow instances.

[Supplemental] interface Document {
  NamedFlow flowWithName(DOMString name);
};               

The NamedFlow interface offers a representation of the named flow.

interface NamedFlow {
  readonly attribute boolean overflow;
};    
    

The overflow property is true if the named flow does not fully fit in the associated regions. Otherwise, it is false.

With the NamedFlow interface, authors can easily check if all content has been fitted into existing regions. If it has, the overflow property would be true.

4.2. Extension to the Element interface

When an region is an actual element, it is convenient to easily find out if content fully fits into the region or not. The supplemental interface on Element provides that functionality.

[Supplemental] interface Element {
    readonly attribute DOMString regionOverflow;
    readonly Range[] flowRanges;
};               
    

The regionOverflow attribute can take one of the following values:

overflow

the region element's content overflows the region's content box. Note that the region's overflow property value can be used to control the visibility of the overflowing content. This means that the region is the last one in the region chain and not able to fit the remaining content from the named flow.

fit

the region element's content fits into the region's content box. It does not overflow. If the region is the last one in the region chain, it means that the content fits without overflowing. If the region is not the last one in the region chain, that means the named flow content is further fitted in subsequent regions. In particular, in this last case, that means the region may have received no content from the named flow (for example if the region is too span to accommodate any content).

empty

the region element has no content and is empty. All content from the named flow was fitted in regions with a lower ‘content-order’ value.

If an element is not a region, then the contentOverflow attribute value is ‘fit’.

The flowRanges attribute is an array of Range instances corresponding to the content from the region flow that is positioned in the region.

If an element is not an region, then the flowRanges attribute returns an array with a single Range matching the element's full content.

5. Integration with other specifications

This specification does not specify how regions are created or laid out. This section illustrates how regions can be crated and laid out with other specifications. It first defines the requirements for integrating CSS Regions. Then it provides examples for different existing solutions.

5.1. Region requirements

For a container element (or pseudo-element) to become a region, it must be selectable with a CSS selector and accept the content property as defined in this specification.

5.2. Integration Examples

Authors can use different methods to layout regions in CSS. Some solutions can be expressed with CSS only and not require document changes, some solutions leverage the document tree. The following examples illustrate these different options.

5.2.1. CSS Grid Layout

The CSS Grid Layout specification (see [CSS3-GRID-LAYOUT]) defines a grid-cell pseudo-element selector for grid cells. Consequently, grid cells can be a region.

The following example shows how CSS Grid Layout could be use to create regions and position them to create the example given in the introduction.

<style>
body:before {
    display: grid;
    grid-template: "aae"
                   "bbe"
                   "cde";
}

body:before::grid-cell(a) {
    content: url('illustration.png');
}

body:before::grid-cell(b),
body:before::grid-cell(c),
body:before::grid-cell(d),
body:before::grid-cell(e) {
    content: from-flow('article_flow');
}
</style>

5.2.2. CSS Multi-Column Layout

The CSS Multi-Column Layout (see [CSS3COL]) does not specify a selector for column regions.

The CSS Multi-Column specification could offer a pseudo-element selector (e.g., called ‘nth-column’) for its column boxes. This would enable different content to flow through different columns. The following example illustrates how two different content flows could be threaded on alternate columns.

<style>
body:before {
    columns: 4;
}

body:before::nth-column(even) {
    content: from-flow('article_1_flow');
}

body:before::nth-column(odd) {
    content: from-flow('article_2_flow');
}
</style>

<body>
    <div id="article_1">...</div>
    <div id="article_2">...</div>
</body>

Note that if a column box becomes associated with a flow by its content property, it is no longer associated to the ‘column flow’, as discussed before. For example, if the second column in a multi column element was associated with the ‘illustration’ named flow, the regular ‘column-flow’ would thread through the first and third column while column two would flow content from the ‘illustration’ named flow.

5.2.3. CSS Visual Formatting

CSS (see [CSS21]) offers a way to visually format content with different layout schemes: inline and block formatting, float, absolute positioning, relative positioning or table layout.

Elements laid out using these schemes can be regions, as illustrated below, using absolutely positioned elements for simplicity.

<style>
#article {
    flow: article_flow;
}

#region_1, #region_2, #region_3, #region_4 {
    content: from-flow(article_flow);
}

#region_1 {
    /* positioning properties */
}

/* ... positioning of other regions ... */

</style>
<html>
    <body>
        <div id="article">...</div>
        <div id="region_A"></div>
        <div id="region_1"></div>
        <div id="region_2"></div>
        <div id="region_3"></div>
        <div id="region_4"></div>
    </body>
</html>
  

6. Relation to other specifications

This specification is related to other specifications as described in the references section. In addition, it is related to the following specifications:

1. CSS Exclusions Module [CSS3-EXCLUSIONS]. This module defines a generic way to define arbitrarily shaped exclusions into which content can flow or around which content can flow. This can be seen as an extension to the way CSS floats provide rectangular areas into which content flows and around which content flows. In advanced layout designs, it is expected that the CSS Exclusions module will be commonly combined with the CSS Regions module.
2. CSS Line Grid Module [CSS3-LINE-GRID]. This module defines a concept of line grid to align the position of lines in different elements. The line grid functionality is related and needed for aligning content flowing in separate regions.

7. Conformance

Acknowledgments

References

Normative references

[CSS21]

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-CSS2-20110607

[CSS3COL]

Håkon Wium Lie. CSS Multi-column Layout Module. 12 April 2011. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2011/CR-css3-multicol-20110412

[SELECT]

Tantek Çelik; et al. Selectors Level 3. 15 December 2009. W3C Proposed Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/PR-css3-selectors-20091215

Other references

[CSS3-EXCLUSIONS]

Vincent Hardy. CSS Exclusions Module. Proposal for a CSS module. (Retrieved 11 May 2011) URL: http://dev.w3.org/csswg/css3-exclusions/

[CSS3-GRID-LAYOUT]

Alex Mogilevsky; et al. Grid Layout. 7 April 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-css3-grid-layout-20110407

[CSS3-LINE-GRID]

Koji Ishii. CSS Line Grid Module. Proposal for a CSS module. (Retrieved 11 May 2011) URL: http://dev.w3.org/csswg/css-line-grid/

[CSS3PAGE]

Håkon Wium Lie; Melinda Grant. CSS3 Module: Paged Media. 10 October 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-page-20061010

[CSSOM-VIEW]

Anne van Kesteren. CSSOM View Module. 4 August 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-cssom-view-20090804/

[DOM-LEVEL-2-TRAVERSAL-RANGE]

Joe Kesselman; et al. Document Object Model (DOM) Level 2 Traversal and Range Specification. 13 November 2000. W3C Recommendation. URL: http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113

[MEDIAQ]

Håkon Wium Lie; et al. Media Queries. 27 July 2010. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2010/CR-css3-mediaqueries-20100727/

Index

• auto flows, 2.4.
• break-after, 3.4.
• break-before, 3.4.
• break-inside, 3.4.
• column flow, 2.4.3.
• content, 3.2.
• content-order, 3.3.
• current-region, 2.3.1.
• disconnected, 3.2.
• flow, 3.1.
• flowRanges, 4.2.
• from-flow(<string>), 3.2.
• generated flow, 2.4.4.
• grid cell flow, 2.4.3.
• NamedFlow, 4.1.
• none, 3.2.
• normal flow, 2.4.1.
• overflow, 4.1.
• positioned-flow, 2.4.2.
• region, 2.2.
• region chain, 3.
• regionOverflow, 4.2.
• region-overflow, 3.5.
• specified flow, 3.1.

Property index