How PDF.js Works
In this article, we walk you through how PDF.js works to render PDFs, what technologies it uses, and implications for projects using PDF.js.
12 May 2020
PDF.js is used within Mozilla Firefox today as the built-in PDF viewer, and it works well within a website when viewed using the latest versions of Chrome and Firefox, whether through the pre-built PDF.js viewer UI or a custom commercial UI such as PDF.js Express.
But organizations who embed PDF.js within a cross-browser solution, or those whose users are restricted to work on a specific browser, may want to assess PDF.js behavior in terms of performance, reliability, and rendering accuracy on other browsers before starting projects to embed it in a website or an application.
In this blog, we detail what browsers support PDF.js, where PDF.js is less supported, and the potential implications for a project using PDF.js.
<canvas> element used to render PDFs in PDF.js.
Not all browsers support all these features -- with implications for projects today.
“The objective is to support all HTML5 compliant browsers, but since feature support varies per browser/version our support for all PDF features varies as well.”
~PDF.js, FAQ response
A lot of work has been done by the open-source contributor community to ensure cross-browser compatibility. The pre-built version of PDF.js includes a compatibility mode (via
compatability.js) that will attempt to emulate missing features, such as dashed lines in Safari v.6.0.
On browsers where PDF.js must emulate missing features, such as IE9/10, however, you can expect slower performance and increased risk of crashing or freezing the viewer due to memory issues -- especially with any large/complex documents.
Today, PDF.js has the best performance, reliability, and accuracy on the latest versions of Firefox and Chrome. These browsers receive the most contributor attention and automated testing to proactively catch and squash bugs such as regressions due to a vendor update.
The open-source community, however, states in the FAQ that it cannot deliver the same level of support for all browsers. This is largely due to the missing features on certain browsers that would be too resource-intensive for contributors to add.
|IE 10 and below||No||None|
|Safari 8 and below||No||None|
|Android 4 and below||No||None|
What all this means for a project is that Mozilla Firefox will offer the best experience. Chrome will offer the next best.
Whereas on Edge and Safari, one faces greater uncertainty and exposure to possible crashes and rendering issues. And on browsers such as IE9/10 and older mobile browsers, you face the greatest exposure.
“…the default viewer should still work in IE 11/Edge (non-Chromium-based) for the time being, some functionality/features may not be available and the performance will be worse compared to modern browsers.”
~PDF.js FAQ response
Issues often arise after updates to PDF.js or the browser, which can regress behavior due to an upstream browser bug that can be impossible for the community to resolve.
Should you encounter an issue, you will have to wait on the PDF.js contributor community to respond and fix the issue, before manually updating PDF.js. Should you encounter an issue on IE9/10, however, or should the issue stem from an upstream bug, you will not be able to rely on the open-source community for help.
Instead, you will have to wait on the browser vendor -- or, in some cases, fix the issue yourself if it involves PDF.js. However, this will require familiarity with the PDF.js code base, which, in turn, assumes an understanding of a PDF specification over 1,000 pages long.
The specific bugs you may encounter will be difficult to predict, as they vary with the documents loaded, the specific document features used, any PDF.js customizations, the browser in question and its support for PDF.js’s required features, and so on.
However, a few examples of undesired behavior include…
There are a few measures you can take to try to measure your level of exposure to browser-specific issues in PDF.js.
Mozilla offers this URL that will allow you to see instantly what required PDF.js features a browser supports, the level of severity should one not be supported, and whether PDF.js can emulate missing features.
One can also try testing documents on the prebuilt PDF.js viewer demo within the browsers your users expect to work in, with a representative sample capturing the variety of documents you expect them to open.
However, even with these tests, it will be difficult to estimate your full level of exposure, as custom projects and browser vendor patches are known to introduce their own problems.
If your users work on older browsers, you may ultimately wish for the support of professional developers experienced with PDF to help troubleshoot and resolve any issues quickly.
Should you require consistent rendering, performance, and reliability across all browsers or on a specific browser -- as well as commercial backing to help fix new issues on the fly -- then you may wish to consider such PDF.js alternatives as a professional commercial PDF SDK like PDFTron.