CSS @page Rule: Guide to Print Layout Configuration

The CSS @page at-rule is a core component of the CSS Paged Media module, designed specifically to control the formatting, dimensions, orientation, and margins of pages when printing web documents. This article explores the purpose of the @page rule, how it bridges the gap between fluid web viewports and fixed physical paper, and the practical properties used to create professional print layouts.

The Core Purpose of @page

Standard CSS targets a continuous, scrollable screen canvas. When a user prints a web page or exports it to PDF, the document must be divided into discrete physical pages. The @page at-rule targets the "page box"—an abstract representation of the physical sheet—allowing developers to define layout constraints that apply exclusively to printed output rather than on-screen containers.

Without @page, print output relies on browser defaults, which often include inconsistent margins, undesirable orientations, and poorly cropped content.

Defining Page Dimensions and Orientation

One of the primary functions of @page is the size property, which dictates the physical dimensions and orientation of the print medium:

  • Standard Paper Sizes: You can declare standard paper formats such as A4, A3, letter, or legal.
  • Orientation: You can specify portrait or landscape alongside paper sizes (e.g., size: A4 landscape;).
  • Custom Dimensions: You can set explicit physical measurements (e.g., size: 8.5in 11in; or size: 210mm 297mm;).
@page {
  size: A4 portrait;
  margin: 20mm;
}

Managing Margins and Page Padding

On the web, margins push elements away from other elements. Under @page, the margin property controls the blank area between the outer edge of the physical sheet and the printable content area. This ensures text and graphics do not get cut off by printer hardware margins or binding constraints.

Margins can be specified globally or independently using margin-top, margin-right, margin-bottom, and margin-left.

Targeting Specific Pages with Pseudo-Classes

Printed media often requires distinct layouts for different pages, such as omitting headers on a cover page or alternating margins for double-sided binding. The @page rule supports specific pseudo-classes to handle these scenarios:

  • :first: Targets the initial page of the printed document, useful for removing margins or custom headers on cover sheets.
  • :left and :right: Applies styles to even and odd pages respectively, enabling asymmetrical margins for bound books and booklets (often called "gutter" margins).
  • :blank: Applies styling to intentionally empty pages generated by forced page breaks.
/* Generates an offset margin for double-sided binding */
@page :left {
  margin-left: 30mm;
  margin-right: 15mm;
}

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

@page :first {
  margin-top: 0;
}

Named Pages for Section-Specific Layouts

The @page rule can be assigned a custom identifier to create named page contexts. Elements in the document can then reference this context using the page property:

@page landscape-section {
  size: landscape;
}

.wide-data-table {
  page: landscape-section;
}

When the browser encounters an element styled with page: landscape-section;, it triggers a page break and rotates that specific section into landscape orientation while leaving the rest of the document in portrait.

Conclusion

The CSS @page at-rule transforms standard web documents into structured, publication-ready physical documents. By controlling page dimensions, orientations, margins, and page-specific variations, developers can ensure that invoices, reports, and manuals render cleanly and predictably across printers and PDF generation tools.