<pre class='metadata'>

Title: CSS Paged Media Module Level 3

Shortname: css-page

Level: 3

Status: ED

Remove Multiple Links: false

Work Status: Revising

Group: csswg

ED: https://drafts.csswg.org/css-page-3/

TR: https://www.w3.org/TR/css-page-3/

Issue Tracking: Tracker http://www.w3.org/Style/CSS/Tracker/products/13

Editor: Elika J. Etemad / fantasai, Apple&#44; formerly Mozilla, http://fantasai.inkedblade.net/contact, w3cid 35400

Former Editor: Simon Sapin, Mozilla&#44; formerly Kozea, http://exyr.org/about/, w3cid 58001

Former Editor: Melinda Grant, HP

Former Editor: Håkon Wium Lie, Opera Software

Former Editor: Jim Bigelow, Hewlett-Packard

Former Editor: Jacob Refstrup, Hewlett-Packard

Former Editor: Robert Stevahn, Hewlett-Packard

Ignored terms: fit, fit-position, stacking context

Abstract: This CSS module specifies how pages are generated and laid out to hold fragmented content in a paged presentation. It adds functionality for controlling page margins, page size and orientation, and headers and footers, and extends generated content to enable page numbering and running headers / footers. The process of paginating a flow into such generated pages is covered in [[!CSS-BREAK-3]].

</pre>

<pre class=link-defaults>

spec:css-borders-4; type:property;

text:border-bottom-width

text:border-top-width

spec:css-break; type:property; text:break-after

spec:css-values; type:value; text:ex

spec:css2; type: property

text: counter-increment

text: counter-reset

text: display

text: margin

text: max-height

text: max-width

text: min-height

text: min-width

</pre>

<style>

#margin-values { border-collapse: collapse; }

#margin-values td,

#margin-values th

{

padding: 0.2em;

border: thin solid black;

}

.property-list

{

border: 1px solid black;

padding: .2em;

margin-top: 2em;

}

.property-list td

{

border: 1px solid black;

padding: .1em;

}

table.page-sizes

{

border: thin solid;

margin-top: 1.5em;

}

table.page-sizes td

{

border: thin solid;

padding: .5em;

}

table.page-sizes th

{

border: thin solid;

padding: .5em;

background: #ffffaa;

}

</style>

<h2 id="intro">

Introduction</h2>

<div class=non-normative>

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:

<ul>

<li><a href="#page-breaks">page breaks</a> are created and avoided;

<li>the page properties such as size, orientation, margins, border, and

padding are specified;

<li>headers and footers are established within the page margins; and

<li>content such as page counters are placed in the headers and footers;

</ul>

This module defines a <a href="#page-model">page model</a> that specifies how a

document is formatted within a rectangular area, called the

<a href="#page-box-page-rule">page box</a>, 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 <a href="#page-size">size and orientation</a>. In the general case,

CSS3 assumes that one page box will be transferred to one surface of similar

size.

Note: The [[CSS-BREAK-4]] specification

addresses controls over [=fragmentation=] (pagination),

such as the 'break-before', 'break-after', 'break-inside',

'widows', and 'orphans' properties.

</div>

<h3 id="values">

Value Definitions</h3>

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]

using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].

Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].

Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions,

all properties defined in this specification

also accept the <a>CSS-wide keywords</a> as their property value.

For readability they have not been repeated explicitly.

<h2 id="page-terms">

Page Terminology</h2>

The following terminology and accompanying diagrams help to describe the

page model:

<dl>

<dt><dfn export>Page sheet</dfn>

<dd>

<img src="images/PageSheet.png" style="float: right;" alt="The corner of a page sheet with the non-printable area at the edge and printable area inside it" height="148" width="194">

The page sheet is one surface of the physical

medium. The illustration to the right shows a representation of the upper-left

corner of a page sheet.

<dt><dfn export lt="printable area">Printable and non-printable areas</dfn>

<dd>

The non-printable area is the area of a page sheet that a physical device such

as a printer is not capable of marking reliably, usually due to the printer's

paper handling mechanism. This value is printer dependent and is usually a

