@enmo-design/html2pdf v1.0.1

html2pdf

html2pdf converts any webpage or element into a printable PDF entirely client-side using html2canvas and jsPDF.

Getting started

HTML

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>

NPM

Install html2pdf and its dependencies using NPM with npm install --save @enmo-design/html2pdf.

Note: You can use NPM to create your project, but html2pdf will not run in Node.js, it must be run in a browser.

Usage

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);

Advanced usage

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();

Workflow

The basic workflow of html2pdf tasks (enforced by the prereq system) is:

.from() -> .toContainer() -> .toCanvas() -> .toImg() -> .toPdf() -> .save()

Worker API

A few aliases are also provided for convenience:

Options

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().set(opt).from(element).save();

// Old monolithic-style usage:
html2pdf(element, opt);

The opt parameter has the following optional fields:

Page-breaks

html2pdf 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 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

Page-break modes

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:

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.

Contributing

Contributors

• @node-rookie

License

The MIT License