CSS Fragmentation Module Level 3

Abstract

This module describes the fragmentation model that partitions a flow into pages. It builds on the Page model module and introduces and defines the fragmentation model. It adds functionality for pagination, breaking variable fragment size and orientation, widows and orphans.

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-break” in the subject, preferably like this: “[css3-break] …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 the first public Working Draft of this module.

Table of contents

• 1. Introduction
  • 1.1. Module Interactions
  • 1.2. Values
• 2. Fragmentation Model and Terminology
• 3. Controlling Breaks
  • 3.1. Forced breaks and keep-together: the ‘break-before’, ‘break-after’, ‘break-inside’ properties
  • 3.2. Breaks inside elements: ‘orphans’, ‘widows’
• 4. Rules for Breaking
  • 4.1. Possible Break Points
  • 4.2. Types of Breaks
  • 4.3. Forced breaks
  • 4.4. Unforced Breaks
  • 4.5. Optimizing Unforced Breaks
• 5. Box Model for Breaking
  • 5.1. Breaking into Varying-size Fragmenters
  • 5.2. Margins at Breaks
  • 5.3. Decorating Box Breaks
• 6. Conformance
  • 6.1. Document Conventions
  • 6.2. Conformance Classes
  • 6.3. Partial Implementations
  • 6.4. Experimental Implementations
  • 6.5. Non-Experimental Implementations
  • 6.6. CR Exit Criteria
• Acknowledgments
• References
  • Normative references
  • Other references
• Index
• Property index

1. Introduction

This section is not normative.

In paged media (e.g., paper, transparencies, photo album pages, pages displayed on computer screens as printed output simulations), as opposed to continuous media, the content of the document is split into one or more discrete display surfaces. In order to avoid awkward breaks (such as halfway through a line of text), the layout engine must be able to shift around content that would fall across the page break. This process is called pagination.

In CSS, in addition to paged media, certain layout features such as regions [CSS3-REGIONS] and multi-column layout [CSS3COL] create a similarly fragmented environment. The generic term for breaking content across containers is fragmentation. This module explains how content breaks across fragmenters such as pages and columns and how such breaks can be controlled by the author.

1.1. Module Interactions

This module replaces and extends the pagination controls defined in [CSS21] section 13.3 and in [CSS3PAGE].

1.2. Values

This specification follows the CSS property definition conventions from [CSS21]. Value types not defined in this specification are defined in CSS Level 2 Revision 1 [CSS21]. Other CSS modules may expand the definitions of these value types: for example [CSS3COLOR], when combined with this module, expands the definition of the <color> value type as used in this specification.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the inherit keyword as their property value. For readability it has not been repeated explicitly.

2. Fragmentation Model and Terminology

fragmented flow

A content flow that is being laid out in a fragmentation context, such as a multi-column element, a chain of CSS regions, or a paged media display.

fragmenter

A box—such as a page box, column box, or region—that contains a portion (or all) of a fragmented flow. Fragmenters can be pre-defined, or generated as needed. When breakable content overflows a fragmenter in the block dimension, instead of overflowing it breaks into the next container in its fragmentation context.

fragmentation context

An ordered series of fragmenters. A given fragmentation context can only have one block flow direction across all its fragmenters.

fragmentation

The process of splitting a content flow across the fragmenters that form a fragmentation context.

box fragment or fragment

The portion of a box that belongs to exactly one fragmenter. A box in continuous flow always consists of only one fragment. A box in a fragmented flow consists of one or more fragments.

Each fragmentation break (hereafter, break) ends layout of the fragmented box in the current fragmenter and causes the remaining content to be laid out in the next fragmenter, in some cases causing a new fragmenter to be generated to hold the deferred content. When multiple flows are laid out in parallel, fragmentation is performed independently in each flow.

Breaking a fragmenter F effectively splits the fragmenter into two fragmenters (F₁ and F₂). The only difference is that the type of break between the two pieces F₁ and F₂ is the type of break created by the fragmentation context that split F, not the type of break normally created by F's own fragmentation context.

Breaking inline content into lines is another form of fragmentation, and similarly creates box fragments when it breaks inline boxes across line boxes. However, inline breaking is not covered here; see [CSS3TEXT] and the ‘box-decoration-break’ property in [CSS3BG].

3. Controlling Breaks

The following sections explain how breaks are controlled in a fragmented flow. Five properties indicate where the user agent may or should break the content flow. In the case of pagination, the author can also specify on which page (left or right) the subsequent content should resume.

3.1. Forced breaks and keep-together: the ‘break-before’, ‘break-after’, ‘break-inside’ properties

These properties describe page/column/region break behavior before/after/inside the generated box. These values have the following meaning:

auto

Neither force nor forbid a break before/after/inside the principle box.

always

Always force a break before/after the principle box.

avoid

Avoid a break before/after/inside the principle box.

