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

# HTML to PDF

> Convert any HTML file into a high-quality PDF with full control over page layout, margins, headers, and footers

The HTML to PDF tool converts any HTML file into a pixel-perfect PDF. Use your own HTML and CSS — including frameworks like Tailwind CSS or Bootstrap — and get a print-ready document with customizable page settings.

## How it works

1. **Upload** your HTML file via the [file upload endpoint](/api-reference/developer-api/upload-a-file)
2. **Create a job** via `POST /tools/convert/html-to-pdf` with the file ID and optional page settings
3. **Poll the job** via `GET /tools/jobs/{jobId}` until status is `COMPLETED`
4. **Download** the result via `GET /tools/files/{fileId}/download`

## Basic request

At minimum, just provide the file ID of your uploaded HTML file:

```json theme={null}
{
  "fileId": "your-html-file-id"
}
```

This will produce an A4 portrait PDF with default margins (20mm top/bottom, 15mm left/right).

## Full request with all options

```json theme={null}
{
  "fileId": "your-html-file-id",
  "format": "A4",
  "landscape": "landscape",
  "emulatedMediaType": "screen",
  "scale": 1.0,
  "preferCssPageSize": false,
  "margin": {
    "top": "25mm",
    "right": "20mm",
    "bottom": "25mm",
    "left": "20mm"
  },
  "headerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">My Report</div>",
  "footerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
  "webhook": {
    "url": "https://example.com/webhook",
    "secret": "my-secret"
  }
}
```

## Properties

| Property            | Type    | Required | Default      | Description                                                                                                           |
| ------------------- | ------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `fileId`            | string  | **Yes**  | —            | File ID of the uploaded HTML file.                                                                                    |
| `format`            | string  | No       | `"A4"`       | Page format: `"A4"`, `"A3"`, `"A5"`, `"Letter"`, `"Legal"`, `"Tabloid"`. Ignored when `preferCssPageSize` is enabled. |
| `landscape`         | string  | No       | `"portrait"` | Page orientation: `"portrait"` or `"landscape"`.                                                                      |
| `emulatedMediaType` | string  | No       | `"print"`    | CSS media type: `"print"` or `"screen"`. See [CSS media emulation](#css-media-emulation).                             |
| `scale`             | number  | No       | `1.0`        | Scale factor between `0.1` and `2.0`. Values below 1.0 zoom out, above 1.0 zoom in.                                   |
| `preferCssPageSize` | boolean | No       | `false`      | When enabled, any `@page` CSS rules in your HTML take priority over the `format` option.                              |
| `margin`            | object  | No       | See below    | Page margins. See [Margins](#margins).                                                                                |
| `headerTemplate`    | string  | No       | —            | HTML template for page headers. See [Headers & Footers](#headers--footers).                                           |
| `footerTemplate`    | string  | No       | —            | HTML template for page footers. See [Headers & Footers](#headers--footers).                                           |
| `webhook`           | object  | No       | —            | Optional [webhook configuration](/api-reference/webhooks) for job completion notification.                            |

***

## Margins

Control the page margins using the `margin` object. Each value accepts a number with a unit (`mm`, `cm`, `in`, or `px`).

| Property | Default  | Example values                |
| -------- | -------- | ----------------------------- |
| `top`    | `"20mm"` | `"1in"`, `"2.54cm"`, `"72px"` |
| `right`  | `"15mm"` | `"1in"`, `"2cm"`              |
| `bottom` | `"20mm"` | `"1in"`, `"2.54cm"`           |
| `left`   | `"15mm"` | `"1in"`, `"2cm"`              |

```json theme={null}
{
  "margin": {
    "top": "25mm",
    "right": "20mm",
    "bottom": "30mm",
    "left": "20mm"
  }
}
```

<Warning>
  When using `headerTemplate` or `footerTemplate`, make sure the corresponding
  margin (top or bottom) is large enough to display the header/footer content.
</Warning>

***

## Headers & Footers

Add repeating headers and footers to every page of your PDF. Templates are standard HTML strings and support special placeholders for page numbers:

| Placeholder                        | Description           |
| ---------------------------------- | --------------------- |
| `<span class="pageNumber"></span>` | Current page number   |
| `<span class="totalPages"></span>` | Total number of pages |

### Example: Page numbers in footer

```json theme={null}
{
  "footerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
}
```

### Example: Custom header and footer

```json theme={null}
{
  "headerTemplate": "<div style=\"font-size:9px;width:100%;padding:0 20mm;\"><span style=\"float:left;\">Confidential</span><span style=\"float:right;\">ACME Corp</span></div>",
  "footerTemplate": "<div style=\"font-size:9px;text-align:center;width:100%;\"><span class=\"pageNumber\"></span> / <span class=\"totalPages\"></span></div>"
}
```

<Info>
  Header and footer templates must include their own inline styling (font-size,
  colors, etc.) — they do not inherit styles from your HTML document.
</Info>

***

## CSS media emulation

By default, the conversion uses `print` media emulation. This means CSS rules inside `@media print` will apply, and some CSS frameworks may behave differently than expected.

Set `emulatedMediaType` to `"screen"` if you want the PDF to look exactly like it does in a browser — particularly useful when using CSS frameworks like **Tailwind CSS** or **Bootstrap**.

```json theme={null}
{
  "emulatedMediaType": "screen"
}
```

| Value      | Behavior                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| `"print"`  | Standard print rendering. `@media print` rules apply. Best for documents designed for print.          |
| `"screen"` | Screen rendering. All responsive and visual styles apply as in a browser. Best for web-designed HTML. |

***

## Page breaks

You can control page breaks directly in your HTML using standard CSS print properties:

```css theme={null}
/* Force a page break before an element */
h2 {
  break-before: page;
}

/* Prevent a page break inside an element */
.card {
  break-inside: avoid;
}

/* Force a page break after an element */
.section {
  break-after: page;
}
```

## CSS `@page` rule

If you want full control over the page size and margins from within your HTML, use the CSS `@page` rule and enable `preferCssPageSize`:

```html theme={null}
<style>
  @page {
    size: A3 landscape;
    margin: 10mm;
  }
</style>
```

```json theme={null}
{
  "preferCssPageSize": true
}
```

When `preferCssPageSize` is enabled, the `format` and `landscape` API options are ignored in favor of your CSS rules.

***

## Tips

* **External resources**: The HTML file can reference external CSS, fonts, and images via URLs. These will be loaded during conversion.
* **Background colors**: Background colors and images are always printed. No need for `-webkit-print-color-adjust`.
* **Maximum file size**: The HTML file must be under 50 MB.
* **Timeout**: The conversion allows up to 60 seconds for the page to load. If your HTML loads external resources, make sure they are accessible and responsive.