> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chromiumly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Chromium options

> Page properties, conversion options, and screenshot options for Chromium routes.

## 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 }`                 | Page range to print                                                                                                 |

Example with units:

```typescript theme={null}
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](#rendering-and-wait)
* **Header/footer**: `header`, `footer` — path, `Buffer`, or `ReadStream` (see below)
* **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)
* **PDF**: `pdfUA` (accessibility), `metadata`, `userPassword`, `ownerPassword`, `embeds`
* **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](/pdf-engines/rotate))
* **Split**: `split` — `{ mode: "pages" | "intervals", span, unify?, flatten? }`

See [Reference — types](/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.

```typescript theme={null}
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](https://gotenberg.dev/docs/manipulate-pdfs/watermark-pdfs) and [stamp docs](https://gotenberg.dev/docs/manipulate-pdfs/stamp-pdfs).

### 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`)      |

Other `capture()` options mirror the conversion options where applicable (e.g. `waitDelay`, `waitForSelector`, `extraHttpHeaders`, `optimizeForSpeed`). See [Reference — screenshots](/reference/screenshots).