small region along each edge of the page sheet. The printable area is the area

of page sheet that a printer <em>is</em> capable of marking reliably. The size

of the printable area is the size of the page sheet reduced by the size of the

non-printable area. A user agent may not know the dimensions of this area for a

particular printing device; but when its dimensions are known, user agents

may adjust the formatting of the document so that

content falls within the printable area. How this adjustment is accomplished is

device dependent within the constraints expressed in the sections

[[#renderingpages]] and [[#content-outside-box]].

<dt><dfn export>Page Orientation</dfn>

<dd>

The page orientation is defined by comparing the length of the edges of a

<a>page box</a>. The page box is a rectangle with two

perpendicular edges called the long edge and the short edge. The length of the

long edge is always greater than or equal to the length of the short edge. When

the page box is square, the two edges are of the same length and either can be

used as the long edge with the other being the short edge. This specification

defines page orientations of ''portrait'' and ''landscape''.

<dt><dfn export lt="portrait|portrait orientation">Portrait Orientation</dfn>

<dd>

A portrait page's height is greater than or equal to its width. Horizontal

elements are parallel to the short edge and vertical elements to the long edge.

<dt><dfn export lt="landscape|landscape orientation">Landscape Orientation</dfn>

<dd>

A landscape page's width is greater than or equal to its height. Horizontal

elements are parallel to the long edge and vertical elements to the short edge.

Note: Note that CSS3 makes no distinction between landscape and

reverse-landscape orientations. However, future versions of CSS may do so.

UAs should consider, when formatting for duplexed printing, the binding edge,

page progression, and ease of reading when choosing between landscape and

reverse-landscape renderings.

<dt><dfn export>Duplex Printing</dfn>

<dd>

Duplex printing prints one page box per side of a page sheet and uses both

sides of the page sheet. This module provides no ability to specify whether a

document is duplex printed, but the concept of left and right pages is based on

the assumption that the document is duplex printed, regardless of whether or

not it actually is.

<dt><dfn export>Binding Edge</dfn>

<dd>

The binding edge is the edge of the page box that is toward the binding if the

material is bound. The binding edge often has a larger margin than the opposite

edge to provide for the space used by the binding. The binding edge can be any

of the four edges. However, page sheets are customarily bound so that the

binding edge of page boxes with portrait orientation is vertical. This module

provides no method to specify the binding edge. In duplex printing, the binding

edge is on opposite sides of the page box for the left and right pages.

<dt><dfn export>Facing Pages</dfn>

<dd>

Facing pages are two sequential pages such that when the document is duplex

printed they are on separate sheets of paper. Typically, the earlier page will

be the back side of one sheet and the later page will be the front side of

another. They are usually laid out so that the binding edges of facing pages

are vertical and adjacent when the pages are placed in their normal reading

orientation.

<dt><dfn export>Left Page</dfn>

<dd>

A page that would be on the left if it is part of a pair of facing pages as

typically laid out. Page layouts for documents using a left-to-right page

progression have the earlier of the facing pages on the left. Rules specific to

the left page can be specified using the '':left'' <a>page selector</a>.

<dt><dfn export>Right Page</dfn>

<dd>

A page that would be on the right if it is part of a pair of facing pages as

typically laid out. Page layouts for documents using a right-to-left page

progression have the earlier of the facing pages on the right. Rules specific

to the right page can be specified using the '':right'' <a>page selector</a>.

</dl>

<h2 id="page-model">The Page Model</h2>

In the [=paged media=] formatting model, the document is transferred into one

or more page boxes. The <dfn export>page box</dfn> 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 <a href="https://www.w3.org/TR/CSS2/visuren.html#viewport">viewport</a>.

<img src="images/PageBox.png" style="float: right;" alt="" height="266" width="267">

As with other CSS <a href="https://www.w3.org/TR/CSS2/box.html">boxes</a>, a page box

consists of margin, border, padding, and content areas. The content and

margin areas of a page box have special functions:

Issue: In CSS 2.1, both the page box and page area are simple rectangles.

Neither is a CSS box with margins, borders, and padding.

This CSS box should be distinct from the page box and page area,

which would be its margin area and content area, respectively.

Naming ideas?

<ul>

<li>

The content area of a page box is called the <dfn export>page area</dfn>.

The content of the document is flowed into one or more page boxes.

The page area acts as a container for all the boxes generated by the root

element and its descendants that are laid out within a given page box. The

edges of the page area on the first page establish the rectangle that is the

initial <a>containing block</a>

of the document.

<li>

The margin area of a page box is divided into

16 <dfn export>page-margin boxes</dfn>.

Each page-margin box has its own margin, border, padding and content areas.

Page-margin boxes are typically used to display running headers and footers.

</ul>

The properties of a <a>page box</a> are determined by properties

declared within the <a>page context</a>, which is the

<a href="https://www.w3.org/TR/CSS2/syndata.html#x14">declaration block</a> of the

''@page'' rule. Similarly the properties of a <a>page-margin box</a>

are determined by properties declared within its <a>margin context</a>.

Declarations in the page context can affect the page box and/or inherit

to the page-margin boxes, but they do not apply to or inherit into the

document's root element or other content.

The <a>containing block</a> of the page box is specified using the '@page/size'

property in the <a>page context</a>. The width and horizontal margins

of the page box are then calculated exactly as for a

<a href="https://www.w3.org/TR/CSS2/visudet.html#blockwidth">non-replaced block element in normal flow</a>. [[!CSS2]]

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.

<h3 id="painting">

Page Backgrounds and Painting Order</h3>

When drawing a page of content, the page layers are painted in the

following painting order (bottommost first):

<ol>

<li>page background

<li>document canvas

<li>page borders

<li>document contents

<li>page-margin boxes

</ol>

In the page model, the page background behaves similar to the root background:

its <a spec=css-backgrounds>background painting area</a> is the <a>bleed area</a>,

which covers the entire page box, including its margins (regardless of 'background-clip').

Page backgrounds are anchored within the page box's padding area by default

(and honor 'background-origin' if the UA supports [[!CSS-BACKGROUNDS-3]]).

However if 'background-attachment' is ''background-attachment/fixed''

then the image is positioned relative to the page box including its margins

(i.e. the <a spec=css-backgrounds>background positioning area</a>

is the page's margin box).

The document canvas background is drawn as the page box's background:

by default its <a spec=css-backgrounds>background painting area</a> covers the page box's border box,

and for UAs that support [[!CSS-BACKGROUNDS-3]], follows the 'background-clip' value specified on the root element.

It remains, however, positioned with respect to the root element

or page area as usual.

With respect to the page-margin boxes,

the document canvas, page borders, and all of the document contents

are treated as a single element with a <code>z-index</code> value of ''0''

that establishes a

<a>stacking context</a>

[[!CSS2]]:

the page-margin boxes never interleave with parts of the document content

or between the content and the canvas.

They may only paint in front of the document content

or behind the document canvas.

The page background is always painted underneath everything else.

The 'z-index' property applies to page-margin boxes.

Since the 'position' property does not apply to page-margin boxes,

'z-index' always affects page-margin boxes as if they were positioned elements

regardless of the 'position' property's value.

Each page-margin boxes always establishes a stacking context.

The default painting order,

or <a href="https://www.w3.org/TR/CSS2/zindex.html">CSS2.1 Appendix E</a> "tree order",

of page-margin boxes with respect to each other is as follows:

<ol>

<li>''@top-left-corner''

<li>''@top-left''

<li>''@top-center''

<li>''@top-right''

<li>''@top-right-corner''

<li>''@right-top''

<li>''@right-middle''

<li>''@right-bottom''

<li>''@bottom-right-corner''

<li>''@bottom-right''

<li>''@bottom-center''

<li>''@bottom-left''

<li>''@bottom-left-corner''

<li>''@left-bottom''

<li>''@left-middle''

<li>''@left-top''

</ol>

<p class=note>

Start with ''@top-left-corner'', then go clockwise.

This order is arbitrary but can be overridden with 'z-index'.

It only has a visible effect when page-margin boxes overlap,

which should not happen in most cases.

<h3 id="content-outside-box">Content outside the page box</h3>

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:

<ul>

<li>Content should be allowed slightly beyond the page box to allow pages

to "bleed".

<li>User agents <em class="RFC2119">SHOULD</em> 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 <dfn export id="content-empty">Content-empty page</dfn> 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 ''visibility/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 page-margin box content <em>is</em> a

content-empty page.

<p class="note">Note, however, that generating a small number of empty page

boxes is sometimes necessary to honor the forced-break values for

'page-break-before'/'break-before' and 'page-break-after'/'break-after'.

[[!CSS2]] [[!CSS-BREAK-3]]

<li>Authors <em class="RFC2119">SHOULD NOT</em> position elements in

inconvenient locations just to avoid rendering them. Instead:

<ul>

<li>To suppress box generation entirely, set the 'display' property to ''display/none''.

<li>To make a box invisible, set the <span class="property">'visibility'</span>

property.

</ul>

<li>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.

</ul>

<h3 id="progression">Page Progression</h3>

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 <a href="#left-right-first"><code>:left</code> and <code>:right</code> pseudo-classes</a>.

Whether the first page of a document is a left page or a right page

depends on the page progression of the document.

The <dfn export>page progression</dfn>

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.

The page progression direction is determined as follows:

<ul>

<li>If text is laid out in horizontal lines,

the <a>page progression</a> is the same as the <a>inline base direction</a>.

<li>If text is laid out in vertical lines,

the <a>page progression</a> is the same as the <a>block flow direction</a>.

</ul>

If the UA supports the 'direction' and 'writing-mode' properties

from the CSS 3 Writing Modes Module [[CSS-WRITING-MODES-3]], it must

<a href="https://www.w3.org/TR/css3-writing-modes/#page-direction">determine</a>

the <a>page progression</a> is determined by the <a>principal writing mode</a>.

In documents with a left-to-right <a>page progression</a>

the first page of the document is a right page, and vice versa.

To explicitly force a document to begin printing on a left or right page,

authors can specify a 'break-before' value

that that propagates a page break to the root. [[!CSS-BREAK-3]]

The UA must suppress the first (empty) page(s) in this case

(and the <code>:first</code> pseudo-class matches the first printed page).

<div class="example">

<pre>

html { break-before: always }

</pre>

For an HTML document with a left-to-right page progression,

the above style rule will cause the first page of the document

to print on a ':left' page

<pre>

html { break-before: left }

</pre>

For an HTML document,

the above style rule will cause the first page of the document

to print on a ':left' page,

regardless of the page progression.

</div>

<h2 id="page-selector-and-context">

Page Selectors and the Page Context</h2>

<h3 id="at-page-rule" oldids="page-box-page-rule">

The @page Rule</h3>

Authors can specify various aspects of a page box,

such as its dimensions, orientation, and margins,

within an <dfn>@page</dfn> rule.

''@page'' rules are allowed

wherever <a href="https://www.w3.org/TR/CSS2/syndata.html#rule-sets">rule-sets</a> are allowed.

An ''@page'' rule consists of the keyword ''@page'',

an optional comma-separated list of

<a>page selectors</a>

and a block of declarations

(said to be in the <dfn export id="page-context">page context</dfn>).

An ''@page'' rule can also contain other at-rules,

interleaved between declarations.

The current level of this specification

only allows <a>margin at-rules</a> inside ''@page''.

''@page'' rules without a selector list apply to every page.

Other ''@page'' rules apply to pages that <a>match</a>

at least one of their selectors.

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 <a href="https://www.w3.org/TR/CSS2/syndata.html#parsing-errors">Rules for handling parsing errors</a>

apply; that is, valid declarations within the block are applied.

<h3 id="page-selectors">Page selectors</h3>

A <dfn export id="page-selector">page selector</dfn> is made of

either a <a>page type selector</a>

or a <a>page pseudo-class</a>,

followed by zero or more additional <a>page pseudo-classes</a>.

No whitespace is allowed between components of a selector.

The <<page-selector>> grammar

and examples can be found below.

A <a>page selector</a> is said to <dfn>match</dfn> a given page if and only if

all of its components match the page.

A <dfn export>page type selector</dfn> is

a case-sensitive <a href="https://www.w3.org/TR/CSS2/syndata.html#value-def-identifier">CSS identifier</a> [[!CSS2]].

It <a>matches</a> pages of the <a href="#using-named-pages">named page type</a>

generated by the 'page' property.

<span id="page-selector-syntax-restrict">

A page type name of ''page/auto''

(<a href="https://www.w3.org/TR/CSS2/syndata.html#characters">ASCII case-insensitive</a>)

does not make the rule invalid,

but must never match.

</span>

A <dfn export>page pseudo-class</dfn> is <a href="https://www.w3.org/TR/CSS2/syndata.html#characters">ASCII case-insensitive</a>

and has the same syntax as <a href="https://www.w3.org/TR/selectors/#pseudo-classes">pseudo-classes</a> in regular Selectors. [[!SELECT]]

The various <a>page pseudo-classes</a> are defined below.

<h4 id="spread-pseudos"><span id="left-right-first"></span>

Spread pseudo-classes: '':left'', '':right''</h4>

When printing double-sided documents,

left and right pages are often formatted differently.

This can be expressed by using the '':left'' and '':right'' page pseudo-classes.

<p dfn-type="value" dfn-for="@page">All pages are automatically classified by user agents

as either left pages or right pages,

based on <a href="#progression">page progression</a>.

The <dfn>:left</dfn> and <dfn>:right</dfn> pseudo-classes

only <a>match</a> <a lt="left page">left</a> or <a lt="right page">right pages</a>,

respectively.

<div class="example">

The following example creates left and right binding edges using these pseudo-classes:

<pre>

@page :left {

margin-left: 3cm;

margin-right: 4cm;

}

@page :right {

margin-left: 4cm;

margin-right: 3cm;

}

</pre>

</div>

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).

<div class="note">

<em><strong>Note.</strong>

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).</em>

</div>

<h4 id="first-pseudo">

First-page pseudo-class: '':first''</h4>

The <dfn dfn-type="value" dfn-for="@page">:first</dfn> pseudo-class <a lt="match">matches</a>

the first printed page of a document.

<div class="example">

<pre>

@page { margin: 2cm } /* All margins set to 2cm */

@page :first {

margin-top: 10cm /* Top margin on first page 10cm */

}

</pre>

</div>

<h4 id="blank-pseudo">

Blank-page pseudo-class: ''@page/:blank''</h4>

The <dfn dfn-type="value" dfn-for="@page">:blank</dfn> pseudo-class <a lt="match">matches</a>

<a lt="content-empty page">content-empty pages</a>

that appear as a result of

<a href="https://www.w3.org/TR/css3-break/#forced-breaks">forced page breaks</a>.

<div class="note">

Only the ''break-before/left'', ''break-before/right'', ''break-before/recto'' and ''break-before/verso'' values

of the 'break-before' and 'break-after' properties

can generate pages that match ''@page/:blank''.

</div>

<div class="example">

In this example, forced page break may occur before <code>h1</code> elements.

<pre>

h1 { break-before: left }

@page :blank {

@top-center { content: "This page is intentionally left blank" }

}

</pre>

</div>

A page matched by ''@page/:blank'' can also be matched

by other page pseudo-classes.

<div class="example">

If headers have been specified on all right pages, a blank right

page will be matched by both <code>:blank</code>

and <code>:right</code>. Therefore, margin boxes set on right pages

will have to be removed unless they are wanted on blank pages. Here is

an example where the top center header is removed from blank pages,

while the page number remains:

<pre>

h1 { break-before: left }

@page :blank {

@top-center { content: none }

}

@page :right {

@top-center { content: "Preliminary edition" }

@bottom-center { content: counter(page) }

}

</pre>

Due to the higher <a>specificity</a> of <code>:blank</code>

over <code>:right</code>, the top center header is removed even

if <code>content: none</code> comes before <code>content: "Preliminary

edition"</code>.

</div>

<div class="note">

<em><strong>Note.</strong> Future versions of CSS may include other page

pseudo-classes.</em>

</div>

<h3 id="syntax-page-selector">@page rule grammar</h3>

''@page'' rules are [=CSS/parsed=] according to the following grammar,

plus the additional rules noted below:

<pre class=prod>

@page = @page <<page-selector-list>>? { <<declaration-rule-list>> }

<dfn><<page-selector-list>></dfn> = <<page-selector>>#

<dfn><<page-selector>></dfn> = [ <<ident-token>>? <<pseudo-page>>* ]!

<dfn><<pseudo-page>></dfn> = : [ left | right | first | blank ]

/* Margin rules */

<dfn for="@page">@top-left-corner</dfn> = @top-left-corner { <<declaration-list>> };

<dfn for="@page">@top-left</dfn> = @top-left { <<declaration-list>> };

<dfn for="@page">@top-center</dfn> = @top-center { <<declaration-list>> };

<dfn for="@page">@top-right</dfn> = @top-right { <<declaration-list>> };

<dfn for="@page">@top-right-corner</dfn> = @top-right-corner { <<declaration-list>> };

<dfn for="@page">@bottom-left-corner</dfn> = @bottom-left-corner { <<declaration-list>> };

<dfn for="@page">@bottom-left</dfn> = @bottom-left { <<declaration-list>> };

<dfn for="@page">@bottom-center</dfn> = @bottom-center { <<declaration-list>> };

<dfn for="@page">@bottom-right</dfn> = @bottom-right { <<declaration-list>> };

<dfn for="@page">@bottom-right-corner</dfn> = @bottom-right-corner { <<declaration-list>> };

<dfn for="@page">@left-top</dfn> = @left-top { <<declaration-list>> };

<dfn for="@page">@left-middle</dfn> = @left-middle { <<declaration-list>> };

<dfn for="@page">@left-bottom</dfn> = @left-bottom { <<declaration-list>> };

<dfn for="@page">@right-top</dfn> = @right-top { <<declaration-list>> };

<dfn for="@page">@right-middle</dfn> = @right-middle { <<declaration-list>> };

<dfn for="@page">@right-bottom</dfn> = @right-bottom { <<declaration-list>> };

</pre>

In addition, the following rules apply:

* No whitespace is allowed between the productions in <<page-selector>> or <<pseudo-page>>

(similar to the rule for <<compound-selector>>).

* The ''@page'' rule can only contain <a>page properties</a> and <a>margin at-rules</a>.

* The <a>margin at-rules</a> can only contain <a>page-margin properties</a>.

<div class="example">

The following are examples of page selectors (declaration block intentionally

left blank)

<pre>

@page { ... }

@page :left { ... }

@page :right { ... }

@page LandscapeTable { ... }

@page CompanyLetterHead:first { ... } /* identifier and pseudo page. */

@page:first { ... }

@page toc, index { ... }

@page :blank:first { ... }

</pre>

The following are examples of page-margin boxes

where the declaration blocks are intentionally left blank.

<pre>

@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 */ } }

