html2pdf converts any webpage or element into a printable PDF entirely client-side using html2canvas and jsPDF.
The simplest way to use html2pdf is to download dist/html2pdf.bundle.min.js to your project folder and include it in your HTML with:
<script src="html2pdf.bundle.min.js"></script>Note: Click here for more information about using the unbundled version dist/html2canvas.min.js.
Install html2pdf 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 will not run in Node.js, it must be run in a browser.
Install html2pdf and its dependencies using Bower with bower install --save html2pdf.js (make sure to include .js in the package name).
Once installed, html2pdf 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);Every step of html2pdf is configurable, using its new Promise-based API. If html2pdf 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();The basic workflow of html2pdf tasks (enforced by the prereq system) is:
.from() -> .toContainer() -> .toCanvas() -> .toImg() -> .toPdf() -> .save()
| 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 |
html2pdf 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().from(element).set(opt).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. |
| image | object | {type: 'jpeg', quality: 0.95} | The image type and quality used to generate the PDF. See the Extra Features section 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). |
You may add html2pdf-specific page-breaks to your document by adding the CSS class html2pdf__page-break to any element (normally an empty div). For React elements, use className=html2pdf__page-break. During PDF creation, these elements will be given a height calculated to fill the remainder of the PDF page that they are on. Example usage:
<div id="element-to-print">
<span>I'm on page 1!</span>
<div class="html2pdf__page-break"></div>
<span>I'm on page 2!</span>
</div>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.
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.
html2pdf depends on the external packages html2canvas, jsPDF, and es6-promise. 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="es6-promise.auto.min.js"></script>
<script src="jspdf.min.js"></script>
<script src="html2canvas.min.js"></script>
<script src="html2pdf.min.js"></script>When submitting an issue, please provide reproducible code that highlights the issue, preferably by creating a fork of this template jsFiddle (which has html2pdf already loaded). Remember that html2pdf 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.
If you want to create a new feature or bugfix, please feel free to fork and submit a pull request! Use the develop branch, which features the latest development, and make changes to /src/ rather than directly to /dist/. You can test your changes by rebuilding with npm run build.
Copyright (c) 2017 Erik Koopmans <http://www.erik-koopmans.com/>