Export a searchable PDF.

Install

npm install @zumer/snapdom @zumer/snapdom-pdf

Requires SnapDOM 3.4.0 or newer within 3.x. Source and MIT license. Without a bundler, map both packages in an import map and serve the whole @zumer/snapdom-pdf folder, because its index.js imports files from src/.

<script type="importmap">
{
  "imports": {
    "@zumer/snapdom": "/vendor/snapdom.mjs",
    "@zumer/snapdom-pdf": "/vendor/snapdom-pdf/index.js"
  }
}
</script>

Quick start

import { snapdom } from '@zumer/snapdom'
import { pdf } from '@zumer/snapdom-pdf'

snapdom.plugins(pdf())

const shot = await snapdom(document.querySelector('#report'))
const blob = await shot.toPdf({ page: 'a4', download: 'report.pdf' })

Register the plugin before you capture. A capture made without it has no toPdf(). To use it on one capture only, pass it there: snapdom(el, { plugins: [pdf()] }).

toPdf() returns a PDF Blob. download also saves the file. shot.to('pdf', options) does the same as toPdf(options).

The page image plus a PDF text layer

The page image is SnapDOM's capture. The plugin places a second, invisible text layer over it using positions derived from SnapDOM's final serialized clone. No headless browser or separate layout engine rebuilds the page.

By default, the image preserves the capture’s appearance while the text layer adds selection, search and copy. Paper sizes add pagination; optional fields keep supported controls fillable. Vector text, headers and footers, encryption and structured reports are configured below.

Options on pdf()

Set these options on pdf(): they decide which text, controls and pagination hints the plugin reads from the captured artifact. A later toPdf() call cannot change them.

Every other option works in either place. On pdf() it becomes the default for every export; in toPdf() it applies to that export and wins.

Pages

Page breaks avoid table rows, list items, figures, quotes, images and anything with break-inside: avoid. CSS page breaks are respected. A block taller than a page still has to split.

Image and file size

What you see in the PDF is an image of the capture, with invisible text on top so it can be selected and searched.

Sharpness and size come from the capture: snapdom(el, { scale, dpr }). Both multiply the image's pixels and leave the page layout alone. The image keeps that many pixels per CSS pixel at the size it is printed. A capture enlarged to fill the paper is drawn at the enlarged size, so it stays as sharp as on screen. dpr defaults to the screen of the machine that exports, so set it, for example to 2, to get the same file everywhere.

Text and links

Links work for http:, https:, mailto: and tel:. Any other link is left out with a warning.

Fonts and sharp text

The PDF can only embed fonts the capture carries, so capture with snapdom(el, { embedFonts: true }). System fonts have no file to embed. Copying text works the same with or without embedded fonts.

vectorText needs embedded fonts. Right-to-left and complex scripts stay as image. With image: false it gives a very small text-only PDF, without borders, backgrounds or pictures.

Bookmarks and accessibility

The PDF is marked accessible (PDF/UA-1) only when it qualifies: every font embedded, a language, a meta.title, alt text on every image and fields: false. There is no option to force it. When something is missing, the report says what.

Fillable forms

Text inputs, textareas, checkboxes, radio buttons and selects become fields with their name, value and label. Read-only, disabled, required and maxlength carry over. Password fields are written empty. Buttons, sliders, colour pickers and file inputs stay as image. The PDF never contains scripts or submit actions.

Header, footer and page numbers

await shot.toPdf({
  page: 'a4',
  header: { left: 'North Studio', right: 'Delivery report' },
  pageNumbers: { format: (page, pages) => `Page ${page} of ${pages}` },
})

These need a paper size and do nothing on page: 'fit'. Text is real PDF text. An element is captured as an image, so its text cannot be selected.

Cover, contents, back page and watermark

Cover, contents and back page need a paper size. The watermark also works on page: 'fit'.

Metadata

Dates are written only when you pass them. Pass new Date() when you want today. The same captured state with the same options produces identical unencrypted bytes. Encryption uses fresh randomness for each export.

Password

await shot.toPdf({
  page: 'a4',
  encrypt: { userPassword: 'ada-1815', ownerPassword: 'owner-key' },
})

encrypt protects the file with AES-256. userPassword is required. ownerPassword defaults to it. permissions takes print, modify, copy, annotate, fillForms, assemble and printHighRes, all true by default.

Only the password protects the file. Permissions are requests that a viewer may ignore. Encryption needs https or localhost, and an encrypted export is different every time.

Output

Progress, cancel and report

await shot.toPdf({
  page: 'a4',
  onProgress: ({ done, total }) => bar.update(done, total),
  signal: controller.signal,
  onReport: (report) => console.log(report.pages, report.warnings),
})

Each warning in the report has a code, such as link-unresolved or text-clipped, so a test can check for them without reading messages.

When something looks wrong

The plugin warns in the console with a [snapdom-pdf] prefix: a block split across pages, a link without a target, text cut off. The same warnings arrive in the report.

A grey box where an image should be means the capture could not read that image. It shows up in the capture's result.warnings as image-fallback. Export a PDF with cross-origin images explains the fix.

If the PDF does not match the page, report a small example with the capture options, browser and warning codes.

Limits

• Text is an image unless you use vectorText, so a deep zoom shows the capture's resolution.
• Closed shadow roots cannot be read.
• Date inputs are written in ISO format, not as the browser shows them.
• An element used as header, footer or watermark has no selectable text. A repeated table header has no links.
• The full test suite runs in Chromium. Firefox and WebKit are checked for the main features.

Questions