</pre>

</div>

<h3 id="cascading-and-page-context">Cascading in the page context</h3>

Declarations in page and margin contexts <a href="https://www.w3.org/TR/CSS2/cascade.html">cascade</a> just like declarations in style rule for elements.

The <dfn>specificity</dfn> of a page selector is computed in a manner

analogous to the computations defined in

the <a href="https://www.w3.org/TR/CSS2/selector.html">Selectors</a> module:

<ul>

<li>Count the number of page type names (= <var>f</var>)

<p class="note">

Given the syntax of page selectors, <var>f</var> can only ever be 0 or 1.

<li>Count the number of ':first' or ':blank' pseudo-classes (= <var>g</var>)

<li>Count the number of ':left' or ':right' pseudo-classes (= <var>h</var>)

</ul>

<p class="note">

Note: Repeated occurrences of the same pseudo-classes are allowed

and do increase specificity.

Due to storage limitations,

implementations may have limitations on

the size of <var>f</var>, <var>g</var>, or <var>h</var>.

If so, values higher than the limit must be clamped to that limit,

and not overflow.

Specificities are compared by comparing the three components in order

(<var>f</var>, <var>g</var>, <var>h</var>):

the specificity with a larger <var>f</var> value is more specific;

if the two <var>f</var> values are tied,

