Skip to content

How it renders / options.preset

Use a PDF rendering preset

Three named bundles of options for the three shapes most documents fall into, with anything you pass explicitly overriding them.

What it is for

Most render calls set the same four or five options, and most of them fall into a small number of patterns. A preset names the pattern so the intent is visible in the call: invoice means a business document with tight margins, report means a document with room to breathe, screenshot means capture the page as it appears on screen.

The request

Sent to options.preset. Everything else on this page is what happens around it.

json

{
  "html": "<!doctype html>...",
  "options": {
    "preset": "invoice",
    "margin": "14mm"
  }
}

// The preset sets A4, 10mm margins, backgrounds on and print media.
// The explicit margin above wins, so this is A4 at 14mm.

The actual limits

Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.

  • Three values: invoice, report and screenshot. Anything else returns 400 with the list.
  • invoice is A4 with 10mm margins, backgrounds on, print media. report is A4 with 20mm margins, otherwise the same. screenshot is A4 with zero margins, backgrounds on, screen media.
  • Preset values form the base and explicit options win over them, so a preset is a starting point rather than a lock.

What failure looks like

An unknown preset name returns 400 before rendering, so nothing is metered. The subtler problem is a preset that nearly fits: reaching for report and then overriding three of its four values is more code than setting the four values, and it hides what the call actually does.

When this is the wrong tool

When the document has its own opinion about the page. If the markup declares an @page rule, a preset is setting a format that will then be argued with. Use prefer_css_page_size instead and let the document decide.

Frequently asked

Is presets available on the free plan?

Yes. There is no plan gate on this one: it behaves the same on the free plan as on every paid plan, and the only limit that applies is the monthly document allowance.

Where do these numbers come from?

The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.

Related capabilities

Options that come up in the same request, and one from each of the other groups.

Print background colours and images in a PDFControls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.Render a PDF using screen CSS instead of print CSSChooses which CSS media type the document is rendered under: print by default, or screen when you want the page to look like the page.Add a header, footer and page numbers to a PDFSmall HTML fragments repeated on every page, with substitution tokens for the page number, the total, the date, the title and the URL.Render an HTML string to PDF over an APISend a complete HTML document in the request body and get the PDF bytes back in the response.Set the PDF page size in an API requestSix named paper sizes, passed in the request options, with A4 as the default when nothing is given.Render many PDFs in one API callUp to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.Password protect a generated PDFEncrypts the output so a reader is asked for a password before the document opens.Check API usage and remaining document quotaHow many documents have been used this billing period, what the limit is, and what the plans are, all readable from the API rather than from a dashboard.Everything the API doesThe full list, grouped by which part of the request it belongs to.API referenceThe complete parameter documentation, including the parts with nothing interesting to say about them.

100 free documents a month, and a playground that runs a real render without a key.

Try it live, no signup Get an API key