PDF Preview - standalone example

Documentation

Getting started

Add a root element with a pages container inside it, create a preview for the root and load a document into it. Every control is optional; leave out the ones you do not need.

<div id="preview" data-pdf-preview>
  <button type="button" data-pdf-preview-prev>Prev</button>
  <input type="number" data-pdf-preview-page> / <span data-pdf-preview-total></span>
  <button type="button" data-pdf-preview-next>Next</button>
  <div data-pdf-preview-pages></div>
</div>

<script src="pdf-preview.min.js"></script>
<script>
  var preview = new PdfPreview('#preview', { height: '70vh' });

  preview.load(file); // a File, a Blob or a URL
</script>

To set everything up from markup instead, put the options on the root as data- attributes (see Options) and call PdfPreview.initAll() once. A root with data-pdf-preview-src starts loading straight away.

Options

Pass options as the second argument of new PdfPreview() or PdfPreview.initAll(), or as data- attributes on the root element. When both are given, the JavaScript value wins. Options are read once, when the preview is created.

Markup hooks

The library finds its elements with these selectors, inside the root. Everything except the root is optional. Rename any of them with the selectors option, so another project does not have to use these attribute names.

Methods

Events

Dispatched on the root element. All of them bubble, so you can also listen higher up.

document.querySelector('#local-preview')
  .addEventListener('pdfpreview:loaded', function (e) {
    console.log('pages:', e.detail.pageCount);
  });

Thumbnails

A thumbnail is one page of a PDF (the first, unless you ask for another) drawn to an offscreen canvas and handed back as a data URL. The canvas is thrown away, so what you hold on to is a string you can put in an <img>, store, or pass around. There is no pagination, no scrolling container and no root element: a thumbnail is a still image, and sits anywhere an image does.

Thumbnails resolve with the data URL and the size to show it at, in CSS px: { dataUrl, width, height, page, pageCount }.

Fill an <img> yourself

PdfPreview.thumbnail() takes the same sources as load(): a File, a Blob or a URL.

<img id="thumb" alt="First page of the document">

<script src="pdf-preview.min.js"></script>
<script>
  var img = document.getElementById('thumb');

  PdfPreview.thumbnail('invoice.pdf', { width: 120 })
    .then(function (thumb) {
      img.src = thumb.dataUrl;
      img.width = thumb.width;   // keeps the tile from jumping
      img.height = thumb.height;
    })
    .catch(function (error) {
      console.warn('no thumbnail:', error);  // leave the fallback icon in place
    });
</script>

Straight from a file input

PdfPreview.thumbnailInto() does the same and sets src, width and height on the element for you. On failure it leaves the element alone, so whatever it already shows stays visible.

document.getElementById('file').addEventListener('change', function (event) {
  var file = event.target.files[0];

  if (file && file.type === 'application/pdf') {
    PdfPreview.thumbnailInto('#thumb', file, { width: 120 });
  }
});

From markup

Put the source and any options on the <img> as data- attributes and call PdfPreview.initThumbnails() once, the same way PdfPreview.initAll() works for previews. Calling it again picks up newly added elements and skips the ones already done, so it is safe after rendering more markup.

<img
  data-pdf-thumbnail
  data-pdf-thumbnail-src="invoice.pdf"
  data-pdf-thumbnail-width="120"
  alt="First page of invoice.pdf"
>

<script>PdfPreview.initThumbnails();</script>

Alongside a preview

When a preview already has the document open, ask it for the thumbnail instead. The file is read and parsed once and both come out of the same document, which is the cheapest option when you show a tile and a full preview of the same upload.

var preview = new PdfPreview('#preview');

preview.load(file).then(function () {
  return preview.getThumbnail({ width: 120 });
}).then(function (thumb) {
  document.getElementById('thumb').src = thumb.dataUrl;
});

Thumbnail options

Pass these as the last argument of thumbnail(), thumbnailInto(), initThumbnails() or getThumbnail(), or as data- attributes on the element. When both are given, the JavaScript value wins.

Thumbnail events

Dispatched on the <img> by thumbnailInto() and initThumbnails(), so markup-driven thumbnails can be followed without holding on to a promise. Both bubble.

document.addEventListener('pdfthumbnail:error', function (e) {
  e.target.closest('.upload').classList.add('upload--no-thumbnail');
});

Notes

• Give the <img> a meaningful alt, naming the document the thumbnail is of. The library never sets one, since only the calling code knows what the file is.
• Nothing is kept alive once a thumbnail resolves: the document is closed and any object URL for a File is revoked. The data URL is all that remains, so it is worth keeping tiles small, which is why the default format is JPEG.
• Unlike previews, thumbnails do not measure the page, so they can be drawn into a hidden or not-yet-shown element, a modal included.
• Thumbnails from getThumbnail() resolve with undefined when a later load(), reset() or destroy() replaces the document while the thumbnail is being drawn, matching how load() behaves.

Styling

The library brings layout only: a scrolling pages container with the pages stacked inside it. Everything visual is up to you. The base styles are added at the very top of <head>, so any rule in your own stylesheet wins over them. To change the height or spacing from CSS, set the real property (max-height, padding, margin-top) rather than the custom property, which the options set on the element itself.

The custom properties are set even when injectStyles is off, so your own CSS can use them, for example max-height: var(--pdfp-height).

Sharpness

Pages are drawn at the size they are shown multiplied by the device pixel ratio (capped by maxPixelRatio), so they stay sharp on dense screens without wasting memory on others. Very large pages are scaled down to stay within the largest canvas iOS Safari will draw.

The container width is measured when a document loads, so load into a visible container. In a modal, call load() once the modal is shown. A container with no width falls back to scale. Pages are not redrawn when the container is resized; the layout stays correct, but they may look slightly soft until the next load.

Security

Every document is opened with pdf.js's isEvalSupported set to false, for thumbnails as much as for previews. With it on (the pdf.js default), pdf.js turns font glyphs into code with new Function(), and in versions before 4.2.67 a crafted PDF can use that to run its own script on the page showing it (CVE-2024-4367). With it off, glyphs are interpreted instead, which is slightly slower. The setting is passed each time a document is opened, so it also covers a pdf.js supplied through pdfjsLib. Treat this as a safeguard, not a substitute for keeping pdf.js up to date, especially where staff open PDFs uploaded by customers.

Module formats

The library is wrapped in UMD, so it works as a global (window.PdfPreview), via CommonJS (require('pdf-preview')) or with AMD.