then the two <var>g</var> values are compared, etc.

If all the values are tied, the two specificities are equal.

<div class="example">

Some page specificity calculation examples follow:

<pre>

@page { } /* specificity = (0,0,0) */

@page :left { } /* specificity = (0,0,1) */

@page :first { } /* specificity = (0,1,0) */

@page :blank:left { } /* specificity = (0,1,1) */

@page artsy { } /* specificity = (1,0,0) */

@page artsy:left { } /* specificity = (1,0,1) */

@page artsy:first { } /* specificity = (1,1,0) */

</pre>

</div>

<div class="example">

Consider the following usage example:

<pre>

@page :left {

margin-left: 4cm;

}

@page {

margin-left: 3cm;

}

</pre>

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.

</div>

<div class="example">

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 page-margin box

and green text in the top-right page-margin box,

while subsequent pages will have red text in the page-margin boxes.

<pre>

@page :first {

color: green;

@top-left {

content: "foo";

color: blue;

}

@top-right {

content: "bar";

}

}

@page { color: red;

@top-center {

content: "Page " counter(page);

}

}

</pre>

</div>

<div class="example">

Page contexts cascade, so the following stylesheet would style pages with 25

millimeter margins and 14 point type in the page-margin boxes:

<pre>

@page { margin: 25mm;}

