Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
The CSS regions module allows content to flow across multiple areas called regions. The regions are not necessarily contiguous in 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.
This document uses an experimental style sheet. We welcome your feedback on the styles at site-comments@w3.org.
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 draft is related to the drafts about Multi-column Layout [CSS3COL], Grid Layout [CSS3GRID], Flexible Box Layout [CSS3-FLEXBOX], and Template Layout [CSS3LAYOUT].
This section is non-normative.
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.
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>
And the following snippet shows an example of elements that will be used as regions.
<div id="region1"></div>
<div id="region2"></div>
<div id="region3"></div>
<div id="region4"></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
The CSS regions module is independent of the layout of regions and the mechanism used to create them. However, for simplicity, our example uses elements as regions as shown in the previous code snippet.
The following code example illustrates how the content of the
article element becomes a flow and how the areas ‘region1’, ‘region2’, ‘region3’ and ‘region4’ become regions that consume the
‘article_flow’ content.
<style>
#article {
flow-into: article_flow;
}
#region1, #region2, #region3, #region4 {
flow-from: article_flow;
}
</style>
The ‘article_flow’ value on the
‘flow-into’ property directs the
‘#article’ element to the ‘article_flow’ named flow. Setting the elements'
‘flow-from’ property to ‘article_flow’ on elements makes them regions and
associates these regions with the named flow: the flow is ‘poured’ into the desired regions.
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 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;
display: run-in;
}
/*
* Additional styling to apply to content when it falls into
* region1
*/
@region #region1 {
#article {
font-weight: bold;
color: #0C3D5F;
font-size: larger;
}
#article h1 {
color: crimson;
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.
Different rendering with a different region styling
This section is non-normative.
A region is an element that generates
a block
container box and has an associated named
flow (see the ‘flow-from’ property).
There was a recent discussion on intrinsic sizing of regions which has not been resolved
.A named flow is the ordered sequence of elements associated with a flow with a given identifier. Elements in a named flow are ordered according to the document order.
Elements are placed into a named flow with the ‘flow-into’
property. The elements in a named flow are laid out in the chain of
regions that are associated with this named flow. Regions are organized in to a region chain according to the document order.
Content from a named flow is broken up between regions according to the regions flow breaking rules.
Breaking a named flow across multiple regions is similar to breaking a document's content across multiple pages (see [CSS3PAGE]) or a multi-column element's content across column boxes (see [CSS3COL]). One difference is that page boxes are generated based on the available content whereas regions are a predefined set of recipient boxes for the named flow content.
Regions are organized in to a region chain.
Each region in turn consumes content from its associated named flow. The named flow content is positioned
in the current region
until a natural or forced region break occurs, at which point the current region becomes the
next one in the region chain. If there are
no more regions 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.
This section is normative.
The CSS regions module does not alter 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.
This section is normative.
flow-into’
propertyThe ‘flow-into’ property can place an element into a named flow. Elements that belong to the same flow are laid out in the regions associated with that flow.
| Name: | flow-into |
|---|---|
| Value: | <ident> | none | inherit |
| Initial: | none |
| Applies to: | any element |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | as specified |
<ident>’. The element is said to have a specified flow. The values ‘none’, ‘inherit’, ‘default’, ‘auto’ and ‘initial’ are invalid flow names.
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 the same specified flow as one of its ancestors, it becomes a sibling of it's ancestor for the purpose of layout in the regions laying out content from that flow.
The ‘flow-into’ property does not affect the
CSS cascade and inheritance for the elements on which it is specified. The
‘flow-into’ property affects the visual
formatting of elements placed into a named flow and of regions laying out
content from a named flow.
The edges of the first region in a region chain associated with a named flow establish the rectangle that is the initial containing block of the named flow.
The first region defines the writing mode for the entire flow. The writing mode on subsequent regions is ignored.
Elements in a named flow are sequenced in document order.
This note is informative.
The ‘flow-into’ property moves an element into
the flow and the interplay with selectors should be considered carefully.
For example,
table {flow-into: table-content}
will move all tables in the ‘table-content’ named flow. However, the
table * {flow-into: table-content}
selector will move all the descendants of table elements in the
‘table-content’ named flow. This
will make all the descendants of table elements siblings in the named
flow. Having the descendants become siblings in the named flow results in
a different processing (see the CSS
2.1‘s anonymous table objects). This
note illustrates how authors must exercise caution when choosing a
particular selector for setting the ’flow-into' property to avoid
unintended results.
The ‘flow-into’ property does not apply to the
::first-line and ::first-character.
The effect of ‘flow-into’ on generated content such as
::marker, ::before and ::after is undefined. This may change depending on
implementation feedback.
flow-from’
propertyThe ‘flow-from’ property makes an element a
region and associates it with a named flow.
| Name: | flow-from |
|---|---|
| Value: | <ident> | none | inherit |
| Initial: | none |
| Applies to: | Elements that generate a block
container box. This might be expanded in future versions of the specification to allow other types of containers to receive flow content. |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | as specified |
content’ property
computes to something else than ‘normal’, the element does not become a
region. If the ‘content’ property
computes to ‘normal’, then the
element becomes a region and is ordered in a region
chain according to its document order. The content from the flow
with the <ident>
name will be broken into segments and
visually formatted in the principal
boxes of the regions in the region chain. If there is no flow with
name <ident>, then the element does not format any content
visually. A region's document children are not visually formatted unless they are directed to a named flow referenced by one or more regions.
An element becomes a region when its ‘flow-from’ property is set to a valid
<ident> value, even if there is no content contributing to the
referenced flow. For example:
<style>
.article{
flow-into: thread;
}
.region{
flow-from: thread;
}
</style>
<html>
<body>
<div class=region>div content</div>
</body>
</html>
There is no element matching the .article selector and
therefore no content in the thread flow. However, the element
matching the .region selector is still associated with that
empty named flow and, consequently, its children are not formatted
visually.Regions create a new stacking context. Regions establish a new block formatting Context.
If the ‘content’ property is
defined on a region, it has no effect on the region's visual formatting.
This note is informative.
With regions, an element may be split across multiple regions and these regions may overlap (for example if they are absolutely positioned). So fragments of the same element can overlap each other. Since each element has a single z-index, it would be required to find another mechanism to decide in which order the fragments are rendered. Since each region creates a new stacking context, it is clear that each region is rendered separately and their rendering order follows the regular CSS rendering model.
Floats or other exclusions (see [CSS3-EXCLUSIONS]) potentially impact the content laid out in regions, just as for non-regions.
In the following example, the inline content coming from the body_text named flow wraps
around the #float box.
<style>
#float {
float: left;
width: 100px;
height: 300px;
}
#region1, #region2 {
width: 200px;
height: 200px;
flow-from: body_text;
}
#content {
flow-into: body_text;
}
</style>
<div id="float"></div>
<div id="region1"></div>
<div id="region2"></div>
<div id="content"></div>
If a region's ‘width’ property
is computed to ‘auto’, its
resolved value is computed based on the region's ::before and
::after generated content only.
If a region's ‘height’ property
is computed to ‘auto’, its
resolved value is computed based on the region's ::before and
::after generated content only.
break-before’, ‘break-after’,
‘break-inside’User agents laying out content in multiple regions 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 region chain. 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.
| Name: | break-before |
| Value: | auto | always | avoid | left | right | page | column | region | avoid-page | avoid-column | avoid-region |
| Initial: | auto |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | paged |
| Computed value: | specified value |
| Name: | break-after |
| Value: | auto | always | avoid | left | right | page | column | region | avoid-page | avoid-column | avoid-region |
| Initial: | auto |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | paged |
| Computed value: | specified value |
| Name: | break-inside |
| Value: | auto | avoid | avoid-page | avoid-column | avoid-region |
| Initial: | auto |
| Applies to: | block-level elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | paged |
| Computed value: | specified value |
These properties describe page, column and region break behavior before/after/inside the generated box. These values are normatively defined in [CSS3COL]:
This specification adds the following new values:
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.
| Name: | region-overflow |
| Value: | auto | break |
| Initial: | auto |
| Applies to: | region elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | paged |
| Computed value: | specified value |
The ‘region-overflow’ property controls the
behavior of the last region associated with a named flow.
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. A forced region break takes precedence over a natural break point.
Flow content that follows the last break in the last region, if any is not rendered.
The ‘region-overflow’ property does not
influence the size of the region it applies to.
The following code sample illustrates the usage of the ‘region-overflow’ property.
<style>
#article {
flow-into: "article";
}
#region_1, #region_2 {
flow-from: 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-into: "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
The ‘overflow’ property is honored on a
region: if region content overflows, such as the borders of elements on
the last line, the ‘overflow’ property controls the
visibility of the overflowing content. See the ‘overflow’ property definition ([CSS21]).
An ‘@region’ rule contains style
declarations specific to particular regions.
@region <selector> {
... CSS styling rules ...
}
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 flows in the selected region(s).
Elements that are fully or partially in the ‘flow
segment’ may match any of the selectors found in the style
rule.
Only a limited list of properties can be set in a region style rule:
word-spacing’
letter-spacing’
text-decoration’
text-transform’
line-height’
text-shadow’ property
box-shadow’ property
box-decoration-break’ property
width’ property
In the following example, the named flow ‘article_flow’ flows through ‘region_1’ and ‘region_2’.
<style>
#div_1 {
flow-into: article_flow;
}
<region1_sel>, <region2_sel> {
flow-from: article_flow;
}
/* region style RSA */
@region <region1_sel>, <region2_sel> {
div {...}
p {...}
}
/* region style RSB */
@region <region1_sel> {
p {...}
}
</style>
<div id="div_1">
<p id="p_1">...</p>
<p id="p_2">...</p>
</div>
The region style ‘RSA’ applies to
flow content that is laid out in either ‘region_1’ or ‘region_2’.
The first rule set ‘div {...}’
applies to all <div> elements that fit
partially or fully into ‘region_1’ or
‘region_2’. div_1 is split between ‘region_1’ and ‘region_2’ and gets the style from this style rule.
The second rule set ‘p {...}’
applies to all <p> elements that fit into
‘region_1’ or ‘region_2’. In our example, both p_1 and p_2 are selected.
The region style ‘RSB’ applies to
flow content that fits in ‘region_1’.
The first rule set ‘p {...}’ matches
p_1 and p_2 because these
paragraphs flow into ‘region_1’. Only
the segment of p_2 that flows into region_1 is styled with this rule.
Making issue stale because this issue has not been raised on the mailing list and we will wait for implementation feedback. Is the proposed restriction that elements are only selected selector in a rule set appearing in an @region rule sufficient?
first-line’ precedent is
underspecified and that more specification is needed in addition to
referencing the existing precedent.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].
A’ receives content from a
flow that contains region ‘B’, the
content that flows into ‘B’ does
not receive the region styling specified for region ‘A’.This section is normative.
It can be useful to visually mark the content to highlight that a
content thread is flowing from region to region. For example, a marker
such as ‘continues on page 3’
clearly indicates, at the end of a region, that there is more content in
the flow which can be found on ‘page 3’
(in this example, the notion of page is application specific).
The ‘::before’ and ‘::after’ pseudo-elements (see [SELECT]) let content authors mark
the beginning and end of a region with such markers.
The ‘::before’ content is laid out in
the region prior to any other content coming from the flow. Note that it
is possible to set the ‘::before’
pseudo-element's ‘display’
property to ‘run-in’ to align it
with the content's inline boxes.
The ‘::after’ content is laid out in
the region after laying out the flow content. Then, flow content is
removed from the region to accommodate for the ‘::after’ content. Accommodating means that the
‘::after’ content is laid out without
overflowing the region. If there is still not enough room to accommodate
for the ‘::after’ content after
removing all flow content, then the ‘::after’ content overflows. The ‘display’ property of the ‘::after’ content should be set to ‘run-in’ to align with the region's content's
inline boxes. In that case, the ‘::after’ content becomes the last inline box of the
previous element in the flow that has some visual rendering in the region
and can accommodate for the ‘::after’
box.
This section is normative.
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.
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 regions may need to be removed for smaller text.
Since an element may be split into multiple regions, invoking getClientRects
on it must return the list of rectangles for the element in all the
regions it is part of.
The getFlowByName method on the Document interface provides access to the document's
named flow instances.
[Supplemental] interface Document {
NamedFlow
getFlowByName(DOMString name);
};
The NamedFlow
interface offers a representation of the named
flow.
interface NamedFlow {
readonly attribute boolean overflow;
readonly attribute NodeList contentNodes;
NodeList getRegionsByContentNode(Node node);
};
};
The overflow
property is true if the named flow does not fully fit in the associated
regions. Otherwise, it is false. A NamedFlow object is live.
The contentNodes property returns an ordered collection of nodes that constitute the named flow. Note that this collection is live: every time it is queried it must return the same object, and the object is always up to date.
The getRegionsByContentNode() method gets a collection of regions that contain at least part of the target content node. This can be used to navigate by bookmark in paginated view: the method returns regions containing the bookmarked element, which are then passed to pagination UI to show desired region or page.
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 false.
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;
getter Range[] getRegionFlowRanges();
};
The regionOverflow attribute can take one of the
following values:
overflow’
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’
empty’
undefined’
The getRegionFlowRanges method returns an array of Range instances corresponding to the content from the region flow that is positioned in the region.
If an element is not a region, the getRegionFlowRanges
method throws a DOMException with the INVALID_ACCESS_ERR error code.
ACTION-350 was created to add the API to the specification draft.
It has been suggested
to add an API to find which region displays an element in a named flow.
Should we add such an API? How would it work in a ‘multi-view’ context as suggested by Alex.
Region Event
Targets dispatch regionLayoutUpdate events when
there is a possible layout change of their named flow segment.
| Type | regionLayoutUpdate
|
|---|---|
| Interface | UIEvent
|
| Sync / Async | Async |
| Bubbles | Yes |
| Target | Element
|
| Cancelable | Yes |
| Default action | none |
| Context info |
|
This specification is related to other specifications as described in the references section. In addition, it is related to the following specifications:
Use cases are described on this page.
content-order’ a
<integer> and not a <float> following a working group resolution
none’, ‘inherit’ and ‘initial’ from the possible identifier names
on the flow property following discussion
on the mailing list.
flow-into’ property interacts with
object, embed and iframe elements.
default’ from the
possible identifier names on the flow property because it may
get reserved.
auto’ on ‘region-overflow’ specifying that region
breaks must be ignored.
Document.flowWithName’ to
‘Document.getFlowByName’ since it is
not a property.
NamedFlow’ instance is live.
undefined’ string
value to the regionOverflow property on the Element interface extension.
Event’ in the event name.
flow’ to ‘flow-into’
following working group resolution.
from-flow’ to
‘flow-from’ following a working group resolution.
content:
flow-from()’ to block container box and added a note that
this might be expanded in the future, following a working group resolution.
flow’ property
description, removed the required wrapper anonymous block as agreed on mailing
list discussion.
flow-into’
property following a mailing
list discussion.
content:flow-from(<ident>)’ with
‘flow-from: <ident>’ following a
working group
resolution.
::before’ and ‘::after’ and explain how ‘display:run-in’ works with regions.
region-order’
property following implementation feedback.
auto’ to the list of
invalid flow identifiers.
none’ the initial value
for ‘flow-into’ and aligned with ‘flow-from’, as
explained in this email.
Also allowed the ‘inherit’ value
on ‘flow-from’ and ‘flow-into’ (same
email).
content’ property computes to normal,
following the resolution of Issue
22.
The editors are grateful to the CSS working group for their feedback and help with the genesis of this specification.
In addition, the editors would like to thank the following individuals for their contributions, either during the conception of CSS regions or during its development and specification review process:
NamedFlow, 6.1.
overflow,
6.1.
regionOverflow, 6.2.