Options Reference
Customize PDF output using the options object in your request.
Page Format
Preset Sizes
{
"options": {
"format": "A4"
}
}
| Format | Dimensions |
|---|---|
A4 | 8.27" x 11.69" (210mm x 297mm) |
Letter | 8.5" x 11" (216mm x 279mm) |
Legal | 8.5" x 14" (216mm x 356mm) |
Tabloid | 11" x 17" (279mm x 432mm) |
Custom Size
Specify exact dimensions:
{
"options": {
"format": {
"width": "8.5in",
"height": "11in"
}
}
}
Supported units: px, in, cm, mm
Margins
Uniform Margin
Apply the same margin to all sides:
{
"options": {
"margin": "1in"
}
}
Individual Margins
Set each side separately:
{
"options": {
"margin": {
"top": "1in",
"bottom": "1in",
"left": "0.5in",
"right": "0.5in"
}
}
}
Supported units: px, in, cm, mm, pt, pc, em, rem, %
Tip: Use at least 0.5" margins for documents that will be printed to avoid content being cut off.
Orientation
Portrait (default)
{
"options": {
"landscape": false
}
}
Landscape
{
"options": {
"landscape": true
}
}
Background Printing
By default, CSS background colors and images are not printed.
{
"options": {
"printBackground": true
}
}
Enable
printBackground for documents with colored headers, styled tables, or background images.Page Ranges
Print specific pages:
{
"options": {
"pageRanges": "1-5"
}
}
Examples:
"1"- First page only"1-5"- Pages 1 through 5"1,3,5"- Pages 1, 3, and 5"1-3,5,7-9"- Pages 1-3, 5, and 7-9
Scale
Adjust the page zoom level:
{
"options": {
"scale": 0.8
}
}
| Value | Effect |
|---|---|
0.1 | 10% zoom (minimum) |
1.0 | 100% zoom (default) |
2.0 | 200% zoom (maximum) |
Scale values below 1.0 can help fit wide content. Values above 1.0 make text larger.
Headers and Footers
Add custom headers and footers with HTML templates.
Header Template
{
"options": {
"headerTemplate": "<div style='font-size: 10px; width: 100%; text-align: center;'>Company Name</div>"
}
}
Footer Template
{
"options": {
"footerTemplate": "<div style='font-size: 10px; width: 100%; text-align: center;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"
}
}
Template Variables
Use these CSS classes for dynamic content:
| Class | Value |
|---|---|
.date | Current date |
.title | Document title |
.url | Document URL |
.pageNumber | Current page number |
.totalPages | Total page count |
Example: Invoice Footer
<div style="font-size: 9px; width: 100%; display: flex; justify-content: space-between; padding: 0 20px;">
<span>Invoice #12345</span>
<span>Page <span class="pageNumber"></span> of <span class="totalPages"></span></span>
</div>
Note: Header and footer templates are sanitized. Script tags and event handlers are removed for security.
Complete Example
{
"html": "<!DOCTYPE html><html><body>...</body></html>",
"options": {
"format": "Letter",
"margin": {
"top": "1in",
"bottom": "1in",
"left": "0.75in",
"right": "0.75in"
},
"landscape": false,
"printBackground": true,
"scale": 1.0,
"footerTemplate": "<div style='font-size: 9px; text-align: center; width: 100%;'>Page <span class='pageNumber'></span></div>"
}
}