left

Force one or two page breaks before/after the principle box so that the next page is formatted as a left page.

right

Force one or two page breaks before/after the principle box so that the next page is formatted as a right page.

page

Always force a page break before/after the principle box.

column

Always force a column break before/after the principle box.

region

Always force a region break before/after the principle box.

avoid-page

Avoid a page break before/after/inside the principle box.

avoid-column

Avoid a column break before/after/inside the principle box.

avoid-region

Avoid a region break before/after/inside the principle box.

A potential page/column/region break location is typically under the influence of the parent element's ‘break-inside’ property, the ‘break-after’ property of the preceding element, and the ‘break-before’ property of the following element. When these properties have values other than ‘auto’, the forced break values (‘always’, ‘left’, ‘right’, ‘page’, ‘column’ and ‘region’) take precedence over the avoid break values (‘avoid’, ‘avoid-page’, ‘avoid-column’ and ‘avoid-region’). See the section on rules for breaking for the exact rules on how these properties affect forced breaks.

User Agents must apply these properties to block-level boxes and to table rows, table row groups, and—in the case of ‘break-inside’—block containers in the normal flow of the root fragmented element. User agents should also apply these properties to floated boxes whose containing block is in the normal flow of the root fragmented element. User agents may also apply these properties to other boxes.

3.2. Breaks inside elements: ‘orphans’, ‘widows’

The ‘orphans’ property specifies the minimum number of line boxes in a block container that must be left in a fragment before a fragment break. The ‘widows’ property specifies the minimum number of line boxes of a block container that must be left in a fragment after a break. Examples of how they are used to control fragmentation breaks are given below.

Only positive integers are allowed as values of ‘orphans’ and ‘widows’. Negative values and zero are invalid must cause the declaration to be ignored.

If a block contains fewer lines than the value of ‘widows’ or ‘orphans’, the rule simply becomes that all lines in the block must be kept together.

4. Rules for Breaking

A fragmented flow may be broken across fragmenters at a number of possible break points. In the case of forced breaks, the UA is required to break the flow at that point. In the case of unforced breaks the UA has to choose among the possible breaks that are allowed.

4.1. Possible Break Points

Fragmentation splits boxes in the block flow dimension. In block-and-inline flow, breaks may occur at the following places:

Class 1

Between sibling boxes of the following types:

When the block flow direction of the siblings' parent is parallel to that of the fragmentation context

block-level boxes, table row group boxes, table row boxes, multi-column column row boxes

When the block flow direction of the siblings' parent is perpendicular to that of the fragmentation context

table column group boxes, table column boxes, multi-column column boxes

Class 2

Between line boxes inside a block container box.

Class 3

Between the content edge of a block 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.

Other layout models may add breakpoints to the above classes.

Since breaks are only allowed between siblings (1), not between a child and its parent, a ‘break-before’ value on a first-child box is propagated to its parent. Likewise a ‘break-after’ value on a last-child box is propagated to its parent.

When paginating, if there are no possible break points below the top of the page, and not all the content fits, the UA may break anywhere in order to avoid losing content off the edge of the page.

The UA is not required to fragment the contents of scrollable elements e.g. those with ‘overflow’ set to ‘auto’ or ‘scroll’, and may instead either graphically slice their contents as necessary to fragment the element or treat the element as unbreakable and overflow the fragmenter. In such cases it must treat the element as having ‘break-inside: avoid’.

4.2. Types of Breaks

There are different types of breaks in CSS, defined based on the type of fragmenters they span:

page break

A break between two page boxes. [CSS3PAGE]

spread break

A break between two page boxes that are not associated with facing pages. A spread break is always also a page break. [CSS3PAGE]

column break

A break between two column boxes. Note that if the column boxes are on different pages, then the break is also a page break. [CSS3COL]

region break

A break between two regions. Note that if the region boxes are on different pages, then the break is also a page break. [CSS3-REGIONS]

A fifth type of break is the line break, which is a break between two line boxes. These are not covered in this specification; see [CSS21].

4.3. Forced breaks

A forced break then occurs at (1) if, among the ‘break-after’ properties specified on or propagated to the earlier sibling box and the ‘break-before’ properties specified on or propagated to the later sibling box there is at least one with a forced break value.

When multiple forced break values apply to a single break point, they combine such all types of break are honored and no content-empty page boxes are generated, except for at most one content-empty page as may be required by the ‘right’ or ‘left’ values to position ensuing content on a right- or left-facing page. When ‘left’ and ‘right’ are both combined, the value specified on the latest element in the flow wins.

A page break must also occur at (1) if the last line box above this margin and the first one below it do not have the same value for ‘page’. See [CSS3PAGE]

4.4. Unforced Breaks

While breaking controls can force breaks, they can also discourage them. The following rules control whether breaking at a possible break point is allowed:

Rule A

