# PDF page size, margins and page breaks

Control the page size, margins, headers and footers, and read the tips that help real documents come out right.

## The options object

Add `options` to a request to control the page:

```json
{"html": "...", "options": {"format": "Letter", "landscape": true, "margins": {"top": "20mm", "bottom": "20mm"}}}
```

| Option | Values |
| --- | --- |
| `format` | `A4` (default), `Letter`, `Legal`, `A3`, `A5` |
| `landscape` | `true` or `false` (default) |
| `margins` | `top`, `right`, `bottom`, `left` as lengths such as `10mm`, `1in` or `20px`; each is `10mm` by default |
| `scale` | `0.1` to `2.0` (default `1`) |
| `print_background` | `true` (default) prints background colours and images; `false` leaves them out |
| `prefer_css_page_size` | `true` to use the page size from your CSS `@page` rule |
| `header_template`, `footer_template` | HTML for a header and footer on every page (see below) |
| `wait_until` | `load` (default) or `networkidle` |
| `javascript` | `true` (default) runs scripts in your page; `false` turns them off |

If a value is not valid, you get `400 INVALID_OPTIONS` with a message that names the option and what it accepts.

## Headers and footers with page numbers

The templates are small HTML snippets. Give them a font size (the default is tiny) and leave room for them with the margins. These placeholders are filled in on every page: `pageNumber`, `totalPages`, `date` and `title`.

```json
"options": {
  "margins": {"top": "25mm", "bottom": "20mm"},
  "header_template": "<div style='font-size:9px; width:100%; text-align:center; font-family:sans-serif'>ACME Ltd. Invoice</div>",
  "footer_template": "<div style='font-size:9px; width:100%; text-align:center; font-family:sans-serif'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"
}
```

## Page breaks

Content flows onto as many pages as it needs (up to 20). To start a new page, use CSS: `<section style="break-before: page">`. To keep something in one piece, such as a table row, use `break-inside: avoid`.

## Page size in CSS

If your stylesheet already has an `@page { size: ...; margin: ... }` rule, set `"prefer_css_page_size": true` and Stolid PDF follows it.

## Page numbers and footers in CSS

Stolid PDF renders with Chromium. Test the print CSS your templates depend on: a few features behave differently from other layout engines and produce no warning. It supports `@page` margin boxes such as `@bottom-right { content: "Page " counter(page) " of " counter(pages); }`, and the `:first`, `:left` and `:right` page selectors. A few print CSS features behave differently, and the render report does not warn about them:

- `counter(page)` and `counter(pages)` print `0` in normal page content. Use them in a margin box, or use `footer_template`.
- `@page :nth(3)` is ignored, so its margin boxes do not appear.
- `position: running()` leaves the element where it is in the page, once, instead of repeating it on each page.

## Page images (coming soon)

> **Page images: coming soon.**
> Optional images of the rendered pages, so an agent can look at the result, are not available yet. Today a render returns the PDF and the render report.

## Related

- [Files and fonts](https://stolid.dev/docs/files-and-fonts/): send your stylesheets, images and fonts.
- [API reference](https://stolid.dev/docs/api/): the complete list of options and their defaults.

Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.

[Preview Terms](https://stolid.dev/legal/terms/) · [Acceptable use](https://stolid.dev/legal/terms/#acceptable-use) · [Privacy Policy](https://stolid.dev/legal/privacy/) · [Data handling](https://stolid.dev/data/) · Report abuse or copyright infringement: hello@stolid.dev

© 2026 Stolid · Operated by an individual in Washington, USA

Source: https://stolid.dev/docs/page-options/
