---
title: Render options
description: Every field the render endpoints accept — source, output format, viewport, page timing, image settings, and PDF settings.
sidebar:
  label: Render options
  order: 3
---

Both `/v1/render` and `/v1/render/template` take the same options, apart from the source fields. Everything below is optional unless marked required, and unknown fields are rejected.

## Source

| Prop | Type | Default | Description |
| - | - | - | - |
| `html?` | `string` | - | Complete HTML document to render. /v1/render only. Required unless url is given; wins if both are sent. Max 5 MB. |
| `url?` | `string` | - | Publicly reachable URL to render. /v1/render only. Required unless html is given. |
| `templateId` | `string` | - | ID of a saved template. /v1/render/template only, where it replaces html and url. |
| `variables?` | `Record<string, string \| number \| boolean \| null>` | `{}` | Values substituted into the template's {{ placeholders }}. /v1/render/template only. |

## Output

| Prop | Type | Default | Description |
| - | - | - | - |
| `format?` | `"png" \| "webp" \| "jpg" \| "pdf"` | `"png"` | Output format, which also picks the response content-type. |
| `quality?` | `number` | `100` | Compression quality from 1 to 100. Applies to jpg and webp; ignored for png and pdf. |
| `fileName?` | `string` | - | Attachment filename without the extension, used in content-disposition. Slugified, capped at 80 characters. Max 160 characters in. |

PNG is lossless and supports transparency — good for previews and social images with a transparent background. WebP at `quality: 80` is usually a third the size of the same PNG. JPG is the safest choice for old email clients. PDF is the only paged format, and the only one that uses the PDF settings below.

## Viewport

| Prop | Type | Default | Description |
| - | - | - | - |
| `width?` | `number` | `1024` | Viewport width in pixels. For PDFs without pdfFormat, this is also the page width. |
| `height?` | `number` | `768` | Viewport height in pixels. For PDFs without pdfFormat, this is also the page height. |
| `deviceScaleFactor?` | `number` | `2` | Pixel density from 1 to 4. The default renders at 2x, so images stay sharp on high-DPI screens. |

A `1024 × 768` viewport at `deviceScaleFactor: 2` produces a 2048 × 1536 image. Drop it to `1` when file size matters more than sharpness.

## Page timing

| Prop | Type | Default | Description |
| - | - | - | - |
| `waitUntil?` | `"load" \| "domcontentloaded" \| "networkidle"` | `"domcontentloaded"` | How long to wait before capturing. domcontentloaded is fastest; networkidle waits for the network to settle, which matters for pages that fetch their own data. |
| `waitForTimeout?` | `number` | `0` | Extra delay in milliseconds after waitUntil, up to 10,000. Use it for animations, web fonts, or charts that draw after load. |
| `media?` | `"screen" \| "print"` | `"screen"` | Which CSS media type the page is rendered with. Use print to apply your @media print rules. |
| `reducedMotion?` | `"reduce" \| "no-preference"` | `"reduce"` | Motion preference reported to the page. Accepted for compatibility; the current renderer does not apply it. |

:::warning
Everything the page needs must be reachable at render time. Relative URLs in `html` have no origin to resolve against, so reference styles, fonts, and images by absolute URL — or inline them as `<style>` blocks and `data:` URIs.
:::

## Image settings

Ignored when `format` is `pdf`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `fullPage?` | `boolean` | `false` | Capture the entire scrollable page instead of just the viewport. Width still comes from width. |
| `transparentBackground?` | `boolean` | `false` | Render without the default white backdrop, so uncovered areas stay transparent. PNG and WebP only. |
| `omitBackground?` | `boolean` | `false` | Alias for transparentBackground. Either one turns it on. |

## PDF settings

Ignored for image formats.

| Prop | Type | Default | Description |
| - | - | - | - |
| `pdfFormat?` | `string` | - | Paper size, such as "A4" or "Letter". When set, it replaces width and height as the page size. |
| `printBackground?` | `boolean` | `true` | Include CSS backgrounds and background images. On by default, unlike a browser's print dialog. |
| `margin?` | `{ top?: string; right?: string; bottom?: string; left?: string }` | - | Page margins as CSS lengths, e.g. { "top": "20mm", "bottom": "20mm" }. |
| `scale?` | `number` | `1` | Scale of the rendered content, from 0.1 to 2. |
| `preferCSSPageSize?` | `boolean` | `false` | Let the page's CSS @page size win over pdfFormat, width, and height. |

## Worked examples

<CodeGroup>

```json title="A4 invoice"
{
  "html": "<!doctype html><html>…</html>",
  "format": "pdf",
  "pdfFormat": "A4",
  "printBackground": true,
  "margin": { "top": "18mm", "bottom": "18mm", "left": "14mm", "right": "14mm" },
  "media": "print",
  "fileName": "invoice-1842"
}
```

```json title="Social card"
{
  "html": "<!doctype html><html>…</html>",
  "format": "png",
  "width": 1200,
  "height": 630,
  "deviceScaleFactor": 1,
  "fileName": "og-launch-week"
}
```

```json title="Full-page screenshot"
{
  "url": "https://example.com/pricing",
  "format": "webp",
  "quality": 80,
  "width": 1440,
  "height": 900,
  "fullPage": true,
  "waitUntil": "networkidle",
  "waitForTimeout": 500
}
```

```json title="Transparent badge"
{
  "html": "<div class=\"badge\">Pro</div>",
  "format": "png",
  "width": 400,
  "height": 120,
  "transparentBackground": true
}
```

</CodeGroup>