A fragmented flow may break at (1) only if all the ‘break-after’ and ‘break-before’ values applicable to this break point allow it, which is when at least one of them forces a break 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’, 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

Additionally, breaking at (2) or (3) is allowed only if the ‘break-inside’ property of all ancestors is ‘auto’.

If the above doesn't provide enough break points to keep content from overflowing the page boxes, then rules A, B and D are dropped in order to find additional breakpoints. In this case the UA may use the ‘avoid’s that are in effect at those points to weigh the appropriateness of the new breakpoints; however, this specification does not suggest a precise algorithm.

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

4.5. Optimizing Unforced Breaks

While CSS3 requires that a fragmented flow must break at allowed break points in order to avoid overflowing the fragmenters in its fragmentation context, it does not define whether content breaks at a particular allowed break. However, it is recommended that user agents observe the following guidelines (while recognizing that they are sometimes contradictory):

• Break as few times as possible.
• Make all fragmenters that don't end with a forced break appear to be equally filled with content.
• Avoid breaking inside a replaced element.

5. Box Model for Breaking

The sizing terminology used in this section is defined in Appendix D of [CSS3-WRITING-MODES].

5.1. Breaking into Varying-size Fragmenters

When a flow is fragmented into varying-size fragmenters, the following rules are observed for adapting layout:

• Intrinsic sizes are calculated and maintained across the entire element. Where an initial containing block size is needed to resolve an intrinsic size, assume the size of the first fragmenter defining a pagination context.
• Layout is performed per-fragmenter, with each fragmenter continuing progress from the breakpoint on the previous, but recalculating sizes and positions using its own size as if the entire element were fragmented across fragmenters of this size. Progress is measured in percentages (not absolute lengths) of used/available space and in amount of used/remaining content. However, when laying out scrollable elements and certain replaced elements the UA may instead maintain a consistent measure and resolved extent across fragmenters.
• Option A: Fragments of boxes that began on a previous fragmenter must start at the top of the new fragmenter. If this results in multiple boxes side-by-side that would otherwise be staggered (if they were not continuations) in order to fit, the elements' widths are reduced (on that fragmenter only) in proportion to their original widths until they fit. However they are not reduced past their min-content width or in case the width copmutes to a non-percent length value.

  First page
  +----------------------------------+
  |########### ......... ############|
  |#         # .....     #          #|
  |#  left   # .......   #   right  #|
  |#  float  # ......... #   float  #|
  |#         # ........  #          #|
  |#         # ......... #          #|
  |#         # ........  #          #|
  |#,,,,,,,,,# ......... #,,,,,,,,,,#|
  +----------------------------------+
  
  Second page in case the 'width' computes to 'auto' or 'percent'
  
  +-----------------+
  |#``````##```````#|
  |# left ## right #|
  |# float## float #|
  |# cont.## cont. #|
  |#################|
  |.................|
  |...............  |
  |.................|
  |....             |
  
  Second page in case the 'width' computes to 'length' value
  
  +-----------------+
      |#`````````##``````````#
      |#  left   ##   right  #
      |#  float  ##   float  #
      |#  cont.  ##   cont.  #
      |#######################
  |.................|
  |...............  |
  |.................|
  |....             |

• Option B: Fragments of boxes that began on a previous fragmenter must obey placement rules with the additional constraint that fragments must not be positioned above the before edge of the fragmenter and must otherwise be placed as high as possible while not violating other constraints. If this results in a box's continuation fragment shifting away from the before edge of the fragmenter, then ‘box-decoration-break: clone’, if specified, wraps the fragment with the box's margin in addition to its padding and border.

  First page
  +----------------------------------+
  |########### ......... ############|
  |#         # .....     #          #|
  |#  left   # .......   #   right  #|
  |#  float  # ......... #   float  #|
  |#         # ........  #          #|
  |#         # ......... #          #|
  |#         # ........  #          #|
  |#,,,,,,,,,# ......... #,,,,,,,,,,#|
  +----------------------------------+
  
  Second page
  
  +-----------------+
  |#`````````# .... |
  |#  left   # ...  |
  |#  float  # .... |
  |#  cont.  # .... |
  |########### ...  |
  |.... #``````````#|
  |...  #  right   #|
  |.... #  float   #|
  |.... #  cont.   #|
  |.... ############|
  |...............  |
  |.......          |

Below are listed some implications of these rules:

