CSS @page At-Rule

CSS @page At-Rule

The @page at-rule controls the dimensions, orientation, margins, and other formatting of printed pages. It allows developers to customize how HTML documents appear when printed or saved as PDF files, including setting different styles for the first page, left and right pages, and named page layouts.

@page Syntax

@page {
  size: auto;
  margin: 20mm;
}

The @page at-rule begins with the keyword @page, optionally followed by a page selector, and contains a block of page descriptors and page-margin at-rules.

Without a page selector, the rule applies to every printed page.

@page :first {
  margin-top: 30mm;
}

This example applies a larger top margin to the first printed page.

The main page descriptors include:

The specification also defines additional page properties, but browser support varies. Ordinary element declarations such as color and font-size should generally be placed in regular CSS style rules rather than directly inside @page.

How @page Works

When a browser prints a document, it divides the content into individual pages. Each page has a page box containing the printable content area and surrounding margins.

The @page at-rule defines properties of these page boxes rather than styling individual HTML elements.

@page {
  size: letter;
  margin: 1in;
}

This rule requests US Letter paper with one-inch margins on all sides.

The browser applies the page settings when the document is printed or saved as a PDF. They do not change the layout of the normal webpage displayed on the screen.

Print dialog settings, printer limitations, and browser implementations can affect the final output. For example, a user may select a different paper size or enable additional printer headers and footers.

Page Size and Orientation

The size descriptor specifies the dimensions and orientation of the page box.

Standard Paper Sizes

@page {
  size: A4;
}

This rule requests A4 paper.

Common supported size keywords include A3, A4, A5, letter, and legal.

Portrait and Landscape

@page {
  size: A4 portrait;
}

@page {
  size: A4 landscape;
}

The portrait keyword requests a page taller than it is wide. The landscape keyword requests a page wider than it is tall.

Custom Dimensions

@page {
  size: 6in 9in;
}

Two length values specify the page width followed by the height.

Absolute units such as in, mm, and cm are useful for printed layouts because they correspond to physical measurements.

Page Orientation Descriptor

@page {
  size: A4;
  page-orientation: rotate-left;
}

The page-orientation descriptor rotates the rendered page after layout. Unlike size: landscape, it does not change the dimensions used to lay out the content.

For most landscape printing requirements, size: landscape or a paper size combined with landscape is the simpler choice.

Page Margins

Page margins control the space between the edges of the page box and its content area.

Equal Margins

@page {
  margin: 20mm;
}

This rule sets all four margins to 20 millimeters.

Different Margins

@page {
  margin: 20mm 15mm 25mm 15mm;
}

The four values follow the same order as the CSS margin shorthand: top, right, bottom, and left.

Individual Margins

@page {
  margin-top: 25mm;
  margin-right: 15mm;
  margin-bottom: 25mm;
  margin-left: 15mm;
}

Individual margin descriptors are useful when a printed document needs extra space for a header, footer, or binding.

Page margins differ from the CSS margin property applied to HTML elements. Element margins control spacing around elements within the page content area.

Page Selectors

Page selectors allow different @page rules to apply to specific printed pages.

First Page

@page :first {
  margin-top: 40mm;
}

This example creates additional space at the top of the first printed page, which can be useful for a document title.

Left and Right Pages

@page :left {
  margin-left: 25mm;
  margin-right: 15mm;
}
@page :right {
  margin-left: 15mm;
  margin-right: 25mm;
}

These rules set different margins for left and right pages, which can be useful for double-sided documents.

Blank Pages

@page :blank {
  @top-center {
    content: none;
  }
  @bottom-center {
    content: none;
  }
}

This example removes the specified margin-box content from intentionally blank pages.

Page selectors are different from ordinary element pseudo-classes. They match generated printed pages rather than HTML elements.

Named Pages

Named pages allow different sections of a document to use different page layouts.

A name is assigned to an @page rule and referenced using the CSS page property on an element.

@page report {
  size: A4 portrait;
  margin: 20mm;
}
@page wide {
  size: A4 landscape;
  margin: 15mm;
}
.report {
  page: report;
}
.wide-table {
  page: wide;
}

Elements with the .report class request the portrait page layout, while elements with the .wide-table class request the landscape layout.

Combining Names and Page Selectors

@page report {
  margin: 20mm;
}
@page report:first {
  margin-top: 35mm;
}

The first rule defines margins for pages named report. The second rule overrides the top margin on the first page of that named page sequence.

Named pages are useful for reports, documents containing wide tables, and layouts that require different formatting for selected sections.

Page Margin Boxes

Page margin boxes are special regions around the printable content area. They can display information such as document titles, page numbers, and footer text.

Margin boxes are defined using nested at-rules inside @page.

@page {
  margin: 20mm;
  @top-center {
    content: "Website Report";
  }
  @bottom-center {
    content: "Page " counter(page);
  }
}

This example places a document title in the top-center margin and the current page number in the bottom-center margin.

Available Margin Box At-Rules

Each margin box occupies a specific region of the printed page. The content property determines what appears in the box.

Browser support for individual margin boxes and their styling capabilities may vary, especially in older browsers.

Page Numbers and Counters

CSS provides special counters for printed documents that can be used inside page margin boxes.

@page {
  margin: 20mm;
  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
  }
}

For a five-page document, the third page would display Page 3 of 5.

Removing Page Numbers from the First Page

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

The first rule displays page numbers. The second rule removes the page number from the first page while allowing numbering to continue on later pages.

Page counters are separate from counters used for numbered lists and other content within a webpage.

Print Styles and Page Breaks

The @page at-rule controls page formatting, while @media print controls the appearance of HTML elements when printed.

These features are commonly used together.

@page {
  size: A4;
  margin: 20mm;
}
@media print {
  nav,
  footer {
    display: none;
  }
  body {
    color: #000;
    background-color: #fff;
  }
}

The @page rule defines the paper size and margins. The @media print rule hides navigation and footer elements and adjusts the document colors.

Controlling Page Breaks

The break-before, break-after, and break-inside properties control how document content is divided across pages.

@media print {
  .chapter {
    break-before: page;
  }
  .card {
    break-inside: avoid;
  }
}

The .chapter class starts a new printed page. The .card class requests that its content remain together when possible.

Page breaks are controlled through ordinary CSS declarations on elements, not by placing break properties directly inside @page.

@page Example

The following example creates a print-friendly document with US Letter paper, one-inch margins, and page numbering.

HTML

<main>
  <h1>Website Design Report</h1>
  <p>This report demonstrates CSS print formatting.</p>
  <section>
    <h2>Introduction</h2>
    <p>Printed pages can use custom margins and page sizes.</p>
  </section>
  <section class="new-page">
    <h2>Page Two</h2>
    <p>This section starts on a new printed page.</p>
  </section>
</main>

CSS

@page {
  size: letter;
  margin: 1in;
  @bottom-center {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 10pt;
  }
}
@media print {
  body {
    font-family: Arial, sans-serif;
    color: #000;
  }
  .new-page {
    break-before: page;
  }
}

When printed, the document uses US Letter paper with one-inch margins. The second section begins on a new page, and the bottom margin displays the current page number and total page count.

Browser Support

The @page at-rule is Baseline Newly available since December 2024. Core page formatting is supported across current major browsers, but some descriptors, named page behavior, and margin-box features may have varying levels of support. See Can I Use? for compatibility information.

Specifications

The @page at-rule is defined in CSS Paged Media Module Level 3. The specification describes page boxes, page selectors, named pages, page descriptors, and margin boxes used when formatting documents for paged media.

CSS Paged Media Module Level 3