Client-Side HTML to PDF Conversion

Common errors

• ReferenceError: html2pdf is not defined

  cause Attempting to use `html2pdf` in a Node.js environment, or the script/module was not loaded correctly in the browser.
  fix Ensure the code is running in a browser. If using npm, verify your bundler (e.g., Webpack, Rollup) correctly includes `html2pdf.js`. If using CDN, confirm the script tag is present and loaded before `html2pdf` is called.

• TypeError: Cannot read properties of undefined (reading 'Worker')

  cause Incorrectly trying to destructure `Worker` as a named import (e.g., `import { Worker } from 'html2pdf.js'`) when it's a property of the default export.
  fix Import the default export first, then access `Worker` as a property: `import html2pdf from 'html2pdf.js'; const worker = new html2pdf.Worker();`.

• Some HTML elements or styles are missing/incorrect in the generated PDF.

  cause Limitations of `html2canvas` in accurately replicating all browser rendering features, especially for advanced CSS or dynamic content not fully stable at the time of canvas capture.
  fix Adjust `html2canvas` options (e.g., `scale`, `useCORS`, `logging`). Ensure images are loaded and fonts are available. For complex layouts, try simplifying the HTML/CSS structure specifically for the PDF conversion target, or delay conversion until all dynamic content has settled.

Warnings

• gotcha html2pdf.js is designed exclusively for client-side browser environments and cannot be run in Node.js. Attempts to use it server-side will result in errors.
  Fix: Ensure the library is only executed within a web browser context. For server-side PDF generation, consider headless browser solutions (e.g., Puppeteer) or dedicated Node.js PDF libraries.
• breaking Version 0.13.0 updated the underlying jspdf dependency from 3.0.3 to 4.0.0. This major version bump in jspdf may introduce breaking changes or API alterations that could affect advanced custom configurations or integrations directly interacting with jspdf objects.
  Fix: Review the jspdf 4.0.0 release notes for any breaking changes if you are using advanced html2pdf.js configurations that rely on jspdf internals. Test your application thoroughly after upgrading to html2pdf.js v0.13.0 or later.
• gotcha When manually including html2pdf.js via script tags, differentiate between `html2pdf.bundle.min.js` and `html2pdf.min.js`. The `bundle` version includes its dependencies (`html2canvas` and `jsPDF`), while the unbundled version requires these dependencies to be loaded separately.
  Fix: For simplicity, always use `html2pdf.bundle.min.js` unless you have a specific need to manage `html2canvas` and `jsPDF` versions independently. If using the unbundled version, ensure `html2canvas` and `jsPDF` are loaded *before* `html2pdf.min.js`.
• gotcha The quality of PDF output can be highly dependent on the complexity of HTML and CSS. Certain CSS properties (e.g., `flexbox`, `grid`, `z-index` with complex stacking contexts) may not render perfectly due to the underlying `html2canvas` limitations in faithfully replicating browser rendering.
  Fix: Simplify complex layouts and CSS when possible for PDF conversion. Test different `html2canvas` options like `scale`, `dpi`, and `letterRendering` to find the best balance. Consider pre-rendering complex elements as images if precise fidelity is critical.

Install

• npm install html2pdf.js npm
• yarn add html2pdf.js yarn
• pnpm add html2pdf.js pnpm

Imports

• html2pdf
  wrong:

  const html2pdf = require('html2pdf.js');

  correct:

  import html2pdf from 'html2pdf.js';

  The primary API is a callable default export. CommonJS 'require' is not supported as the library is browser-only.
• html2pdf.Worker

  import html2pdf from 'html2pdf.js';
  const worker = new html2pdf.Worker();

  The Worker API for advanced usage is accessed as a property of the default export, or via html2pdf() called without arguments. It is not a named export itself.
• Global `html2pdf`
  wrong:

  import html2pdf from 'https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.14.0/html2pdf.bundle.min.js';

  correct:

  <script src="https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.14.0/html2pdf.bundle.min.js"></script>
  // Then access directly: html2pdf(element);

  When included via a CDN script tag, `html2pdf` is exposed as a global variable. Direct ES Module imports from CDN URLs (without a build step) are generally not supported for this bundled format.

Quickstart

This quickstart demonstrates how to import `html2pdf.js` as an ES module, create an HTML element dynamically, and then use the `html2pdf` function with common options to generate and save a PDF document from that element.

import html2pdf from 'html2pdf.js';

const content = document.createElement('div');
content.innerHTML = `
  <h1>Hello, PDF!</h1>
  <p>This is some sample content that will be converted to a PDF document.</p>
  <img src="https://via.placeholder.com/150" alt="Placeholder Image">
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
`;

// Append content to body for demonstration, normally it would be an existing element
document.body.appendChild(content);

// Generate PDF from the content element
html2pdf(content, {
  margin: 1,
  filename: 'document.pdf',
  image: { type: 'jpeg', quality: 0.98 },
  html2canvas: { scale: 2, logging: true, dpi: 192, letterRendering: true },
  jsPDF: { unit: 'in', format: 'letter', orientation: 'portrait' }
}).then(() => {
  console.log('PDF generation complete!');
  // Optionally remove the appended content if it was temporary
  document.body.removeChild(content);
}).catch(error => {
  console.error('PDF generation failed:', error);
});