@page { font-size: 14pt;}

</pre>

</div>

<h2 id="margin-boxes">Page-Margin Boxes</h2>

Page-margin boxes are boxes within the page margin that,

like pseudo-elements, can contain generated content.

Page-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.

<div class="example">

Typically, a <dfn export>page header</dfn> is located at the top of the page

in documents with a predominately horizontal writing direction

and on the side opposite the <a>binding edge</a>

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''

page-margin boxes.

Another design, for vertically written documents, could use the

''@right-top'', ''@right-middle'', and ''@right-bottom'' page-margin boxes

for <a lt="right page">right facing pages</a> and

''@left-top'', ''@left-middle'', and ''@left-bottom''

for <a lt="left page">left facing pages</a>.

The <dfn export>page footer</dfn> 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''

page-margin boxes as the page footer.

The design of a vertically written document could use

the page-margin boxes of the binding edge of the page for the page footer.

</div>

Page-margin boxes are positioned with respect to the page area

and are independent of page orientation,

for example the top page-margin boxes are above the page area

in both portrait and landscape orientation.

The various page-margin boxes are defined

and illustrated in the diagram below:

<table id="margin-box-def" class="data">

<caption>Table 1 Page-Margin Box Definitions</caption>

<thead>

<tr>

<th>Box

<th>Description

<th>Placement

<tbody>

<tr id="top-margin-boxes-def">

<th id="top-left-corner-box-def">top-left-corner

<td>a fixed-size box defined by the intersection of the top and left margins of the

page box

<td><img src="images/TopLeftCornerBox.png" alt="the top left corner box with margin, border, and padding, nested within intersection of the page's top and left margins"

height="47" width="181">

<tr id="top-left-box-def">

<th>top-left

<td>a variable-width box filling the top page margin between the top-left-corner

and top-center page-margin boxes

<td><img src="images/TopLeftMarginBox.png" alt="the top left box with margin, border, and padding, nested in the page's top margin next to the top left corner box"

height="47" width="181">

<tr id="top-center-box-def">

<th>top-center

<td>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

page-margin boxes

<td><img src="images/TopCenterMarginBox.png" alt="the top center box with margin, border, and padding, centered within the page's top margin"

height="47" width="181">

<tr id="top-right-box-def">

<th>top-right

<td>a variable-width box filling the top page margin between the top-center and

top-right-corner page-margin boxes

<td><img src="images/TopRightMarginBox.png" alt="the top right box with margin, border, and padding, nested within the page's top margin"

height="47" width="181">

<tr>

<th id="top-right-corner-box-def">top-right-corner

<td>a fixed-size box defined by the intersection of the top and right margins of

the page box

<td><img src="images/TopRightCornerMarginBox.png" alt="the top right corner box with margin, border, and padding, nested within the intersection of the page's top and right margin"

height="47" width="181">

<tr id="left-margin-boxes-def">

<th id="left-top-box-def">left-top

<td>a variable-height box filling the left page margin between the top-left-corner

and left-middle page-margin boxes

<td rowspan="3"><img src="images/LeftMarginBoxes.png" alt="left-top, left-middle, and left-bottom page-margin boxes in the page box's left margin"

height="226" width="181">

<tr id="left-middle-box-def">

<th>left-middle

<td>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 page-margin boxes

<tr id="left-bottom-box-def">

<th>left-bottom

<td>a variable-height box filling the left page margin between the left-middle and

bottom-left-corner page-margin boxes

<tr id="right-margin-boxes-def">

<th id="right-top-box-def">right-top

<td>a variable-height box filling the right page margin between the

top-right-corner and right-middle page-margin boxes

<td rowspan="3"><img src="images/RightMarginBoxes.png" alt="right-top, right-middle, and right-bottom page-margin boxes in the page box's right margin"

height="226" width="181">

<tr id="right-middle-box-def">

<th>right-middle

<td>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 page-margin boxes

<tr id="right-bottom-box-def">

<th>right-bottom

