Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This module describes the page model that partitions a flow into pages. It builds on the Box model module and introduces and defines the page model and paged media. It adds functionality for pagination, page margins, page size and orientation, headers and footers, widows and orphans, and image orientation. Finally it extends generated content to enable page numbering and running headers / footers.
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-page” in the subject, preferably like this: “[css3-page] …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 document contains the CSS3 Paged Media Module W3C Last Call Working Draft of 6 October 2011. The Last Call period ends on TBD.
Relative to the previous Last Call Working Draft, this version has
dropped the formerly named ‘fit
’
and ‘fit-position
’ properties;
they are renamed to ‘object-fit
’
and ‘object-position
’, redefined
to enable additional use cases, and moved to the CSS3 Image Values and Replaced
Content module. The margin-box sizing algorithm has been reworded to
be a bit simpler, and many miscellaneous clarifications and editorial
improvements have been incorporated.
Features at-risk (may be removed if they lack implementor interest):
Expected next revision to this document is another LCWD, due to the substantive changes to margin box sizing and other areas that are now specified with more precision.
The Disposition of Comments document contains the current issues list and responses to input received during this Last Call period.
Paged media (e.g., paper, transparencies, photo album pages, pages displayed on computer screens as printed output simulations) differ from continuous media in that the content of the document is split into one or more discrete static display surfaces. To handle pages, CSS3 Paged Media describes how:
This module defines a page model that specifies how a document is formatted within a rectangular area, called the page box, that has finite width and height.
Although CSS3 does not specify how user agents transfer page boxes to sheets, it does include certain mechanisms for telling user agents about the intended page sheet size and orientation. In the general case, CSS3 assumes that one page box will be transferred to one surface of similar size.
All properties defined in this specification also accept the inherit keyword as their value, but for readability it has not been listed explicitly.
All of the text in this specification is normative except sections explicitly marked as non-normative, examples, and notes. The keywords "MUST", "SHALL", "MUST NOT", "SHALL NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" when used in this document are to be interpreted as described in RFC 2119 [RFC2119]. However, for readability, these words do not appear in all uppercase letters in this specification.
Examples in this specification are introduced with the words "for
example" or are set apart from the normative text with
class="example"
, like this:
This is an example of an informative example.
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.
The following terminology and accompanying diagrams help to describe the page model:
portrait
’ and ‘landscape
’.
:left
’ page
selector.
:right
’ page
selector.
In the paged media formatting model, the document is transferred into
one or more page boxes. The page box is a
specialized CSS box that maps to a rectangular print media surface, such
as a page of paper. It is roughly analogous to the viewport.
As with other CSS boxes, a page box consists of margin, border, padding, and content areas. The content and margin areas of a page box have special functions:
The properties of a page box are determined by
properties declared
within the page
context, which is the declaration block of the @page
rule.
Declarations in the page context can affect the page box and/or inherit to the margin boxes, but they do not apply to or inherit into the document's root element or other content.
When formatting content in the page model, some content may end up
outside the page box. For example, an element whose ‘white-space
’ property has the value
‘pre
’ can generate a box that is
wider than the page box. As another example, when boxes are positioned
absolutely or relatively, they may end up in "inconvenient" locations.
For example, images may be placed on the edge of the page box or 100,000
meters below the page box.
A specification for the exact formatting of such elements lies outside the scope of this document. However, it is recommended that authors and user agents observe the following general principles concerning content outside the page box:
Content should be allowed slightly beyond the page box to allow pages to "bleed".
User agents SHOULD avoid generating a large
number of content-empty pages to honor the positioning of elements
(e.g., printing 100 blank pages is probably neither the author's nor
the user's intent). A Content-empty page is
a page box whose page area contains no printable content other than
backgrounds and/or borders. A page box whose page area contains
generated content, or content whose visibility is ‘hidden
’, or invisible content such as a
zero-width space is not a content-empty page. On the other hand, a page
containing only a background and/or borders and/or margin-box content
is a content-empty page.
Note, however, that generating a small number of empty
page boxes is sometimes necessary to honor the ‘left
’ and
‘right
’
values for ‘page-break-before
’ and ‘page-break-after
’.
Authors SHOULD NOT position elements in inconvenient locations just to avoid rendering them. Instead:
display
’ property to ‘none
’.
visibility
’ property.
This specification does not define how boxes positioned outside the page box are handled. Possibilities include discarding them or creating page boxes for them at the end of the document.
When drawing a page of content, the page background and borders are painted first (underneath). Margin-boxes are painted over (on top of) the page box. The root element then paints the canvas and the document contents within the page padding box.
The exact painting order of margin boxes is not specified, however it is recommended that when margin boxes overlap, paint order should place center/middle margin boxes on top of corner margin boxes, which are in turn painted on top of other boxes. More precisely, in terms of the algorithm in CSS2.1 Appendix E the exact "tree order" of margin boxes is not defined, but it is recommended that center/middle boxes be after corner boxes, which should themselves be after other boxes.
The UA may support the z-index
property for margin boxes.
In this case the root element, together with the canvas background and
all of the document contents, are treated as a single element with a
z-index
value of ‘0
’: the
margin boxes never interleave with parts of the document content, they
may only paint in front of or behind the document content and its canvas.
The page box itself generates a new stacking context and is treated as
the parent of all the margin boxes as well as the document content. In
other words, nothing ever paints behind the page box backgrounds or
borders. Since the position
property does not apply to
margin boxes, z-index
always affects margin boxes as if they
were positioned elements regardless of the position
property's value. Mark this at-risk.
CSS distinguishes between left pages and right pages on all documents,
whether they are printed duplex or not. Each left page is followed by a
right page and vice versa. Left and right pages can be styled differently
with the :left
and
:right
pseudo-classes.
Whether the first page of a document is a left page or a right page depends on the page progression of the document. The page progression is the direction in which the printed pages of a document would be sequenced when laid out side-to-side. For example, English and horizontally-set Japanese typically progress from left to right, whereas Arabic and vertically-set Japanese pages typically progress from right to left. In documents with with a left-to-right page progression the first page of the document is a right page, and vice versa.
The page progression direction is determined as follows:
If the UA supports the ‘direction
’ and ‘block-progression
’ properties from the CSS 3
Text Layout Module [CSS3TEXTLAYOUT], it must
determine whether the first page is a left or right page from the values
of those properties on the root element.
To explicitly force a document to begin printing on a left or right
page, authors can insert a page break
before the first generated box. The UA must suppress the first
(empty) page(s) in this case (and the :first
selector
applies to the first printed page).
Authors can specify various aspects of a page box, such as its
dimensions, orientation, and margins, within an @page rule. An @page rule
consists of the keyword ‘@page
’, an OPTIONAL page name followed with no intervening space
by an OPTIONAL page pseudo-class, and a block of
declarations (said to be in the page context).
Margin at-rules may be interleaved with
the declarations in the page context.
The OPTIONAL page name and OPTIONAL page pseudo-class constitute the page selector. The page selector specifies for
which pages the declarations apply. In CSS3, page selectors can designate
the first page of a document, all left pages, all right pages, or pages with specific names. Multiple
selectors may be combined with a comma (which may be preceded and/or
followed by white space); in this case the ‘@page
’ rule applies to pages that match any of
the page selectors. (Note: this feature is at-risk.) If no page selector
is given, then the ‘@page
’ rule applies to all pages.
Properties declared within the page context apply to the page box.
If an error is encountered during the processing of a declaration block within a page or a margin context, the Rules for handling parsing errors apply; that is, valid declarations within the block are applied.
When printing double-sided documents, left and right pages are often formatted differently. This can be expressed through CSS pseudo-classes defined in the page context.
All pages are automatically classified by user agents as either left
pages or right pages. The ‘:left
’ and ‘:right
’ page pseudo-classes can be used to
selectively apply rules to only the left or right pages, respectively.
@page :left { margin-left: 3cm; margin-right: 4cm; } @page :right { margin-left: 4cm; margin-right: 3cm; }
If different declarations have been given for left and right pages, the user agent MUST honor these declarations even if the user agent does not transfer the page boxes to left and right sheets (i.e., a printer that only prints on one side of the medium must nevertheless produce correctly formatted output).
Authors can also specify style for the first page of a document with
the ‘:first
’
pseudo-class. Such style rules are applied only to the first printed page
of a document.
@page { margin: 2cm } /* All margins set to 2cm */ @page :first { margin-top: 10cm /* Top margin on first page 10cm */ }
html {page-break-before: always;}
For an XHTML document with a left-to-right page progression, the above
style rule will cause the first page of the document to print on a
‘:right
’ page
Note. Adding declarations to the ‘:left
’ or ‘:right
’
pseudo-class does not necessarily influence whether the document comes
out of the printer double- or single-sided (which is outside the scope
of this specification).
Note. Future versions of CSS may include other page pseudo-classes.
The syntax for the @page rule is a specialization of the generic at-rule defined by CSS 2.1. This grammar extends the at-rule syntax to allow @page rules nested inside @media rules. User agents MUST adhere to the following grammar:
See [CSS21], Section 4.1.1 and Appendix G for the expansion of missing productions:
All new lexical tokens are specializations of the ATKEYWORD lexical token:
PAGE_SYM ::= "@page" TOPLEFTCORNER_SYM ::= "@top-left-corner" TOPLEFT_SYM ::= "@top-left" TOPCENTER_SYM ::= "@top-center" TOPRIGHT_SYM ::= "@top-right" TOPRIGHTCORNER_SYM ::= "@top-right-corner" BOTTOMLEFTCORNER_SYM ::= "@bottom-left-corner" BOTTOMLEFT_SYM ::= "@bottom-left" BOTTOMCENTER_SYM ::= "@bottom-center" BOTTOMRIGHT_SYM ::= "@bottom-right" BOTTOMRIGHTCORNER_SYM ::= "@bottom-right-corner" LEFTTOP_SYM ::= "@left-top" LEFTMIDDLE_SYM ::= "@left-middle" LEFTBOTTOM_SYM ::= "@left-bottom" RIGHTTOP_SYM ::= "@right-top" RIGHTMIDDLE_SYM ::= "@right-middle" RIGHTBOTTOM_SYM ::= "@right-bottom" media : MEDIA_SYM S* medium [ COMMA S* medium ]* LBRACE S* [ page | ruleset ]* '}' S* ; page : PAGE_SYM S* IDENT? S* pseudo_page? S* '{' S* [ margin_box | ruleset ]? [ ';' S* [ margin_box | ruleset ]? ]* '}' S* ; Space should not be allowed between name and pseudo. pseudo_page : ':' [ "left" | "right" | "first" ] ; margin_box : margin_sym S* '{' ruleset* '}' S* ; margin_sym : TOPLEFTCORNER_SYM | TOPLEFT_SYM | TOPCENTER_SYM | TOPRIGHT_SYM | TOPRIGHTCORNER_SYM | BOTTOMLEFTCORNER_SYM | BOTTOMLEFT_SYM | BOTTOMCENTER_SYM | BOTTOMRIGHT_SYM | BOTTOMRIGHTCORNER_SYM | LEFTTOP_SYM | LEFTMIDDLE_SYM | LEFTBOTTOM_SYM | RIGHTTOP_SYM | RIGHTMIDDLE_SYM | RIGHTBOTTOM_SYM ;
The value ‘auto
’ is not a valid page name and must be
treated as matching nothing.
The following are examples of page selectors (declaration block intentionally left blank)
@page { ... } @page :left { ... } @page :right { ... } @page LandscapeTable { ... } @page CompanyLetterHead:first { ... } /* identifier and pseudo page. */ @page:first { ... };
The following are examples of margin boxes where the declaration blocks are intentionally left blank.
@page { @top-left { ... /* document name */ } @bottom-center { ... /* page number */} } @page :left { @left-middle { ... /* page number in left margin */ }} @page :right{ @right-middle { ... /* page number in right margins of right pages */}} @page :left { @bottom-left-corner { ... /* left page numbers */ }} @page :right { @bottom-right-corner { ... /* right page numbers */ }} @page :first { @bottom-left-corner { ... /* empty footer on 1st page */ } @bottom-right-corner { ... /* empty footer */ } }
Declarations in page and margin contexts cascade just like declarations in rule sets.
The specificity of page selectors is computed in a manner analogous to the computations defined in the Selectors module:
:first
’ pseudo-class, g=1; else g=0
:left
’
or ‘:right
’ pseudo-class, h=1; else
h=0
Concatenating the three numbers f-g-h gives the specificity.
Properties that are not explicitly set within the page or margin context take their initial values and do not inherit from any element.
Some page specificity calculation examples follow:
@page { } /* f=0 g=0 h=0 -> specificity = 000 */ @page :left { } /* f=0 g=0 h=1 -> specificity = 001 */ @page :first { } /* f=0 g=1 h=0 -> specificity = 010 */ @page artsy { } /* f=1 g=0 h=0 -> specificity = 100 */ @page artsy:left { } /* f=1 g=0 h=1 -> specificity = 101 */ @page artsy:first { } /* f=1 g=1 h=0 -> specificity = 110 */
Consider the following usage example:
@page { margin-left: 3cm; } @page :left { margin-left: 4cm; }
Due to the higher specificity of the pseudo-class selector, the left margin on left pages will be 4cm and all other pages (the right-facing pages) will have a left margin of 3cm.
In this example, the higher specificity of the green rules wins over the red rule. Therefore the first page will have blue text in the top-left margin box and green text in the top-right margin box, while subsequent pages will have red text in the margin boxes.
@page :first { color: green; @top-left { content: "foo"; color: blue; } @top-right { content: "bar"; } } @page { color: red; @top-center { content: "Page " counter(page); } }
Page contexts cascade, so the following stylesheet would style pages with 25 millimeter margins and 14 point type in the margin boxes:
@page { margin: 25mm;} @page { font-size: 14pt;}
Margin boxes are boxes within the page margin that, like pseudo-elements, can contain generated content.
Margin boxes can be used to create page headers and footers, which are portions of the page set aside for supplementary information such as the page number or document title.
Typically, a page header is located at the
top of the page in documents with a predominately horizontal writing
direction and on the side opposite the binding
edge for documents with a predominately vertical writing direction.
One possible design of page headers for horizontally written documents
uses the ‘top-left-corner
’, ‘top-left
’,
‘top-center
’, ‘top-right
’ and
‘top-right-corner
’ margin boxes.
Another design, for vertically written documents, could use the ‘right-top
’,
‘right-middle
’, and ‘right-bottom
’
margin boxes for right facing pages and ‘left-top
’,
‘left-middle
’, and ‘left-bottom
’
for left facing pages.
The page footer is typically at the opposite
end of the page from the page header. For example, the design of a
horizontally written document with a page header at the top of the page
could use the ‘bottom-left-corner
’, ‘bottom-left
’,
‘bottom-center
’, ‘bottom-right
’
and ‘bottom-right-corner
’ margin boxes as
the page footer. The design of a vertically written document could use
the margin boxes of the binding edge of the page for the page footer.
Margin boxes are oriented with respect to the content and are independent of page orientation, for example the top margin boxes are above the page area in both portrait and landscape orientation. The various margin boxes are defined and illustrated in the diagram below:
Box | Description | Placement |
---|---|---|
top-left-corner | a fixed-size box defined by the intersection of the top and left margins of the page box | ![]() |
top-left | a variable-width box filling the top page margin between the top-left-corner and top-center margin boxes | ![]() |
top-center | a variable-width box centered horizontally between the page's left and right border edges and filling the page top margin between the top-left and top-right margin boxes | ![]() |
top-right | a variable-width box filling the top page margin between the top-center and top-right-corner margin boxes | ![]() |
top-right-corner | a fixed-size box defined by the intersection of the top and right margins of the page box | ![]() |
left-top | a variable-height box filling the left page margin between the top-left-corner and left-middle margin boxes | ![]() |
left-middle | a variable-height box centered vertically between the page's top and bottom border edges and filling the left page margin between the left-top and left-bottom margin boxes | |
left-bottom | a variable-height box filling the left page margin between the left-middle and bottom-left-corner margin boxes | |
right-top | a variable-height box filling the right page margin between the top-right-corner and right-middle margin boxes | ![]() |
right-middle | a variable-height box centered vertically between the page's top and bottom border edges and filling the right page margin between the right-top and right-bottom margin boxes | |
right-bottom | a variable-height box filling the right page margin between the right-middle and bottom-right-corner margin boxes | |
bottom-left-corner | a fixed-size box defined by the intersection of the bottom and left margins of the page box | ![]() |
bottom-left | a variable-width box filling the bottom page margin between the bottom-left-corner and bottom-center margin boxes | ![]() |
bottom-center | a variable-width box centered horizontally between the page's left and right border edges and filling the bottom page margin between the bottom-left and bottom-right margin boxes | ![]() |
bottom-right | a variable-width box filling the bottom page margin between the bottom-center and bottom-right-corner margin boxes | ![]() |
bottom-right-corner | a fixed-size box defined by the intersection of the bottom and right margins of the page box | ![]() |
Margin boxes are created by margin at-rules inside the page context. These rules should come after any declarations in the page context as legacy clients may not handle declarations after margin at-rules correctly.
A margin at-rule consists of an ATKEYWORD that identifies the
margin box (e.g. ‘@top-left
’) and a block of declarations
(said to be in the margin context).
The following style sheet establishes a page header containing the title ("Hamlet") on the left side and the page number, preceded by "Page ", on the right side:
@page { size: 8.5in 11in; margin: 10%; @top-left { content: "Hamlet"; } @top-right { content: "Page " counter(page); } }
A margin box is instantiated if and only if the computed value of its
‘content
’ property does not match
that of its initial value.
The following style sheet creates a green box in each corner of the page except the bottom-left corner.
@page { @top-left-corner { content: " "; border: solid green; } @top-right-corner { content: url(foo.png); border: solid green; } @bottom-right-corner { content: counter(page); border: solid green; } @bottom-left-corner { content: normal; border: solid green; } }
The width and height of each margin box is determined by the rules below. These rules define the equivalent of CSS2.1 Sections 10.3 and 10.6 for margin boxes.
The rules for applying ‘min-height
’, ‘max-height
’, ‘min-width
’, and ‘max-width
’ [CSS21] do apply to margin boxes and
may imply a recalculation of the width, height, and/or margins if the
dimensions resulting from the specified ‘width
’ or ‘height
’ violate their constraints. If the UA
does not support the ‘min-height
’
or ‘min-width
’ properties then it
must behave as if ‘min-height
’
and ‘min-width
’ were always zero.
In addition to the box model definitions in CSS2.1 [CSS21], the following terms are defined for use in the subsequent margin box calculations:
s left border edge
and right border edge. This quantity is used when calculating dimensions
of the top and bottom margin boxes.
s top border edge
and bottom border edge. This quantity is used when calculating
dimensions of the left and right margin boxes.
The containing block for a corner margin box is the rectangle defined by the intersection of the two page margins meeting at that corner.
For all other margin boxes, the containing block is the rectangle formed by the encapsulating page margin minus the containing blocks of the adjacent corners' margin boxes. This means that the size of this containing block is given in one dimension by the used page margin and in the other dimension by the max box width (for top and bottom margin boxes) or max box height (for left and right margin boxes).
The following rules apply to ‘top-left
’, ‘top-center
’ and ‘top-right
’ margin boxes, which are referred
to as A, B, and C, respectively, in the expression below.
auto
’, then the outer widths
of the other two boxes are equal to each other (i.e., the center box
is centered in that case).
auto
’, then the used values of its left
and right padding width and left and right border width are all 0.
(This makes such a box invisible, because, by item 5, its width is
also 0.)
auto
’.
auto
’, then its used width must be greater
than or equal to its preferred minimum width.
auto
’, then its used width must also be
less than or equal to its preferred width.
auto
’.
Note: By their definitions, margins can be negative, but widths cannot.
The used values for ‘bottom-left
’, ‘bottom-center
’ and ‘bottom-right
’ margin boxes are established by
the same rules as for ‘top-left
’,
‘top-center
’, and ‘top-right
’, respectively.
The used values for ‘left-top
’,
‘left-middle
’ and ‘left-bottom
’ boxes are established by the
same rules, with "width" replaced by "height", "left" by "top", "right"
by "bottom" and "center" by "middle".
The used values for ‘right-top
’, ‘right-middle
’ and ‘right-bottom
’ margin boxes are established by
the same rules as for ‘left-top
’,
‘left-middle
’ and ‘left-bottom
’, respectively.
The rules below are used to calculate the used values of each
‘top-left-corner
’, ‘top-left
’, ‘top-center
’, ‘top-right
’, and ‘top-right-corner
’ margin box's ‘height
’, ‘margin-top
’, and ‘margin-bottom
’ properties:
‘margin-top
’ + ‘border-top-width
’ + ‘padding-top
’ + ‘height
’ + ‘padding-bottom
’ + ‘border-bottom-width
’ + ‘margin-bottom
’ = top page margin
border-top-width
’ +
‘padding-top
’ + ‘height
’ (if it is not ‘auto
’) + ‘padding-bottom
’ + ‘border-bottom-width
’, plus ‘margin-top
’ and/or ‘margin-bottom
’ if not ‘auto
’, is larger than the height of the top page
margin, then any ‘auto
’ values for
‘margin-top
’ or ‘margin-bottom
’ are, for the following rules,
treated as zero.
height
’, ‘margin-top
’, and ‘margin-bottom
’ have a computed value other
than ‘auto
’, the values are said to
be "over-constrained". In this case, the specified value of ‘margin-top
’ is treated as ‘auto
’.
auto
’, its used value follows from the
equality.
height
’ is set to
‘auto
’, any other ‘auto
’ values become ‘0
’ and ‘height
’ follows from the resulting equality
margin-top
’ and
‘margin-bottom
’ are ‘auto
’, their used values are equal. This
vertically centers the margin-box content within the top page margin.
The same rules apply to the bottom margin boxes (bottom-left-corner,
bottom-left, bottom-center, bottom-right, and bottom-right-corner),
except that in the overconstrained case, the ‘margin-bottom
’ is ignored rather than the
‘margin-top
’.
Analogous rules govern the properties for the left and right margin
boxes with respect to ‘width
’
(top-left-corner, left-top, left-middle, left-bottom, and
bottom-left-corner; top-right-corner, right-top, right-middle,
right-bottom, bottom-right-corner), with ‘top
’ replaced by ‘left
’, ‘bottom
’ replaced by ‘right
’, and ‘height
’ replaced by ‘width
’. In the overconstrained case for left
(right) margin boxes, the specified value of ‘margin-left
’ (‘margin-right
’) is ignored.
The following is a collection of examples of margin box usage.
Here is an example of a page with only a top-left header:
@page { @top-left { content: "Header in Left Cell (top-left)" } }
Because there are no contents defined for the top-center or the top-right margin boxes, the extent of the top-left margin box is allowed to cross the center of the page box.
The following is an example of a page with a centered header:
@page { @top-center { content: "Header in Center Cell (top-center)" } }
The following is an example of a page with a single header in the top-right margin box:
@page { @top-right { content: "Header in Right Cell (top-right)" } }
Because the content of the center cell is empty, the extent of the top-right margin box is allowed to cross the center of the page box.
The following is an example of a page with a top-center and a top-left header:
@page { @top-left { content: "Left Cell (top-left)" } @top-center { content: "Header in Center Cell (top-center)" } }
The following is an example of a page with a top-center and a top-right header:
@page { @top-center { content: "Header in Center Cell (top-center)" } @top-right { content: "Right Cell (top-right)" } }
The following is an example of a page with top-left and top-right headers:
@page { @top-left { content: "Header in top-left with approx. " "twice as many words as right cell." } @top-right { content: "Right cell (top-right)" } }
Because there are no center cell contents, the extent of the top-left is allowed to cross the center of the page box. As the intrinsic width of the top-left contents is approximately twice the intrinsic width of that of the top-right, the top-left margin box is approximately twice as wide as the top-right margin box.
The following properties, when used in the page context, apply to the page box:
The following properties, when used in a margin context, apply to margin boxes and their content:
A detailed list of properties that MUST be supported within page and margin contexts by a conforming implementation can be found in Appendix A.
Other properties defined by [CSS21] do not apply in these contexts. Behavior for properties not included in CSS 2.1 and not listed here or in Appendix A is undefined.
Note: The intent of leaving other properties undefined is to allow the gradual addition of appropriate CSS3 properties as they emerge, without having to update this specification with each addition.
As with elements in the document, both the page context and the margin context have a computed value for every property, even if that property does not apply to the page or margin box.
The normal rules for CSS properties apply with the following exceptions:
em
’ and
‘ex
’ are interpreted relative to the
font associated with their context. When used on the ‘font-size
’ property in the margin context,
they are relative to the font of the page context. When used on the
‘font-size
’ property in the
page context, they are relative to the ‘font-size
’ of the root element. However,
since a previous revision of CSS Paged Media Level 3 was ambiguous on
this point, an implementation that treats ‘em
’ and ‘ex
’
on ‘font-size
’ as relative to
the initial value is also conformant to CSS Paged Media Level 3. Note
that this exception will be removed in Level 4.
width
’
and ‘height
’ have special
computation rules for page boxes and margin boxes; see Page Size and Computing Margin Box Dimensions.
background-attachment
’ is ‘fixed
’ then the image is positioned
relative to the page box including its margins.
::before
’ and
‘::after
’ pseudo-classes, the
‘normal
’ value of the ‘content
’ property computes to ‘none
’ on margin boxes.
It is recommended that user agents establish a default page margin via the user agent stylesheet that includes any non-printable area. It is further recommended that authors assume that the default page area will not include unprintable regions.
Counters can be defined and controlled within an ‘@page
’ rule, and used as content in
margin boxes. This is useful for maintaining a page count.
The following rules result in the placement of the current page number in the middle of the outside margin of each page.
@page { margin: 10%; counter-increment: page; @top-center { font-family: sans-serif; font-weight: bold; font-size: 2em; content: counter(page); } }
A ‘counter-increment
’ within
either a page or margin context causes the counter to increment with the
generation of each page box.
If a counter is reset or incremented within the page context, it is in scope for all margin boxes and obscures all counters of the same name within the document.
If a counter is reset or incremented within a margin context, it is in scope for that margin box and obscures any counters of the same name in both the page context and the document.
If a counter that has not been reset or incremented within the margin context or the page context is used by counter() or counters() in the margin context, then the resultant value is exactly as if the margin box were an element within the document at the start of the page, inside the deepest element in the normal flow that spans the page break. Use of the counter in this way does not affect the calculation of the counter's value.
A counter named ‘page
’ is automatically created and
incremented on every page of the document. Specifically, the UA must
automatically create and increment such a counter as if ‘@page { counter-increment: page; }
’ were
specified. The implied ‘page
’ counter is a real counter, and can be
directly affected using the ‘counter-increment
’ and ‘counter-reset
’ properties when named
explicitly in those properties. It can also be used in the ‘counter()
’ and ‘counters()
’ function forms.
Additionally, a counter named ‘pages
’ is automatically created by the UA. Its
value is always the total number of pages in the document. (In
continuous media this is always 1.) The value of ‘pages
’ cannot be manipulated: while ‘counter-reset
’ and ‘counter-increment
’ statements that set it
are valid, they have no effect.
In all other respects, page-associated counters behave as described in [CSS21], Nested Counters and Scope and Counters.
Properties used within page or margin contexts take their initial values from their respective property definitions; however, user agents must behave as though the values in the following table were established by rules in the UA default style sheet.
Margin box | ‘text-align ’
| ‘vertical-align ’
|
---|---|---|
top-left-corner | right | middle |
top-left | left | middle |
top-center | center | middle |
top-right | right | middle |
top-right-corner | left | middle |
left-top | center | top |
left-middle | center | middle |
left-bottom | center | bottom |
right-top | center | top |
right-middle | center | middle |
right-bottom | center | bottom |
bottom-left-corner | right | middle |
bottom-left | left | middle |
bottom-center | center | middle |
bottom-right | right | middle |
bottom-right-corner | left | middle |
This example style sheet could be used to create a centered header with the current chapter name:
body {counter-reset: chapter;} div.chapter {counter-increment: chapter;} @page { margin: 10%; @top-center { content: "Chapter" counter(chapter) } }
People around the world use many different paper sizes. It is a goal of this specification that web content should be adaptable to a range of different sizes without having to write a specific style sheet for each paper size.
However, in some situations it is important that a certain page size
achieves a certain style. One way to achieve this goal is to utilize the
‘size
’
property, which indicates that the document should preferentially be
displayed on a surface of a certain size; another method is to use Media
Queries [MEDIAQ]
which allow different style sheets to be applied to different page
sizes.
size
’
propertyThe containing block of the page box is specified using the ‘size
’ property in the
page context. The width and
horizontal margins of the page box are then calculated exactly as for a
non-replaced
block element in normal flow. [CSS21] The height and vertical
margins of the page box are calculated analogously (instead of using the
block height formulas). In both cases if the values are
over-constrained, instead of ignoring any margins, the containing block
is resized to coincide with the margin edges of the page box.
Name: | size |
---|---|
Value: | <length>{1,2} | auto | [ <page-size> || [ portrait | landscape] ] |
Initial: | auto |
Applies to: | page context |
Inherited: | N/A |
Percentages: | N/A |
Media: | paged |
Computed value: | specified value |
This property specifies the target size and orientation of the page box. In the general case, where one page box
is rendered onto one page sheet, the ‘size
’ property also indicates the
size of the destination page sheet.
The size of a page box can either be "absolute" (fixed size) or "relative" (scalable, i.e., fitting available sheet sizes).
The first three values in the table below can be used to create relative page boxes.
Other values define a fixed-size page box, and thereby indicate the preferred output media size. When possible, output should be rendered on the media size indicated. If the specified size is not available, the smallest available larger size should be used; if not available, the contents of the page box should be scaled down to fit the largest smaller page sheet available.
If a size
property declaration
specifies a page size that would cause that declaration to not apply
(e.g. a media query that qualifies it applies only to a different paper
size) then the declaration must be ignored. Is this a reasonable way of dealing with this
conflict?
In the following example
@page { size: 4in 6in; } @media (max-width: 6in) { @page { size: letter; } }
The second size
declaration is
ignored, i.e. the specified value of the size
property is 4in 6in
.
Value | Description |
---|---|
auto | The page box will be set to a size and orientation chosen by the UA. In the usual case, the page box size and orientation is chosen to match the target media sheet. |
landscape | Specifies that the page's content be printed in landscape
orientation. The longer sides of the page box are horizontal. If a
‘<page-size> ’ is not specified,
the size of the page sheet is chosen by the UA.
|
portrait | Specifies that the page's content be printed in portrait
orientation. The shorter sides of the page box are horizontal. If a
‘<page-size> ’ is not specified,
the size of the page sheet is chosen by the UA.
|
<length> | The page box will be set to the given absolute dimension(s). If
only one length value is specified, it sets both the width and height
of the page box (i.e., the box is a square). If two length values are
specified, the first establishes the page box width, and the second
the page box height. Values in units of ‘em ’ and ‘ex ’ refer
to the page context's font.
|
<page-size> | A page size can be specified using one of the following media
names. This is the equivalent of specifying the ‘<page-size> ’ using length values.
The definition of the the media names comes from Media
Standardized Names [PWGMSN].
|
The ‘<page-size>
’ names can
be used in conjunction with ‘landscape
’ or ‘portrait
’ to indicate both size and
orientation.
@page { size: A4 landscape; }
The above example sets the width of the page box to be 297mm and the height to be 210mm. The page box in this example should be rendered on a page sheet size of 210 mm by 297 mm.
In the following example, the outer edges of the page box will align
with the page. The percentage value on the ‘margin
’
property is relative to the page size so if the page sheet dimensions
are 210mm x 297mm (i.e., A4), the margins are 21mm and 29.7mm. Assuming
there are no page borders or padding set in the UA default style sheet,
the resulting page area is 189mm by 367.3mm (210mm-21mm by
297mm-29.7mm).
@page { size: auto;/* auto is the initial value */ margin: 10%; }
@page { size: 8.5in 11in;/* width height */ }
The above example sets the width of the page box to be 8.5 inches and
the height to be 11 inches. This indicates that the page sheet size
should be 8.5"x11" and the orientation ‘portrait
’.
This section is informative.
By using Media Queries [MEDIAQ], one style sheet can express different stylistic preferences for different page sizes. Consider this example:
/* style sheet for "A4" printing */ @media print and (width: 21cm) and (height: 29.7cm) { @page { margin: 3cm; } } /* style sheet for "letter" printing */ @media print and (width: 8.5in) and (height: 11in) { @page { margin: 1in; } }
In the example above, "A4" sheets are given a "3cm" page margin, and "letter" sheets are given a "1in" page margin.
If a page box does not match the target page sheet dimensions, the user agent MAY choose (in order of preference) to:
spilling
’ onto other page sheets.
The user agent MAY wish to consult the user before performing these operations.
When the page box is smaller than the page size, the user agent SHOULD either:
The user agent MAY wish to consult the user in this regard.
The following sections explain page breaking in CSS3 paged media. Five properties indicate where the user agent MAY or SHOULD break pages, and on what page (left or right) the subsequent content SHOULD resume. Each page break ends layout in the current page box and causes remaining pieces of the document tree to be laid out in a new page box.
When a page break splits a box, the box's bottom margins, borders, and padding have no visual effect where the split occurs; the box's background and left and right margins, border, and padding extend to the bottom of the page, through an ensuing blank page if one exists, and onto the top of the subsequent page.
page-break-before
’, ‘page-break-after
’, ‘page-break-inside
’Name: | page-break-before |
---|---|
Value: | auto | always | avoid | left | right |
Initial: | auto |
Applies to: | block-level elements |
Inherited: | no |
Percentages: | N/A |
Media: | paged |
Computed value: | specified value |
Name: | page-break-after |
---|---|
Value: | auto | always | avoid | left | right |
Initial: | auto |
Applies to: | block-level boxes, table row groups, table rows (but see prose) |
Inherited: | no |
Percentages: | N/A |
Media: | paged |
Computed value: | specified value |
Name: | page-break-inside |
---|---|
Value: | auto | avoid |
Initial: | auto |
Applies to: | block-level boxes, table row groups, table rows, and table cells (but see prose) |
Inherited: | no |
Percentages: | N/A |
Media: | paged |
Computed value: | specified value |
Values for these properties have the following meanings:
A potential page break location is typically under the influence of
the parent element's ‘page-break-inside
’ property, the
‘page-break-after
’ property of the
preceding element, and the ‘page-break-before
’ property of
the following element. When these properties have values other than
‘auto
’,
the values ‘always
’, ‘left
’, and ‘right
’ take
precedence over ‘avoid
’. See the section on allowed page breaks for the exact rules on
how these properties affect page breaks.
User Agents must apply these properties to block-level boxes and to
table rows, table row groups, and—in the case of ‘page-break-inside
’—table cells of
block-level tables in the normal flow of the root element. User agents
should also apply these properties to floated boxes whose containing
block is in the normal flow of the root element. User agents may also
apply these properties to other boxes.
page
’Name: | page |
---|---|
Value: | auto | <identifier> |
Initial: | auto |
Applies to: | block-level elements |
Inherited: | no (but see prose) |
Percentages: | N/A |
Media: | paged |
Computed value: | specified value |
The ‘page
’ property is used to specify
a particular type of page where an element SHOULD
be displayed.
This example will put all tables on a right-hand side landscape page (named "rotated"):
@page rotated { size: landscape } table { page: rotated; page-break-before: right }
The ‘page
’ property works as follows:
If a block box with inline content has a ‘page
’ property
that is different from the preceding block box with inline content, then
one or two page breaks are inserted between them, and the boxes after
the break are rendered on a page box of the named type. See "Forced page breaks" below.
The ‘page
’
property does not inherit. However, if the ‘page
’ value on an element is
‘auto
’, then it is treated as having
the same name as its nearest ancestor with a non-auto value. When
indicated on the root element, the effective name is the empty string.
Because a previous version of this specification indicated that the
‘page
’
property is inherited, an implementation that inherits the ‘page
’ property and
treats ‘auto
’ as always naming the
empty string remains conformant to CSS3 Paged Media. Therefore authors
should not explicitly specify the ‘auto
’ value on a descendant of an element with a
non-‘auto
’ ‘page
’ value as the
resulting behavior will be unpredictable.
Page names are case-sensitive identifiers. However the ‘auto
’ value, being a CSS keyword, is case-insensitive.
In this example, the two tables are rendered on landscape pages (indeed, on the same page, if they fit). The page type "narrow" is used for the <p> after the second table, as the page properties for the table element are no longer in effect:
@page narrow { size: 9cm 18cm } @page rotated { size: landscape } div { page: narrow } table { page: rotated }with this document:
<div> <table>...</table> <table>...</table> <p>This text is rendered on a 'narrow' page</p> </div>
orphans
’, ‘widows
’Name: | orphans |
---|---|
Value: | <integer> |
Initial: | 2 |
Applies to: | block-level elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | specified value |
Name: | widows |
---|---|
Value: | <integer> |
Initial: | 2 |
Applies to: | block-level elements |
Inherited: | yes |
Percentages: | N/A |
Media: | visual |
Computed value: | specified value |
The ‘orphans
’ property specifies the
minimum number of line boxes in a block element that MUST be left at the bottom of a page. The ‘widows
’ property specifies the
minimum number of line boxes of a block element that MUST be left at the top of a page. Examples of how
they are used to control page 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.
In the normal flow, page breaks may occur at the following places:
margin-top
’ and
‘margin-bottom
’ are set to
zero.
These breaks are subject to the following rules:
page-break-after
’ and ‘page-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
’.
auto
’ and a
common ancestor of all the elements has a ‘page-break-inside
’ value of
‘avoid
’,
then breaking here is not allowed.
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.
page-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.
A page break MUST occur at (1) if, among the'page-break-after' and
‘page-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
’.
When multiple ‘page-break-before
’ and/or ‘page-break-after
’ properties with values
of "always", "left" or "right" apply at a margin, only one of them
should generate page breaks. That is, no content-empty pages are
generated by page-break properties, except for at most one content-empty
page as may be required by ‘right
’ and ‘left
’ values to position ensuing content on
a right- or left-facing page.
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
’.
When a forced page break occurs at (1),
the used values of any adjoining ‘margin-bottom
’ are set to zero.
CSS3 does not define which of a set of allowed page breaks MUST be used; except as defined earlier in the section, CSS3 does not forbid a user agent to break at every possible break point, or to not break at all. But CSS3 does recommend that user agents observe the following guidelines (while recognizing that they are sometimes contradictory):
Suppose, for example, that the style sheet contains ‘orphans : 4
’,
‘widows : 2
’,
and there are 20 lines (line boxes) available at the bottom of the
current page, and the next block in normal flow is considered for
placement:
widows
’ constraint, and so the
second part MUST contain at least two line
boxes; likewise the first part MUST contain at
least four line boxes.
Now suppose that ‘orphans
’ is ‘10
’, ‘widows
’ is ‘20
’, and there are
8 lines available at the bottom of the current page:
This section has been moved to [CSS3IMAGES].
The following CSS 2.1 [CSS21] properties apply to the page box. If a conforming user agent supports any of these properties on block boxes, then it must also support that property for the page box.
bidi properties | direction |
background properties | background-color |
background-image | |
background-repeat | |
background-attachment | |
background-position | |
background | |
border properties | border-top-width |
border-right-width | |
border-bottom-width | |
border-left-width | |
border-width | |
border-top-color | |
border-right-color | |
border-bottom-color | |
border-left-color | |
border-color | |
border-top-style | |
border-right-style | |
border-bottom-style | |
border-left-style | |
border-short-style | |
border-top | |
border-right | |
border-bottom | |
border-left | |
border | |
counter properties | counter-reset |
counter-increment | |
color | |
font properties | font-family |
font-size | |
font-style | |
font-variant | |
font-weight | |
font | |
height properties | height |
min-height | |
max-height | |
line-height | |
margin properties | margin-top |
margin-right | |
margin-bottom | |
margin-left | |
margin | |
outline properties | outline-width |
outline-style | |
outline-color | |
outline | |
padding properties | padding-top |
padding-right | |
padding-bottom | |
padding-left | |
padding | |
quotes | |
text properties | direction |
letter-spacing | |
text-align | |
text-decoration | |
text-indent | |
text-transform | |
white-space | |
word-spacing | |
visibility | |
width properties | width |
min-width | |
max-width |
Properties that apply to the margin boxes can also be set within the
page context: if inheritable or explicitly inherited (with the
inherit
keyword on the margin box), they will inherit to
the margin boxes.
The following CSS 2.1 [CSS21] properties apply to margin
boxes. If a conforming user agents supports any of these properties on
block boxes, then it must also support that property for margin boxes
(except for z-index
, which is optional for margin boxes).
bidi properties | direction |
unicode-bidi | |
background properties | background-color |
background-image | |
background-repeat | |
background-attachment | |
background-position | |
background | |
border properties | border-top-width |
border-right-width | |
border-bottom-width | |
border-left-width | |
border-width | |
border-top-color | |
border-right-color | |
border-bottom-color | |
border-left-color | |
border-color | |
border-top-style | |
border-right-style | |
border-bottom-style | |
border-left-style | |
border-short-style | |
border-top | |
border-right | |
border-bottom | |
border-left | |
border | |
counter properties | counter-reset |
counter-increment | |
content | |
color | |
font properties | font-family |
font-size | |
font-style | |
font-variant | |
font-weight | |
font | |
height properties | height |
min-height | |
max-height | |
line-height | |
margin properties | margin-top |
margin-right | |
margin-bottom | |
margin-left | |
margin | |
outline properties | outline-width |
outline-style | |
outline-color | |
outline | |
overflow | |
padding properties | padding-top |
padding-right | |
padding-bottom | |
padding-left | |
padding | |
quotes | |
text properties | letter-spacing |
text-align | |
text-decoration | |
text-indent | |
text-transform | |
white-space | |
word-spacing | |
vertical-align | |
visibility | |
width properties | width |
min-width | |
max-width | |
z-index |
Often, but not always, the page box has a one-to-one correspondence to the physical surface onto which the document is ultimately rendered. The CSS3 page model specifies formatting within the page box, but it is the user agent's responsibility to transfer the page box to the sheet. Some user agent transfer possibilities that are not addressed by CSS3 include: