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 is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as 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 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>
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.
<style> #article { flow-into: article_flow; } <region1_sel>, <region2_sel>, <region3_sel>, <region4_sel> { 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
’ 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_sel> { #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
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> | auto |
Initial: | auto |
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
’ 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 a the same specified flow value as one of its ancestors, it becomes a sibling of it's ancestor for the purpose of layout in the regions laying out content 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.
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.
If the ‘flow-into’ property is specified on an <iframe>
, an <object>
or a <embed>
element, the ‘display’ property is
computed to ‘none’ and the referenced document within the element is
used as the named flow. In the case of the <object>
element if fallback occurs and the
fallback element has a referenced document then that document is used as
the named flow, otherwise the fallback element itself is added to the
named flow.
Any properties set on the <iframe>
/<object>
/<embed>
elements (including margin, border, padding, background) have no effect.
This redirection of content does not change representation of the elements
in the document tree, just as for any other source of named flow; in this
case the <iframe>
still provides security
checks for script in content (and sandbox if required). Events and CSS
cascading work the same way as in a documents hosted in regular <iframe>
s.
Region styling applies to content coming from <iframe>
/<object>
/<embed>
sources the same way it applies to other flow content.
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: | none | <ident> |
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 |
Note that a region's document children are not visually formatted unless they are directed to a named flow referenced by one or more regions.
Third resolution on Regions at the Seattle Face to Face meeting, July 2011. Superseded by resolution during
content: flow-from(<flow-name>) v.s. flow-from: <flow-name>
WG Conference Call, CSSWG Minutes and Resolutions 2011-06-15.
See issue
NOTE: stale issue because the spec. now contains a way to address these requirements.
Should we consider adding the ability to do the following:
...
") at the region
breaking points to indicate that content has been broken out and is
continuing on a different region.First resolution on Regions at the Seattle Face to Face meeting, July 2011
‘content: flow-from(<ident>)
’
moves an element to a named flow. Should we allow the content to be
copied to a flow instead of moved to a flow. For example:
would keep ‘#quote_A
’ in the normal
flow but also copy its content to the ‘quotes
’ flow. This essentially clones the node and
raises questions regarding DOM access, CSSOM view and the computed style.
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 [[CSS3EXCLUSIONS]]) 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 width is ‘0
’.
If a region's ‘height
’ property
is computed to ‘auto
’, its height
is computed as described in the Computing
heights and margins section of the CSS 2.1 specification (see [CSS21]) where:
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.
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.
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
@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-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].
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
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; };
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.
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:
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.
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.