<td>a variable-height box filling the right page margin between the right-middle

and bottom-right-corner page-margin boxes

<tr id="bottom-margin-boxes-def">

<th id="bottom-left-corner-box-def">bottom-left-corner

<td>a fixed-size box defined by the intersection of the bottom and left margins of

the page box

<td><img src="images/BottomLeftCornerBox.png" alt="bottom left corner box with margin, border, and padding, nested within the page margin at the intersection of the left and bottom page margins"

height="48" width="181">

<tr id="bottom-left-box-def">

<th>bottom-left

<td>a variable-width box filling the bottom page margin between the

bottom-left-corner and bottom-center page-margin boxes

<td><img src="images/BottomLeftMarginBox.png" alt="bottom left page-margin box with margin, border, and padding, nested within the page's bottom margin next to the bottom-left-corner box"

height="48" width="181">

<tr id="bottom-center-box-def">

<th>bottom-center

<td>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 page-margin boxes

<td style="vertical-align: middle;"><img src="images/BottomCenterMarginBox.png" alt="bottom center box with margin, border, and padding, nested within the page's bottom margin and centered on the page"

height="48" width="181">

<tr id="bottom-right-box-def">

<th>bottom-right

<td>a variable-width box filling the bottom page margin between the bottom-center

and bottom-right-corner page-margin boxes

<td><img src="images/BottomRightMarginBox.png" alt="bottom right page-margin box with margin, border, and padding, nested within the page's bottom margin and next to the bottom-right-corner box"

height="48" width="181">

<tr id="bottom-right-corner-box-def">

<th>bottom-right-corner

<td>a fixed-size box defined by the intersection of the bottom and right margins of

the page box

<td><img src="images/BottomRightCornerBox.png" alt="bottom right corner box with margin, border, and padding, nested within the page margin at the intersection of the right and bottom page margins"

height="48" width="181">

</table>

<h3 id="margin-at-rules">At-rules for page-margin boxes</h3>

Page-margin boxes are created by

<a>margin at-rules</a>

inside the <a href="#page-context">page context</a>.

Authors should put these rules after any declarations in the page context

as legacy clients may not handle declarations

after margin at-rules correctly.

A <dfn id="margin-at-rule">margin at-rule</dfn> is an <a>at-rule</a>

that identifies the page-margin box

(e.g. ''@top-left'') and a block of descriptors

(said to be in the <dfn export id="margin-context">margin context</dfn>).

<div class="example">

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:

<pre>

@page {

size: 8.5in 11in;

margin: 10%;

@top-left {

content: "Hamlet";

}