• Boxes (including tables) fullfilling layout constraints at their fill-available or percentage-based size may change measure across pages.
• Boxes (including tables) fulfilling layout constraints at their min-content, max-content, or absolute-length size will maintain their measure across pages.
• Option A: Opposite-side side-by-side floats might overlap if, e.g. both begin on a wide page, but their min-content measures taken together are too wide to fit on a later, narrower page. (Auto-sized floats will not overlap if only their max-content measures are too wide, since the shrink-wrap algorithm will give them narrower measures due to the narrower available measure.)
• Option A: Same-side side-by-side floats might overflow their containing block if, e.g. both begin on a wide page, but their min-content measures taken together are too wide to fit on a later, narrower page.
• Option B: Float continuation fragments may be placed below the top of the page if, e.g. multiple floats continue onto a new page that is narrower than the previous page and their (recalculated) widths together are wider than their containing block.
• Option B: A block-level continuation fragment may be placed below the top of the page if, e.g. it establishes a block formatting context and is placed beside a float and both it and the float continue onto a narrower page that is too narrow to hold both of them side-by-side.
• Option B: Content adjacent to a preceding float on one page may wind up above the float on the next page if, e.g. that float is pushed down because it no longer fits side-by-side with an earlier float that also continues to this narrower page.

5.2. Margins at Breaks

When an unforced break occurs between block-level boxes, any adjoining margins are set to zero. When a forced break occurs there, any margins before the break are truncated, but margins after the break are preserved.

5.3. Decorating Box Breaks

When a break splits a box, the ‘box-decoration-break’ property controls whether the box's margins, borders, and padding wrap the fragment effect where the split occurs. If they do not (i.e. ‘slice’ is specified), the box's background and side margins, border, and padding extend from the effective break point to the end of the fragmenter (and across the ensuing blank fragmenter if one is generated due to ‘left’ or ‘right’ breaking). Does this use up height?

6. Conformance

6.1. Document Conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “must”, “must NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “should”, “should NOT”, “RECOMMENDED”, “may”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

6.2. Conformance Classes

Conformance to CSS Fragmentation is defined for three conformance classes:

style sheet

A CSS style sheet.

renderer

A UA that interprets the semantics of a style sheet and renders documents that use them.

authoring tool

A UA that writes a style sheet.

A style sheet is conformant to CSS Fragmentation if all of its declarations that use properties defined in this module have values that are valid according to the generic CSS grammar and the individual grammars of each property as given in this module.

A renderer is conformant to CSS Fragmentation if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by CSS Fragmentation by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to CSS Fragmentation if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

6.3. Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

6.4. Experimental Implementations

To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.

6.5. Non-Experimental Implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group's website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

6.6. CR Exit Criteria

For this specification to be advanced to Proposed Recommendation, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. For the purposes of this criterion, we define the following terms:

independent

each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.

interoperable

passing the respective test case(s) in the official CSS test suite, or, if the implementation is not a Web browser, an equivalent test. Every relevant test in the test suite should have an equivalent test created if such a user agent (UA) is to be used to claim interoperability. In addition if such a UA is to be used to claim interoperability, then there must one or more additional UAs which can also pass those equivalent tests in the same way for the purpose of interoperability. The equivalent tests must be made publicly available for the purposes of peer review.

implementation

a user agent which:

1. implements the specification.
2. is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or “nightly build”). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
3. is not experimental (i.e., a version specifically designed to pass the test suite and is not intended for normal usage going forward).

The specification will remain Candidate Recommendation for at least six months.

Acknowledgments

The editors would like to extend special thanks to Michael Day, and the former [CSS3PAGE] editors Jim Bigelow (HP), Melinda Grant (HP), Håkon Wium Lie (Opera), and Jacob Refstrup (HP) for their contributions to this specification.

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

[CSS3-REGIONS]

Vincent Hardy; Alex Mogilevsky. CSS Regions Module Level 3. 29 November 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-css3-regions-20111129/

[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

[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

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

Other references

[CSS3-WRITING-MODES]

Elika J. Etemad; Koji Ishii; Shinyu Murakami. CSS Writing Modes Module Level 3. 1 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-css3-writing-modes-20110901/

[CSS3BG]

Bert Bos; Elika J. Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 15 February 2011. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2011/CR-css3-background-20110215

[CSS3COLOR]

Tantek Çelik; Chris Lilley; L. David Baron. CSS Color Module Level 3. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-css3-color-20110607

[CSS3TEXT]

Elika J. Etemad; Koji Ishii; Shinyu Murakami. CSS Text Level 3. 1 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-css3-text-20110901/

Index

• authoring tool, 6.2.
• avoid break values, 3.1.
• box fragment, 2.
• break, 2.
• break-after, 3.1.
• break-before, 3.1.
• break-inside, 3.1.
• column break, 4.2.
• forced break values, 3.1.
• fragment, 2.
• fragmentation, 1., 2.
• fragmentation break, 2.
• fragmentation context, 2.
• fragmented flow, 2.
• fragmenter, 2.
• line break, 4.2.
• orphans, 3.2.
• page break, 4.2.
• pagination, 1.
• region break, 4.2.
• renderer, 6.2.
• spread break, 4.2.
• style sheet
  • as conformance class, 6.2.
• widows, 3.2.

Property index