Chromium options

Page properties (converters)

Pass properties to convert() to control the generated PDF:

Property	Type	Description
`singlePage`	`boolean`	Render entire content on one page (default: `false`)
`size`	`{ width, height }`	Paper size. Numbers = inches; strings support `pt`, `px`, `in`, `mm`, `cm`, `pc` (e.g. `"210mm"`, `"297mm"` for A4)
`margins`	`{ top, bottom, left, right }`	Margins; same unit rules as `size`
`preferCssPageSize`	`boolean`	Use CSS page size when set (default: `false`)
`printBackground`	`boolean`	Include background graphics (default: `false`)
`omitBackground`	`boolean`	Transparent background (default: `false`)
`landscape`	`boolean`	Landscape orientation (default: `false`)
`scale`	`number`	Page scale (default: `1.0`)
`nativePageRanges`	`{ from, to }` \| `string`	Page range to print — a single range, or the free-form syntax `"1-5, 8, 11-13"`

Every field of size and margins defaults independently, so you can set just one dimension or margin and let Gotenberg fill in the rest. Example with units:

await urlConverter.convert({
  url: "https://example.com/",
  properties: {
    size: { width: "210mm", height: "297mm" },
    margins: { top: "1cm", bottom: "1cm", left: "2cm", right: "2cm" },
  },
});

Standard paper sizes

Common sizes (width × height) you can use in properties.size:

Format	Dimensions (in)	Example `size`
A6	4.13 × 5.83	`{ width: 4.13, height: 5.83 }`
A5	5.83 × 8.27	`{ width: 5.83, height: 8.27 }`
A4	8.27 × 11.7	`{ width: "210mm", height: "297mm" }`
Letter	8.5 × 11 (default)	`{ width: 8.5, height: 11 }`
Legal	8.5 × 14	`{ width: 8.5, height: 14 }`
A3	11.7 × 16.54	`{ width: "297mm", height: "420mm" }`

Single page

When singlePage is true, Chromium fits the entire content on one long page and overrides paper height and native page ranges.

Print media

Chromium uses print media by default. The PDF can look different from the browser (e.g. backgrounds omitted). Use printBackground: true to include background graphics, or set emulatedMediaType: "screen" (in conversion options) to use screen media. You can target print in CSS with @media print; use preferCssPageSize: true so Chromium respects @page size and margins.

Background logic

The resulting background depends on printBackground, omitBackground, and whether your document has a background:

`printBackground`	`omitBackground`	Document has background?	Result
`false`	any	any	No background
`true`	any	Yes	Uses HTML/CSS background
`true`	`true`	No	Transparent
`true`	`false`	No	White (default)

Rendering and wait

Chromium captures the current DOM. If the page uses JavaScript to render content (e.g. SPAs, charts), use wait options so conversion runs when content is ready. Prefer waitForExpression or waitForSelector over waitDelay: they are more reliable. Use waitDelay only as a fallback when you cannot change the page; it is less reliable if load time varies.

Conversion options (converters)

In addition to properties, convert() accepts:

Wait: waitDelay (e.g. "5s"), waitForSelector, waitForExpression — see Rendering and wait
Header/footer: header, footer — path, Buffer, or ReadStream (see below)
User agent: userAgent — override the User-Agent header sent by Chromium
HTTP: extraHttpHeaders, cookies, failOnHttpStatusCodes, failOnResourceHttpStatusCodes, ignoreResourceHttpStatusDomains, failOnResourceLoadingFailed, skipNetworkIdleEvent, skipNetworkAlmostIdleEvent (see below)
Behavior: failOnConsoleExceptions, failOnResourceLoadingFailed, skipNetworkIdleEvent, skipNetworkAlmostIdleEvent
Async callbacks: webhook (webhookUrl, webhookErrorUrl, optional methods/headers/events URL — at least one of webhookUrl/webhookErrorUrl is required when webhook is set; webhookErrorUrl is deprecated in favor of webhookEventsUrl)
Output: outputFilename, trace — custom output filename and/or request trace id (see Request tracing)
PDF accessibility: pdfUA (PDF/UA accessibility), generateTaggedPdf (PDF/UA structure tags, independent of pdfUA), generateDocumentOutline (bookmarks from heading tags)
pdfFormat — deprecated: Chromium no longer supports it since Gotenberg 8.0.0; use pdfa on PDFEngines.convert instead
Metadata: metadata
Encryption: userPassword, ownerPassword — see Encryption
Permissions: allowPrinting, allowCopying, allowModifying, allowAnnotating, allowFillingForms, allowAssembling — see PDF permissions
Attachments: embeds, embedsMetadata — see Embedding files
Factur-X / ZUGFeRD: facturx — turn the resulting PDF into an e-invoice, see Factur-X
PDF-engine overlays: watermark, stamp (post-processing)
PDF-engine rotation: rotate — { angle: 90 | 180 | 270; pages?: string } (optional second pass after render; see Rotate PDFs)
Split: split — { mode: "pages" | "intervals", span, unify? } (see Split PDFs; flatten below is a separate top-level option, not part of split)
Flatten: flatten — flatten the resulting PDF’s form fields and annotations (default false); see Flatten PDFs

