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
- Upload your HTML file via the file upload endpoint
- Create a job via
POST /tools/convert/html-to-pdf with the file ID and optional page settings
- Poll the job via
GET /tools/jobs/{jobId} until status is COMPLETED
- Download the result via
GET /tools/files/{fileId}/download
Basic request
At minimum, just provide the file ID of your uploaded HTML file:
{
"fileId": "your-html-file-id"
}
Full request with all options
{
"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. |
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. |
headerTemplate | string | No | — | HTML template for page headers. See Headers & Footers. |
footerTemplate | string | No | — | HTML template for page footers. See Headers & Footers. |
webhook | object | No | — | Optional webhook configuration 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" |
{
"margin": {
"top": "25mm",
"right": "20mm",
"bottom": "30mm",
"left": "20mm"
}
}
When using headerTemplate or footerTemplate, make sure the corresponding
margin (top or bottom) is large enough to display the header/footer content.
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 |
{
"footerTemplate": "<div style=\"font-size:10px;text-align:center;width:100%;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
}
{
"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>"
}
Header and footer templates must include their own inline styling (font-size,
colors, etc.) — they do not inherit styles from your HTML document.
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.
{
"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:
/* 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:
<style>
@page {
size: A3 landscape;
margin: 10mm;
}
</style>
{
"preferCssPageSize": true
}
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.
