---
title: "format parameter"
description: "Output a PDF document instead of a PNG image with the format parameter, on the HTML/CSS, Screenshot and Template APIs."
url: "https://html2img.com/docs/parameters/format/"
---

# Format Parameter

The `format` parameter switches the output between a PNG image (the default) and a PDF document. It works on the HTML/CSS API, the Screenshot API and the [template endpoints](https://html2img.com/docs/templates/).

Looking for the overview rather than the reference? See the [HTML to PDF API](https://html2img.com/html-to-pdf/) page.

## Specifications

| Property | Value |
|----------|-------|
| Type | string |
| Required | No |
| Default | `png` |
| Allowed values | `png`, `pdf` |
| API | HTML/CSS, Screenshot and Template APIs |

## Description

When `format` is set to `pdf`:

- The result is a real, vector PDF - text stays selectable and searchable, and fonts (including webfonts) are embedded in the document
- Content is laid out on A4 portrait pages and paginates automatically, so long content flows across as many pages as it needs
- Background colours, gradients and images are included
- The page renders with your normal screen CSS, so the PDF looks like the image output would - `@media print` rules are not applied
- The response `url` points to a `.pdf` file served with the `application/pdf` content type

Only genuine raster content (`<img>` elements, canvases) is embedded as pixels; everything else in the PDF is vector.

> **Important**
>
> Sizing parameters mostly do not apply to PDF output. Pages are A4 portrait, so `dpi`, `fullpage` and `selector` have no effect when `format` is `pdf`, and there is no quality reason to want a higher DPI: vector output is sharp at any zoom level. `width` and `height` set the rendering viewport but do not change the page size - on their own they have no visible effect. The exception is [`scale_to_fit`](https://html2img.com/docs/parameters/scale-to-fit/): with it enabled, content is laid out at your requested `width` and then scaled down to fit the page, which is how you keep a desktop layout in the PDF.

## Examples

### HTML to PDF

```json
{
    "html": "<h1>Invoice #1042</h1><p>Due within 30 days.</p>",
    "css": "h1 { color: #4f46e5; }",
    "format": "pdf"
}
```

### Web page to PDF

```json
{
    "url": "https://example.com",
    "format": "pdf"
}
```

### Async PDF with a webhook

```json
{
    "html": "<h1>Monthly report</h1>",
    "format": "pdf",
    "webhook_url": "https://your-domain.com/webhook"
}
```

### Response

```json
{
    "success": true,
    "id": "9d5f9b52-6b32-4a1c-a9c5-1f0b2a9e4c11",
    "expires_at": null,
    "credits_remaining": 499,
    "url": "https://i.html2img.com/image-1784019129398-416501.pdf"
}
```

A PDF conversion costs the same single credit as an image conversion.

## Common values

- **`png`** (default) - a PNG image sized by [width and height](https://html2img.com/docs/parameters/dimensions/), with optional [dpi](https://html2img.com/docs/parameters/dpi/) scaling.
- **`pdf`** - an A4 portrait PDF document with selectable text and automatic pagination.

## When to use

Use `format: "pdf"` when the output is a document rather than a picture: invoices, receipts, reports, certificates, tickets, or printable versions of generated content. Anyone opening the file can select and copy the text, search inside it, and print it at full quality. The [HTML to PDF API](https://html2img.com/html-to-pdf/) page covers rendering your own markup as a document; the [URL to PDF API](https://html2img.com/url-to-pdf/) page covers converting live pages.

Stay with the default PNG for social cards, OG images, thumbnails and anywhere the output is displayed inside another page at fixed pixel dimensions.

## Common mistakes

- **Expecting `width` and `height` to size the PDF.** PDF pages are A4 portrait and content reflows to the page width. Design your markup to flow like a document rather than to fixed pixel dimensions, or pass [`scale_to_fit`](https://html2img.com/docs/parameters/scale-to-fit/) to scale a fixed-width design onto the page.
- **Raising `dpi` to sharpen the output.** PDF output is vector, so it is already sharp at any zoom level. The `dpi` value is ignored in PDF mode.
- **Relying on `@media print` styles.** The PDF is rendered with screen CSS so it matches the image output. Put everything the PDF needs in your normal styles.
- **Using `selector` or `fullpage`.** Neither applies to PDFs - the whole document is captured and paginated automatically.

See also: [getting started guide](https://html2img.com/docs/getting-started/), [scale_to_fit](https://html2img.com/docs/parameters/scale-to-fit/), [webhook_url](https://html2img.com/docs/parameters/webhook-url/), [css](https://html2img.com/docs/parameters/css/).

> **Note**
>
> [Templates](https://html2img.com/docs/templates/) accept `format` too. Add `"format": "pdf"` to the JSON body alongside the template's inputs. Template PDFs scale to fit the page automatically, so every design arrives complete with no trailing blank page. Document-shaped templates like invoices, receipts and certificates are the natural fit. One behavioural difference: template endpoints return `422` for validation failures, where the HTML and Screenshot APIs return `400`.