The page box / page (named pages)
How to make one section landscape in a portrait PDF
A named @page rule plus the page property on an element lets one part of a document use a different page box from the rest.
What it is for
A financial report is portrait except for the one wide table that is not. Without named pages the choice is one orientation for the whole document, or two documents.
Support: Only in dedicated print engines
This is the clearest example of the split. Dedicated print engines implement named pages; browser engines largely do not, so the property is accepted and has no effect.
The syntax
Written the way it would appear in a document stylesheet, using page (named pages) as intended.
/* The specification version, which a print engine honours: */
@page landscape { size: A4 landscape; }
.wide-table { page: landscape; }
/* What actually works in a browser-based render: render the landscape section
as its own document and merge the two. */
const portrait = await render(bodyHtml, { format: "A4" });
const landscape = await render(tableHtml, { format: "A4", landscape: true });
const combined = await merge([portrait, landscape]);The mistake people make
Writing the named-page version, seeing no error, and concluding the syntax is wrong. It is not wrong, it is unimplemented, which produces exactly the same silence.
Frequently asked
Does page (named pages) work when generating a PDF?
Only in dedicated print engines. This is the clearest example of the split. Dedicated print engines implement named pages; browser engines largely do not, so the property is accepted and has no effect.
How would I know if it were not working?
You would not, from the CSS. Unimplemented and unmatched CSS both fail silently, which is why the reliable test is to set a deliberately extreme value and see whether anything changes. If a 40mm margin looks the same as an 18mm one, the rule is not reaching the page.
Related properties
Things that come up in the same part of a document stylesheet.
How to use the @page rule for PDF output
@page. Works in a browser-based render.
How to set the PDF page size in CSS
size. Works in a browser-based render.
How to set PDF page margins in CSS
margin (in @page). Works in a browser-based render.
How to style the first page differently in a PDF
@page :first, :left, :right. Works in a browser-based render.
How to put a running header in a PDF with CSS
@top-center and the margin boxes. Does nothing in a browser-based render.
Every property, with its support status
The full reference, grouped by what part of the page it touches.
Paste the CSS and see what the rendered page does with it.