See Reference — types for full type definitions.

Watermark and stamp (PDF engines)

You can set watermark and stamp on converter convert() options. These are applied after Chromium renders the PDF:

watermark overlays behind page content.
stamp overlays on top of page content.

import { UrlConverter } from "chromiumly";

const converter = new UrlConverter();
const buffer = await converter.convert({
  url: "https://example.com/",
  watermark: {
    source: "text",
    expression: "CONFIDENTIAL",
    options: { opacity: 0.25, rotation: 45 },
  },
  stamp: {
    source: "text",
    expression: "APPROVED",
    options: { opacity: 0.5 },
  },
});

For image/PDF overlays, set source to "image" or "pdf", set expression to the uploaded filename, and pass the file via file. Option keys in options are engine-specific; see Gotenberg watermark docs and stamp docs.

Header and footer

Headers and footers are rendered in an isolated context: your main page’s CSS does not apply, JavaScript does not run, and external requests (images, fonts) are not allowed. Provide complete HTML documents. Chromium injects dynamic values into elements with these class names: pageNumber, totalPages, date, title, url. Use base64-encoded images inline (e.g. <img src="data:image/png;base64,...">). Add -webkit-print-color-adjust: exact; in your header/footer CSS if you need background or text colors to print.

HTTP and networking

extraHttpHeaders — Object of header name → value; sent with every request (main page and resources). You can scope a header to certain URLs by appending ;scope=<regex> to the value (the token is stripped before sending).
cookies — Array of { name, value, domain } (and optional path, secure, httpOnly, sameSite) for authentication or session state.
downloadFrom — DownloadFromEntry or DownloadFromEntry[] for remote file fetching; each entry supports url, optional extraHttpHeaders, and routing with field ("embedded", "watermark", "stamp").
webhook — Request-level webhook headers for async processing (webhookUrl, webhookErrorUrl, optional method overrides, extra callback headers, and events URL).
failOnHttpStatusCodes — Array of status codes (or ranges via X99 notation, e.g. 499 = 400–499). If the main page returns a matching code, Gotenberg returns 409 Conflict. Default is [499, 599].
failOnResourceHttpStatusCodes — Same for subresources (images, CSS, scripts). Use ignoreResourceHttpStatusDomains to exclude hostnames from this check (e.g. analytics).
failOnResourceLoadingFailed — If true, conversion fails with 400 when any resource fails to load (e.g. 404 image); by default the PDF is still generated with missing assets.
skipNetworkIdleEvent — If true, Chromium does not wait for the network to be idle before converting (default true).
skipNetworkAlmostIdleEvent — If true, Chromium does not wait for the network to be almost idle (<=2 open connections for 500ms) before converting (default true). Set to false to wait for almost-idle pages with long-lived requests.

Screenshot options (capture)

Pass properties to capture() for image output:

Property	Type	Description
`format`	`"png"` \| `"jpeg"` \| `"webp"`	Image format
`quality`	`number` (0–100)	JPEG compression quality
`omitBackground`	`boolean`	Transparent background
`width`	`number`	Viewport width in pixels (default: 800)
`height`	`number`	Viewport height in pixels (default: 600)
`clip`	`boolean`	Clip to viewport (default: `false`)
`deviceScaleFactor`	`number`	Device scale factor, useful for HiDPI screenshots (default: `1`)

Other capture() options mirror the conversion options where applicable (e.g. userAgent, waitDelay, waitForSelector, extraHttpHeaders, cookies, downloadFrom, webhook, outputFilename, trace, optimizeForSpeed). Screenshots produce an image rather than a PDF, so PDF-only options — header/footer, generateDocumentOutline, userPassword/ownerPassword, embeds/embedsMetadata, facturx, permissions, split, flatten — don’t apply here. See Reference — screenshots.

Getting started

Chromium

LibreOffice

PDF engines

Advanced

Page properties (converters)

Standard paper sizes

Single page

Print media

Background logic

Rendering and wait

Conversion options (converters)

Watermark and stamp (PDF engines)

Header and footer

HTTP and networking

Screenshot options (capture)

​Page properties (converters)

​Standard paper sizes

​Single page

​Print media

​Background logic

​Rendering and wait

​Conversion options (converters)

​Watermark and stamp (PDF engines)

​Header and footer

​HTTP and networking

​Screenshot options (capture)

Page properties (converters)

Standard paper sizes

Single page

Print media

Background logic

Rendering and wait

Conversion options (converters)

Watermark and stamp (PDF engines)

Header and footer

HTTP and networking

Screenshot options (capture)