PDF Generation and Rendering Strategies in React
This comparison evaluates four distinct approaches to handling PDFs in web applications. jspdf serves as the low-level engine for programmatically drawing PDF content. html2pdf.js and react-to-pdf act as higher-level wrappers that convert HTML DOM elements into PDF files using snapshots. react-pdf is primarily designed for rendering and viewing existing PDF files within a React interface, rather than generating new ones. Understanding these roles is critical for selecting the right tool for creation versus display tasks.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
PDF Generation and Rendering Strategies in React
Handling PDFs in modern web applications usually falls into two categories: creating new documents from app data or displaying existing files to users. The packages jspdf, html2pdf.js, react-to-pdf, and react-pdf address these needs differently. Some focus on low-level drawing, others on HTML snapshots, and one specializes in viewing. Let's break down how they work in real engineering scenarios.
🏗️ Core Architecture: Engine vs Wrapper vs Viewer
jspdf is the core engine. It does not know about HTML or CSS. You draw text and lines using coordinates.
// jspdf: Manual drawing
import { jsPDF } from "jspdf";
const doc = new jsPDF();
doc.text("Hello World", 10, 10);
doc.save("document.pdf");
html2pdf.js wraps jspdf and html2canvas. It takes a DOM element and snapshots it.
// html2pdf.js: HTML snapshot
import html2pdf from "html2pdf.js";
const element = document.getElementById("content");
html2pdf().from(element).save();
react-to-pdf is a React hook wrapper around similar snapshot technology. It simplifies ref handling.
// react-to-pdf: Hook-based capture
import { useReactToPdf } from "react-to-pdf";
const { toPdf } = useReactToPdf();
const handlePrint = () => toPdf({ targetRef: ref });
react-pdf is a viewer. It loads existing PDF files and renders them as React components.
// react-pdf: Viewing existing files
import { Document, Page } from "react-pdf";
<Document file="/sample.pdf">{({ pageNum }) => <Page pageNumber={pageNum} />}</Document>
⚛️ React Integration: Components vs Imperative Calls
Integration styles vary from declarative components to imperative function calls. This affects how you manage state and triggers.
jspdf requires imperative logic. You call methods inside event handlers or effects.
// jspdf: Imperative function call
const generate = () => {
const doc = new jsPDF();
doc.text("Data", 10, 10);
doc.save();
};
html2pdf.js also uses imperative chains but targets DOM nodes directly.
// html2pdf.js: Imperative chain
const generate = () => {
html2pdf().from(document.getElementById("root")).save();
};
react-to-pdf offers a hook that fits naturally into React function components.
// react-to-pdf: React hook usage
const Component = () => {
const { toPdf } = useReactToPdf();
return <button onClick={() => toPdf({ targetRef: ref })}>Download</button>;
};
react-pdf uses declarative components to manage the view state.
// react-pdf: Declarative component
const Viewer = () => {
return <Document file="/file.pdf"><Page pageNumber={1} /></Document>;
};
🎨 Styling and Fidelity: CSS vs Vector vs File Load
How the library handles styles determines if your PDF looks like your website or a custom report.
jspdf ignores CSS. You must define fonts and positions manually.
// jspdf: No CSS support
doc.setFont("helvetica");
doc.setFontSize(16);
doc.text("Title", 10, 10); // Coordinates required
html2pdf.js respects CSS because it renders the DOM. What you see is what you get.
// html2pdf.js: CSS respected
// <div id="content" class="styled-box">Text</div>
// The .styled-box classes are preserved in the snapshot
html2pdf().from(document.getElementById("content")).save();
react-to-pdf also relies on DOM rendering, so CSS classes apply normally.
// react-to-pdf: CSS respected
// <div ref={ref} className="card">Content</div>
// The .card styles are captured in the output
const { toPdf } = useReactToPdf();
react-pdf does not apply app CSS to the PDF content. It renders the internal structure of the PDF file itself.
// react-pdf: Internal PDF styling
// Styles come from the PDF file, not your React CSS
<Document file="/report.pdf"><Page width={600} /></Document>
⚠️ Critical Distinction: Generation vs Viewing
A common architectural error is confusing react-pdf with generation tools. The ecosystem has two similar names with different jobs.
jspdf, html2pdf.js, and react-to-pdf create new files. They take data or HTML and output a binary PDF.
// Generation packages output a file
// jspdf, html2pdf.js, react-to-pdf all call .save() or similar
doc.save("new-file.pdf");
react-pdf displays existing files. It does not have a .save() method for creation.
// react-pdf loads a file
// It does not generate content from React components
<Document file="/existing.pdf" />
💡 Note: If you need to generate PDFs using React components (like
<View>and<Text>), the standard library is@react-pdf/renderer, notreact-pdf.react-pdfis strictly for viewing.
🛠️ Maintenance and Ecosystem Risks
Wrapper libraries depend on underlying engines. If the engine changes, the wrapper might break.
jspdf is the foundation. It has the longest lifespan and fewest external dependencies.
// jspdf: Stable core
import { jsPDF } from "jspdf"; // Direct dependency
html2pdf.js depends on jspdf and html2canvas. Updates to either can affect behavior.
// html2pdf.js: Multiple dependencies
// Issues in html2canvas may affect image quality in PDF
html2pdf().set({ html2canvas: { scale: 2 } }).from(element).save();
react-to-pdf is a thin wrapper. It may lag behind React updates or underlying PDF engines.
// react-to-pdf: Wrapper risk
// Check npm for recent commits before adopting
const { toPdf } = useReactToPdf();
react-pdf depends on pdf.js by Mozilla. It is well-maintained for viewing purposes.
// react-pdf: Viewer stability
// Relies on Mozilla's pdf.js rendering engine
import { pdfjs } from "react-pdf";
📊 Summary: Selection Matrix
| Feature | jspdf | html2pdf.js | react-to-pdf | react-pdf |
|---|---|---|---|---|
| Primary Goal | Generate (Vector) | Generate (Snapshot) | Generate (Snapshot) | View Existing |
| CSS Support | ❌ No | ✅ Yes | ✅ Yes | ❌ N/A |
| Text Selectable | ✅ Yes | ❌ Often No | ❌ Often No | ✅ Yes |
| React Style | Imperative | Imperative | Hook | Component |
| Best For | Custom Reports | Invoices/Receipts | Quick React Exports | PDF Viewer UI |
💡 Final Recommendation
Select your tool based on the source of your content. If you have raw data and need crisp text, use jspdf. If you have an HTML layout you want to print exactly, use html2pdf.js. If you want a React hook to simplify that HTML capture, use react-to-pdf. If you need to let users read uploaded PDF files, use react-pdf. Avoid using react-pdf for generation tasks — that requires @react-pdf/renderer instead.
How to Choose: html2pdf.js vs jspdf vs react-pdf vs react-to-pdf
- html2pdf.js:
Choose
html2pdf.jswhen you need a quick solution to convert existing HTML layouts into PDF files without rewriting styles. It is ideal for invoices or reports that already exist as DOM elements and require visual fidelity to the screen. Be aware that text in the resulting PDF may not be selectable since it is often rendered as images. This tool balances ease of use with reasonable output quality for standard web content. - jspdf:
Choose
jspdfwhen you require precise, programmatic control over every element in the PDF document. It is best suited for generating documents from raw data where HTML CSS support is not needed or reliable. You will need to manually define coordinates for text and shapes, which offers flexibility but increases development time. This is the foundational library that many other wrappers rely on for core functionality. - react-pdf:
Choose
react-pdfwhen your goal is to display existing PDF files inside your React application interface. It provides components to render PDF pages with support for zooming, navigation, and text layer extraction. Do not select this package if you intend to generate new PDF files from React components, as that is not its primary function. For generation tasks in React, evaluate@react-pdf/rendererinstead. - react-to-pdf:
Choose
react-to-pdfwhen you want a React-specific hook to simplify capturing components as PDF files. It reduces boilerplate code by managing references and conversion triggers internally. This package is suitable for projects that prefer hook-based patterns over manual DOM manipulation. Verify its maintenance status before adoption, as wrapper libraries can become outdated faster than core engines.
Popular Comparisons
README for html2pdf.js
html2pdf.js
html2pdf.js converts any webpage or element into a printable PDF entirely client-side using html2canvas and jsPDF.
Table of contents
Getting started
CDN
The simplest way to use html2pdf.js is to include it as a script in your HTML by using cdnjs:
<script src="https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js" integrity="sha512-GsLlZN/3F2ErC5ifS5QtgpiJtWd43JWSuIgh7mbzZ8zBps+dvLusV+eNQATqgA/HdeKFVgA5v3S/cIrLF7QnIg==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
Using a CDN URL will lock you to a specific version, which should ensure stability and give you control over when to change versions. cdnjs gives you access to all past versions of html2pdf.js.
Note: Read about dependencies for more information about using the unbundled version dist/html2canvas.min.js.
Raw JS
You may also download dist/html2pdf.bundle.min.js directly to your project folder and include it in your HTML with:
<script src="html2pdf.bundle.min.js"></script>
NPM
Install html2pdf.js and its dependencies using NPM with npm install --save html2pdf.js (make sure to include .js in the package name).
Note: You can use NPM to create your project, but html2pdf.js will not run in Node.js, it must be run in a browser.
Bower
Install html2pdf.js and its dependencies using Bower with bower install --save html2pdf.js (make sure to include .js in the package name).
Console
If you're on a webpage that you can't modify directly and wish to use html2pdf.js to capture a screenshot, you can follow these steps:
- Open your browser's console (instructions for different browsers here).
- Paste in this code:
function addScript(url) { var script = document.createElement('script'); script.type = 'application/javascript'; script.src = url; document.head.appendChild(script); } addScript('https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js'); - You may now execute html2pdf.js commands directly from the console. To capture a default PDF of the entire page, use
html2pdf(document.body).
Usage
Once installed, html2pdf.js is ready to use. The following command will generate a PDF of #element-to-print and prompt the user to save the result:
var element = document.getElementById('element-to-print');
html2pdf(element);
Advanced usage
Every step of html2pdf.js is configurable, using its new Promise-based API. If html2pdf.js is called without arguments, it will return a Worker object:
var worker = html2pdf(); // Or: var worker = new html2pdf.Worker;
This worker has methods that can be chained sequentially, as each Promise resolves, and allows insertion of your own intermediate functions between steps. A prerequisite system allows you to skip over mandatory steps (like canvas creation) without any trouble:
// This will implicitly create the canvas and PDF objects before saving.
var worker = html2pdf().from(element).save();
Workflow
The basic workflow of html2pdf.js tasks (enforced by the prereq system) is:
.from() -> .toContainer() -> .toCanvas() -> .toImg() -> .toPdf() -> .save()
Worker API
| Method | Arguments | Description |
|---|---|---|
| from | src, type | Sets the source (HTML string or element) for the PDF. Optional type specifies other sources: 'string', 'element', 'canvas', or 'img'. |
| to | target | Converts the source to the specified target ('container', 'canvas', 'img', or 'pdf'). Each target also has its own toX method that can be called directly: toContainer(), toCanvas(), toImg(), and toPdf(). |
| output | type, options, src | Routes to the appropriate outputPdf or outputImg method based on specified src ('pdf' (default) or 'img'). |
| outputPdf | type, options | Sends type and options to the jsPDF object's output method, and returns the result as a Promise (use .then to access). See the jsPDF source code for more info. |
| outputImg | type, options | Returns the specified data type for the image as a Promise (use .then to access). Supported types: 'img', 'datauristring'/'dataurlstring', and 'datauri'/'dataurl'. |
| save | filename | Saves the PDF object with the optional filename (creates user download prompt). |
| set | opt | Sets the specified properties. See Options below for more details. |
| get | key, cbk | Returns the property specified in key, either as a Promise (use .then to access), or by calling cbk if provided. |
| then | onFulfilled, onRejected | Standard Promise method, with this re-bound to the Worker, and with added progress-tracking (see Progress below). Note that .then returns a Worker, which is a subclass of Promise. |
| thenCore | onFulFilled, onRejected | Standard Promise method, with this re-bound to the Worker (no progress-tracking). Note that .thenCore returns a Worker, which is a subclass of Promise. |
| thenExternal | onFulfilled, onRejected | True Promise method. Using this 'exits' the Worker chain - you will not be able to continue chaining Worker methods after .thenExternal. |
| catch, catchExternal | onRejected | Standard Promise method. catchExternal exits the Worker chain - you will not be able to continue chaining Worker methods after .catchExternal. |
| error | msg | Throws an error in the Worker's Promise chain. |
A few aliases are also provided for convenience:
| Method | Alias |
|---|---|
| save | saveAs |
| set | using |
| output | export |
| then | run |
Options
html2pdf.js can be configured using an optional opt parameter:
var element = document.getElementById('element-to-print');
var opt = {
margin: 1,
filename: 'myfile.pdf',
image: { type: 'jpeg', quality: 0.98 },
html2canvas: { scale: 2 },
jsPDF: { unit: 'in', format: 'letter', orientation: 'portrait' }
};
// New Promise-based usage:
html2pdf().set(opt).from(element).save();
// Old monolithic-style usage:
html2pdf(element, opt);
The opt parameter has the following optional fields:
| Name | Type | Default | Description |
|---|---|---|---|
| margin | number or array | 0 | PDF margin (in jsPDF units). Can be a single number, [vMargin, hMargin], or [top, left, bottom, right]. |
| filename | string | 'file.pdf' | The default filename of the exported PDF. |
| pagebreak | object | {mode: ['css', 'legacy']} | Controls the pagebreak behaviour on the page. See Page-breaks below. |
| image | object | {type: 'jpeg', quality: 0.95} | The image type and quality used to generate the PDF. See Image type and quality below. |
| enableLinks | boolean | true | If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
| html2canvas | object | { } | Configuration options sent directly to html2canvas (see here for usage). |
| jsPDF | object | { } | Configuration options sent directly to jsPDF (see here for usage). |
Page-breaks
html2pdf.js has the ability to automatically add page-breaks to clean up your document. Page-breaks can be added by CSS styles, set on individual elements using selectors, or avoided from breaking inside all elements (avoid-all mode).
By default, html2pdf.js will respect most CSS break-before, break-after, and break-inside rules, and also add page-breaks after any element with class html2pdf__page-break (for legacy purposes).
Page-break settings
| Setting | Type | Default | Description |
|---|---|---|---|
| mode | string or array | ['css', 'legacy'] | The mode(s) on which to automatically add page-breaks. One or more of 'avoid-all', 'css', and 'legacy'. |
| before | string or array | [] | CSS selectors for which to add page-breaks before each element. Can be a specific element with an ID ('#myID'), all elements of a type (e.g. 'img'), all of a class ('.myClass'), or even '*' to match every element. |
| after | string or array | [] | Like 'before', but adds a page-break immediately after the element. |
| avoid | string or array | [] | Like 'before', but avoids page-breaks on these elements. You can enable this feature on every element using the 'avoid-all' mode. |
Page-break modes
| Mode | Description |
|---|---|
| avoid-all | Automatically adds page-breaks to avoid splitting any elements across pages. |
| css | Adds page-breaks according to the CSS break-before, break-after, and break-inside properties. Only recognizes always/left/right for before/after, and avoid for inside. |
| legacy | Adds page-breaks after elements with class html2pdf__page-break. This feature may be removed in the future. |
Example usage
// Avoid page-breaks on all elements, and add one before #page2el.
html2pdf().set({
pagebreak: { mode: 'avoid-all', before: '#page2el' }
});
// Enable all 'modes', with no explicit elements.
html2pdf().set({
pagebreak: { mode: ['avoid-all', 'css', 'legacy'] }
});
// No modes, only explicit elements.
html2pdf().set({
pagebreak: { before: '.beforeClass', after: ['#after1', '#after2'], avoid: 'img' }
});
Image type and quality
You may customize the image type and quality exported from the canvas by setting the image option. This must be an object with the following fields:
| Name | Type | Default | Description |
|---|---|---|---|
| type | string | 'jpeg' | The image type. HTMLCanvasElement only supports 'png', 'jpeg', and 'webp' (on Chrome). |
| quality | number | 0.95 | The image quality, from 0 to 1. This setting is only used for jpeg/webp (not png). |
These options are limited to the available settings for HTMLCanvasElement.toDataURL(), which ignores quality settings for 'png' images. To enable png image compression, try using the canvas-png-compression shim, which should be an in-place solution to enable png compression via the quality option.
Progress tracking
The Worker object returned by html2pdf() has a built-in progress-tracking mechanism. It will be updated to allow a progress callback that will be called with each update, however it is currently a work-in-progress.
Dependencies
html2pdf.js depends on the external packages html2canvas and jsPDF. These dependencies are automatically loaded when using NPM or the bundled package.
If using the unbundled dist/html2pdf.min.js (or its un-minified version), you must also include each dependency. Order is important, otherwise html2canvas will be overridden by jsPDF's own internal implementation:
<script src="jspdf.min.js"></script>
<script src="html2canvas.min.js"></script>
<script src="html2pdf.min.js"></script>
Contributing
[!TIP] Working on html2pdf.js locally? Use
npm startto host local demos on http://localhost:8000.
Issues
When submitting an issue, please provide reproducible code that highlights the issue, preferably by creating a fork of this template jsFiddle (which has html2pdf.js already loaded). Remember that html2pdf.js uses html2canvas and jsPDF as dependencies, so it's a good idea to check each of those repositories' issue trackers to see if your problem has already been addressed.
Known issues
-
Rendering: The rendering engine html2canvas isn't perfect (though it's pretty good!). If html2canvas isn't rendering your content correctly, I can't fix it.
- You can test this with something like this fiddle, to see if there's a problem in the canvas creation itself.
-
Node cloning (CSS etc): The way html2pdf.js clones your content before sending to html2canvas is buggy. A fix is currently being developed - try out:
- direct file: Go to html2pdf.js/bugfix/clone-nodes-BUILD and replace the files in your project with the relevant files (e.g.
dist/html2pdf.bundle.js) - npm:
npm install eKoopmans/html2pdf.js#bugfix/clone-nodes-BUILD - Related project: Bugfix: Cloned nodes
- direct file: Go to html2pdf.js/bugfix/clone-nodes-BUILD and replace the files in your project with the relevant files (e.g.
-
Resizing: Currently, html2pdf.js resizes the root element to fit onto a PDF page (causing internal content to "reflow").
- This is often desired behaviour, but not always.
- There are plans to add alternate behaviour (e.g. "shrink-to-page"), but nothing that's ready to test yet.
- Related project: Feature: Single-page PDFs
-
Rendered as image: html2pdf.js renders all content into an image, then places that image into a PDF.
- This means text is not selectable or searchable, and causes large file sizes.
- This is currently unavoidable, however recent improvements in jsPDF mean that it may soon be possible to render straight into vector graphics.
- Related project: Feature: New renderer
-
Promise clashes: html2pdf.js relies on specific Promise behaviour, and can fail when used with custom Promise libraries.
- Related project: Bugfix: Sandboxed promises
-
Maximum size: HTML5 canvases have a maximum height/width. Anything larger will fail to render.
- This is a limitation of HTML5 itself, and results in large PDFs rendering completely blank in html2pdf.js.
- The jsPDF canvas renderer (mentioned in Known Issue #4) may be able to fix this issue!
- Related project: Bugfix: Maximum canvas size
Tests
html2pdf.js performs automatic vdiff (visual difference) comparisons on PDFs generated from a collection of sample HTML files. Contributions of additional test cases are more than welcome - see test/vdiff/html2pdf.vdiff.js and test/reference/*.html for examples. Some changes may require adding more options to the test harness, test/util/test-harness.js.
Pull requests
If you want to create a new feature or bugfix, please feel free to fork and submit a pull request! Create a fork, branch off of main, and make changes to the /src/ files (rather than directly to /dist/). You can test your changes by rebuilding with npm run build.
Credits
Contributors
Special thanks
- Sauce Labs for unit testing.
License
Copyright (c) 2017-2019 Erik Koopmans <http://www.erik-koopmans.com/>