Choosing a renderer - Guides

The three renderers

Renderer	How to choose it	Draws	Good for
PDF.js	The default, or `canvas=.js`	On a canvas	Every page: it is already loaded with WebPDF.
PDFium	`ium` on the file, `ium=+` on the `<script>`, or `canvas=ium` on a page	On a canvas, from WebAssembly in a worker	Pages that should look exactly as in Chrome.
SVG	`svg`	Vector SVG, built in a worker	Pages that stay sharp at any zoom, and vector exports.

One page, three renderers

The same page drawn by each of them:

html

<pdf-file id=f src=//pdf.ist/web.pdf ium></pdf-file>
<pdf-page of=f canvas=.js scale=0.3></pdf-page>
<pdf-page of=f canvas=ium scale=0.3></pdf-page>
<pdf-page of=f svg scale=0.3></pdf-page>

PDF.js is Mozilla's PDF engine, the one Firefox shows PDFs with. WebPDF always loads its latest version, and uses it for everything else too: parsing the file, the text layer, links and form fields. A page drawn with it is a canvas with one pixel per CSS pixel of the page at its scale: to draw a page sharper on a high-density screen, size it with CSS and raise its scale; see Styling WebPDF.

PDFium

PDFium is Google's PDF engine, the one Chrome shows PDFs with, here compiled to WebAssembly. It runs in a worker, and loads (about 2.4 MB) only with the first page that needs it; a lazy page waits until it comes near the viewport.

PDFium is opt-in. With ium on a file, or ium=+ on the <script> for every file, the file's pages draw with PDFium unless they say canvas=.js:

html

<script src=//new.webpdf.pro/.js type=module ium=+></script>
<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f></pdf-page>                <!-- PDFium -->
<pdf-page of=f canvas=.js></pdf-page>   <!-- PDF.js -->

A bare ium on the script only makes PDFium available to every file: pages draw with PDF.js, and PDFium loads when a page asks for it, with canvas=ium, the I key or the bar's menu:

html

<script src=//new.webpdf.pro/.js type=module ium></script>
<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f></pdf-page>                <!-- PDF.js -->
<pdf-page of=f canvas=ium></pdf-page>   <!-- PDFium -->

Note: Without ium on the file or the script, canvas=ium still draws with PDF.js.

The text layer, links and form fields of a PDFium page still come from PDF.js, so they work the same with either engine. To leave PDF.js out, see PDFium alone.

PDFium alone

A PDFium page still reads the file through PDF.js: the page count, the page's size, its text layer, links and form fields come from PDF.js, and PDFium draws the image. With js in -, PDFium reads the page alone:

html

<script src=//new.webpdf.pro/.js type=module ium=+ -=js></script>
<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f></pdf-page>   <!-- PDFium alone -->

The page count and the page sizes are PDFium's, so a page that PDF.js cannot read still shows, and so do the pages after it.
The text layer is PDFium's text, cut into the same pieces as PDF.js cuts it, so selecting and finding text work the same. A second PDFium worker reads it while the first draws.
Links, and buttons that open a link, go to a page or reset the form, are PDFium's.
Text fields, check boxes and radio buttons are PDFium's drawing under see-through fields that you type and click in; lists stay HTML. This needs PDFium to hold the file's form: js on the file or the script.

On a file, or on the <script> for every file, js also makes PDFium hold the form: formData, XFDF and save() go through PDFium. On a single page of a file whose form PDF.js holds, PDFium draws the page's fields into its image instead. PDF.js still opens the file in the background, for signatures and for the file's PDF.js and SVG pages, and PDFium pages never wait for it.

js changes nothing on PDF.js and SVG pages, and -=-js on a page or a file brings PDF.js back.

SVG

With svg, a page is drawn as real vector SVG: WebPDF translates PDF.js's drawing operations into SVG in a background worker. The page stays sharp when the browser zooms in or prints, and exports and copies as image/svg+xml. It wins over canvas.

workers on the <script> sets how many SVG pages are built at once, from 1 to 8 (2 by default), and break=svg-worker builds them on the main thread instead.
SVG exports embed their fonts only with fonts on the script.
If the SVG module cannot load, the page is drawn on a canvas and matches :state(svg-fallback).

Switching while you read

On a page with controls, J switches to PDF.js, I to PDFium and V to SVG, and Alt V toggles SVG. The bar's menu has the same choices. From script, set PDFPageElement.canvas and PDFPageElement.svg:

const page = document.querySelector("pdf-page");
page.svg = true;      // SVG
page.svg = false;     // back to the canvas
page.canvas = "ium";  // PDFium, if the file or the script has ium

The page's --re custom property tells you which renderer drew it: "🦊" for PDF.js, "♊" for PDFium and "💎" for SVG.