How to Build a Cordova PDF Viewer with PDF.js
In this article (a six-minute read), you’ll learn how to quickly build a PDF viewer with Cordova and PDF.js, a popular open-source PDF viewer.
1 May 2020
In this article (a five-minute read), you’ll learn about two simple (and free!) approaches to displaying PDFs in the browser and how you can quickly implement them in your website.
Since PDF is such a widely used format, all modern browsers have built-in PDF support. We can take advantage of this by using HTML elements to embed a PDF directly in our web page, like this:
Here’s the code:
<html> <head> <title>PDF Viewer</title> </head> <body> <!-- Place the following <div> element where you want the PDF to be displayed in your website. You can change the size using the width and height attributes. --> <div> <object data='https://pdfjs-express.s3-us-west-2.amazonaws.com/docs/choosing-a-pdf-viewer.pdf' type="application/pdf" width="500" height="678" > <iframe src='https://pdfjs-express.s3-us-west-2.amazonaws.com/docs/choosing-a-pdf-viewer.pdf' width="500" height="678" > <p>This browser does not support PDF!</p> </iframe> </object> </div> </body> </html>
I’ve used a URL for the
src values. These point to the PDF I want to open from a URL. But I could instead open a local file by swapping out the URL for a file path (e.g.
The PDF viewer’s user interface will look a bit different depending on your browser:
|PDF Viewer Embedded in Website in Chrome||PDF Viewer Embedded in Website in Safari|
|PDF Viewer Embedded in Website in FireFox||PDF Viewer Embedded in Website in Edge|
This approach will work in all modern desktop and mobile versions of Chrome, Safari, Firefox, and Edge. (It will not work in Internet Explorer.) If you need to support Internet Explorer or customize the user interface, you should consider the next approach -- PDF.js rendering.
The benefits of PDF.js rendering compared to native browser rendering are:
Here's what we'll build:
To add this PDF.js viewer to our website, we will follow three simple steps.
The easiest way to download PDF.js is to visit the official PDF.js project page on GitHub.
After downloading PDF.js, we’ll extract the contents from the downloaded
.zip. You can see here it contains two folders and a
We’ll move these files into the folder that contains your website files. For the purposes of this tutorial, I’m going to put them in my website’s root directory (which just means the first or top-most directory).
You can see here that I’ve got a home page
assets folder where I keep images and CSS files, a
products folder, as well as a couple PDF files. I’ve also added our two PDF.js folders
web, as well as the
It’s important to understand that PDF.js will not work locally from your computer. It will only work from a server due to browser security restrictions.
Our last step will be to embed the viewer in our About Us page by using an
<iframe>. Here’s the full code for our new
<html> <head> <title>About Us</title> </head> <body style="font-family: Arial, Helvetica, sans-serif;"> <div style="width:760px;"> <h2>About Us</h2> <p>We help software developers do more with PDFs. PDF.js Express gives a flexible and modern UI to your PDF.js viewer while also adding out-of-the-box features like annotations, form filling and signatures.</p> <!-- Place the following <div> element where you want the PDF to be displayed in your website. You can adjust the size using the width and height attributes. --> <div> <iframe id="pdf-js-viewer" src="/web/viewer.html?file=%2Fmy-pdf-file.pdf" title="webviewer" frameborder="0" width="500" height="600"></iframe> </div> </div> </body> </html>
Since PDF.js will not work locally from our computer, we’ll upload all new or updated files to our website server.
Our PDF.js viewer will now be embedded in our About Us HTML page and will display
my-pdf-file.pdf. The UI will look the same across all browsers and will work in Internet Explorer.
In the above
<iframe> code, our
src="/web/viewer.html?file=%2Fmy-pdf-file.pdf" attribute points to the PDF.js viewer as well as the PDF file that is being opened.
/web/viewer.html part is the location for our PDF.js viewer, which is located in our
/web folder. If we wanted to place our PDF.js folders in a different location, we just need to change
/web/viewer.html to the new path.
?file=%2Fmy-pdf-file.pdf part is the location of our PDF file, which is located in our root directory. The
? tells our viewer that everything to the right is a query string, which is the
file we want to open. The
%2F part is HTML URL encoding for the
/ symbol, which in this case means the root directory.
If we wanted to open a different PDF, such as
my-other-pdf-file.pdf in our root directory, we just need to update our
<iframe> as follows:
<iframe id="pdf-js-viewer" src="/web/viewer.html?file=%2Fmy-other-pdf-file.pdf" title="webviewer" frameborder="0" width="500" height="600"></iframe>
If we wanted to open a
widget.pdf file located in our
/products folder, we’d use this
<iframe id="pdf-js-viewer" src="/web/viewer.html?file=%2Fproducts%2Fwidget.pdf" title="webviewer" frameborder="0" width="500" height="600"></iframe>
We can also use the above
<iframe> code to embed our PDF viewer in a
/products/list.html page. Even though the
list.html file is located in the
/products folder, no changes would be needed because we are using “absolute” paths in our
<iframe>. (An absolute path always begins with a
/.) Using absolute paths means that the
src will always point to the root directory -- regardless of the page's location in the website structure.
Note that due to browser security settings, it’s difficult to get PDF.js to open PDF files that are located on a different domain name. You can read more about this here.
In addition to embedding the PDF viewer in a web page, we can also link directly to a full screen version and have it open any PDF hosted on the domain name. Try it here:
Here’s the link code:
<a href="/web/viewer.html?file=%2Fmy-pdf-file.pdf">Open PDF.js Viewer</a>
To open a different PDF in the viewer, you can simply replace the
%2Fmy-pdf-file.pdf path and filename with the path to your file. For example, the following link will open
<a href="/web/viewer.html?file=%2Fmy-other-pdf-file.pdf">Open PDF.js Viewer</a>
Here are two of the most common errors when implementing PDF.js, along with their solutions.
This error is generated when the PDF.js viewer can’t find the PDF file. The most common causes for this are:
The PDF.js viewer is not located on a server. Solution: PDF.js can only work when it’s located on a server. (It will not work locally from your computer, unless you have configured it to run as a server.) The simplest solution is to upload the files to a web server and try opening from its URL.
The path or PDF filename is incorrect. Solution: Double check the path located in the viewer URL (the
?file=%2Fwidget.pdf part). Note that
/, which is the root directory for the website. If you remove the
%2F, the viewer will look for the file relative to the
/web/viewer.html file location. For example,
?file=widget.pdf would try to open the
The PDF filename or its path contains spaces or characters that confuse the browser. Solution: Convert the filename or path to URL encoding.
The PDF is located on a different domain name from the PDF.js viewer. Solution: Unfortunately, PDF.js cannot easily be configured to open PDFs from a different URL, due to browser security restrictions. You can read more about this here.
The 204 response means that the file was empty and didn’t return any content. If you’re sure the PDF contains information, then a common cause is that a download manager installed in your computer is intercepting a PDF request and downloading it directly instead of displaying inside the viewer. The solution is to disable the download manager or configure it to not intercept PDF downloads.
We hope this was helpful! You can also have a look at PDF.js Express, which wraps a modern React UI around the PDF.js rendering engine to enable PDF annotation, form filling, and signing inside your web app.