React to PDF

Common errors

• Content in PDF appears blurry or pixelated.

  cause The default `resolution` setting might be too low for the content or target display density, as the PDF is generated from an image capture.
  fix Increase the `resolution` option (e.g., `Resolution.HIGH` or a higher numeric value like `6` or `10`) in the `usePDF` hook or `generatePDF` options. Be aware that higher resolutions increase PDF file size and generation time.

• ReferenceError: require is not defined or Module parse failed: 'import' and 'export' may only appear at the top level.

  cause Attempting to use CommonJS `require()` syntax or incorrect ES module syntax in a modern JavaScript project configured for ES modules.
  fix Ensure you are using ES module `import` statements for `react-to-pdf`. For example, use `import { usePDF } from 'react-to-pdf';` or `import generatePDF from 'react-to-pdf';`.

• PDF is blank, incomplete, or missing styling/images.

  cause The target React component might not have fully rendered, or external resources (images, fonts, complex CSS) might not have loaded before the PDF generation function was called. CORS issues can also prevent image loading.
  fix Ensure the target element is fully mounted and all asynchronous content (images, fonts) has loaded. Use the `overrides.canvas.useCORS: true` option if images are from a different origin. Implement a delay or wait for critical resources to load before triggering PDF generation.

• TypeError: (0, react_to_pdf__WEBPACK_IMPORTED_MODULE_0__.generatePDF) is not a function

  cause Incorrect import syntax for a default export. `generatePDF` is a default export, but it's being imported as a named export.
  fix Correct the import statement for `generatePDF` to `import generatePDF from 'react-to-pdf';`. Named exports like `usePDF`, `Resolution`, and `Margin` correctly use curly braces.

Warnings

• breaking Version 3.0.0 introduced significant changes by upgrading to `jsPDF v4`, which dropped support for Internet Explorer. This also included various dependency updates and security fixes. Projects targeting older browsers need to either remain on an earlier `react-to-pdf` version or use polyfills for `jsPDF`.
  Fix: Ensure your target browser environment is modern (non-IE). If `jsPDF` overrides were used, review `jsPDF` v4's breaking changes. Consider upgrading to the latest version for continued support.
• breaking Version 2.0.0 marked a major release, aligning with `jsPDF v3`'s breaking changes. This version dropped support for Internet Explorer and included security fixes for `jsPDF`'s `html` function by updating `dompurify`. While no other direct breaking changes were noted, the IE drop is significant.
  Fix: Migrate to a modern browser environment. If stuck on `v2.x.x`, review `jsPDF v3`'s release notes for any other behavioral changes. It is recommended to upgrade to the latest stable version for security.
• gotcha The generated PDFs are not vectorized; they are created from a screenshot of the React component. This means the output is an image, not scalable vector graphics. Text in the PDF will not be selectable or searchable as native text.
  Fix: Understand this limitation. If vectorized PDFs, text selection, or perfect scalability are critical, this library may not be suitable. Consider alternatives like `@react-pdf/renderer` which offers true vector-based PDF generation.
• gotcha The library does not support Server-Side Rendering (SSR). It relies on browser-specific APIs to capture the component's appearance, making it unsuitable for Node.js-only environments.
  Fix: Only use this library in client-side React applications where a browser DOM is available. For server-side PDF generation, explore headless browser solutions or dedicated Node.js PDF libraries.
• breaking Multiple versions have addressed security vulnerabilities originating from the underlying `jsPDF` library (e.g., `v3.2.0`, `v3.1.0`, `v3.0.0`, `v2.0.2`, `v2.0.0`) and other dependencies like `tar-fs` (`v2.0.1`). Regularly updating to the latest stable version is critical to mitigate these risks.
  Fix: Always upgrade to the latest stable version of `react-to-pdf` to ensure you receive all security patches from its dependencies. Monitor `jsPDF`'s security advisories for deeper insights.

Install

• npm install react-to-pdf npm
• yarn add react-to-pdf yarn
• pnpm add react-to-pdf pnpm

Imports

• usePDF
  wrong:

  const { usePDF } = require('react-to-pdf')

  correct:

  import { usePDF } from 'react-to-pdf'

  The `usePDF` hook is a named export for functional components. CommonJS `require` syntax is generally not compatible with modern React setups using ES modules.
• generatePDF
  wrong:

  import { generatePDF } from 'react-to-pdf'

  correct:

  import generatePDF from 'react-to-pdf'

  `generatePDF` is the default export of the library; import it without curly braces. Attempting to import it as a named export will result in an error.
• Resolution, Margin

  import { Resolution, Margin } from 'react-to-pdf'

  These are named exports representing enums or constants used to configure advanced PDF generation options.

Quickstart

Demonstrates how to use the `usePDF` hook to generate and download a PDF from a React component's content, including basic page options.

import { usePDF } from 'react-to-pdf';

const MyPdfDocument = () => {
  const { toPDF, targetRef } = usePDF({
    filename: 'my-react-component.pdf',
    page: {
      margin: 10, // in mm
      format: 'A4',
      orientation: 'portrait'
    }
  });

  return (
    <div>
      <button onClick={() => toPDF()}>Download PDF</button>
      <div ref={targetRef} style={{
        padding: '20px',
        border: '1px solid #ccc',
        borderRadius: '8px',
        fontFamily: 'Arial, sans-serif'
      }}>
        <h1>Hello from React to PDF!</h1>
        <p>This content will be converted into a PDF document.</p>
        <ul>
          <li>Item 1</li>
          <li>Item 2</li>
          <li>Item 3</li>
        </ul>
        <p>Current date: {new Date().toLocaleDateString()}</p>
      </div>
    </div>
  );
};

export default MyPdfDocument;