@page size ignored when rendering a PDF

Two rules decide the page geometry, and when they disagree people usually assume the API option wins. It does not.

The document's @page rule always wins.

Verified, in both directions

Rendered through Renderpaper on 2026-08-08. The document said A5, the request said A4:

@page { size: A5; margin: 10mm; }

{ "options": { "paper": "A4" } }

pdfinfo on the result:

Page size: 420 x 594.96 pts (A5)

The CSS won. Remove the @page rule from the document and the same request produces A4 — the option is a default, not an override.

Why it works that way

The renderer runs with PreferCSSPageSize enabled, which means a template that declares its own geometry keeps it regardless of what the caller sends.

That is deliberate, and the reasoning is worth stating because it is the opposite of what most APIs do: a template designed for A4 should not silently become Letter because a default changed somewhere else, or because a different service in your company sends a different option. The document is the specification. Whoever designed it decided how big it is.

So how do I change the size?

Change it where it is defined — in the template.

/* A4, the default nearly everywhere outside North America */
@page { size: A4; margin: 20mm; }

/* US Letter */
@page { size: Letter; margin: 0.75in; }

/* Landscape */
@page { size: A4 landscape; margin: 15mm; }

/* An exact size, for labels and tickets */
@page { size: 105mm 148mm; margin: 5mm; }

If you need one template to produce both A4 and Letter, do not fight the rule — drive it with data. Store the size as a merge field:

@page { size: {{.PaperSize}}; margin: 20mm; }

and send "PaperSize": "Letter" with the request. Now the caller controls it, the document still specifies it, and there is one template rather than two.

The other reason a size looks ignored

If @page is inside a @media print block, check the block itself:

/* This works — the renderer prints, so print rules apply. */
@media print { @page { size: A4; } }

But @media screen rules are not applied, which surprises people who develop the template in a browser tab. If your layout looks right on screen and wrong in the PDF, look for screen-only rules the renderer is correctly ignoring.

Margins

@page { margin: … } is the page margin. body { margin: … } is inside that, and the two add up — a common cause of "why is there so much white space at the top". Set the page margin and zero the body:

@page { size: A4; margin: 20mm; }
body  { margin: 0; }