ngx-extended-pdf-viewer

Bringing PDF to the Angular world

This library provides an embeddable PDF viewer component. It's different from other approaches like ng2-pdf-viewer in that it shows the full suite of UI widgets. In other words, it strongly resembles the PDF viewer of your browser:

What's new in version 12 and 13?

Due to an internal change of pdf.js, I had to modify both the HTML templates and the CSS rules of the dialogs. This may be a breaking change, especially if you've customized the appearance of the viewer, so it's time to increment the major version number. That's why I'm releasing version 13 shortly after publishing version 12.

Starting with version 13, rolling the mouse wheel only zooms the PDF file if the mouse is hovering above the PDF document. Previous versions also zoomed if the mouse was somewhere else. Thanks to GitHub user newq for pointing this out. It's good to be rid of this nuisance!

Since version 12, the viewer stops supporting the full-screen mode in Safari. That probably includes every browser on iPhones and iPads.

Version 12 has a small but breaking change. Actually, it's a fix repairing a nonsense implementation, but I can't rule out you're relying on the bug. Here we go: If you're two-way binding with a form that contains checkboxes that behave like radiobuttons (I know that's a long list of conditions!), previous versions of ngx-extended-pdf-viewer reported simply true or false if one of the checkbox is checked. You couldn't tell which checkbox was checked. Now that's fixed. ngx-extended-pdf-viewer uses the "export value", as intended by the author of the PDF file.

Version 12 also updates to pdf.js 2.13, with one exception: it doesn't include the latest improvements of the find bar yet. The "bleeding edge" version has been updated to pdf.js 2.14, which is the developer version (something like a nightly build).

As of version 12.0.0, I recommend using the stable branch of pdf.js instead of using the bleeding edge branch. The bleeding edge branch is the developer version of pdf.js, so it's not recommended to use it in production, anyways. However, the last few commits caused merge conflicts that may or may not have side effects. Handle with caution. That said, I encourage you to use the bleeding edge version every once in a while in development, because that way you can help me find bugs early. Just keep in mind I've called that branch "bleeding edge" for a reason.

Showcase and manual

There's a showcase at https://pdfviewer.net. Check this page for live demos, source code examples, and a handbook.

There's also a detailed changelog. If you're interested in breaking changes when updating to the latest version, scroll to the end of this page.

Contributors welcome!

Would you like to participate in a popular open source project? It's easy: just open a ticket so we can discuss the change, create a fork, and send me a pull request. Contributions to the showcase are as welcome as contributions to the core library itself.

Features

• Enhanced searching (e.g. fuzzy search, limiting search to a page rage, multiple search terms, finding ignoring diacritics)
• programmatic API for many features, such as searching
• Printing
• Support for forms, including two-way binding
• (Limited) support for signatures (lacking verification of the signature, so use on your own risk!)
• Sidebar with thumbnails, outlines, and attachments (and each of them both optional and customizable)
• Rotating
• Download (including form data) and upload
• Zoom (with optional two-way binding to an attribute)
• Full-screen mode
• Various selection tools
• Standard display or even / odd spreads (like a book)
• Book mode with animated page turn animations
• Single page mode (supporting giant PDF documents of 30000+ pages)
• Infinite scrolling
• Plus several other approaches to scrolling (vertical, horizontal, "wrapped" scrolling)
• A wide range of event listeners
• Internationalization (providing translations to several dozen languages)
• Direct access to the core API of pdf.js (including TypeScript definition files)
• The ability to deactivate (i.e. hide) every button, menu item, and the context menu
• Color theming
• And to customize the toolbars, the side bar, and the menus according to your needs.

Not to mention the ability to display PDF files, running on a customized version of Mozilla's pdf.js 2.13, released in February 2022. If you're the daring one, you can also use the developer version 2.14. It's bleeding edge, so use it at own risk. Basically, the bleeding edge version helps me because I can add Mozilla's latest improvements in frequent, small increments. But every once in a while, it contains a feature you may need, so feel free to use it. I don't encourage using the "bleeding edge" branch in production, but most of the time, the quality is production-ready.

Alternatives

There's also a direct counterpart to my library: ng2-pdfjs-viewer. As far as I can see, it's also a good library. As of May 2021, it's running on PDF.js 2.2.171. It wraps the PDF viewer in an iFrame. That's a more reliable approach, but it also offers fewer options. The list of attributes is shorter, and the PDF viewer can't emit events to your application. If you're not happy with my library, check out ng2-pdfjs-viewer. It's a good library, too. Its unique selling point is displaying multiple PDF files simultaneously on the same page.

You might also try to use the native PDF viewer of your browser. That's a valid approach. It's even the preferred approach. However, ngx-extended-pdf-viewer gives you a wide range of options that aren't available using the native API.

How to use the library

As a rule of thumb, I recommend cloning the showcase project from GitHub before doing anything else. It's a standard Angular CLI application, so you'll get it up and running in less than ten minutes. It's a good starting point to do your own experiments. Maybe even more important: you'll learn if the library works on your machine. (Of course, it does, but it's always good to double-check!)

Currently, the minimum required version is Angular 9. The idea is to support the four most current versions of Angular, which gives you roughly two years to update.

1. run npm add ngx-extended-pdf-viewer and accept all the defaults
2. Now there's an example component, but it isn't part of your application yet. You can either add the example component to your application or copy the relevant line to you HTML template:

<ngx-extended-pdf-viewer [src]="'assets/example.pdf'" useBrowserLocale="true"></ngx-extended-pdf-viewer>

If you're running a non-standard configuration, have a look at the getting-started page" of the showcase.

Configuration, options, and events

See the attribute list on the showcase and the list of default options page. The lists have become too long to put them here: 87 @Input() attributes, 25 event emitters, and 50 default options, give or take a few.

Missing a configuration option? File an issue on the project bug tracker. If your request makes sense to me and if I can implement it in my (limited) leisure time, I'll add it. BTW, you can speed up the process by providing a code snippet telling me how to implement the feature or by submitting a pull request.

Searching programmatically

The service NgxExtendedPdfViewerService offers you a programmatic API for searching, printing, dealing with layers, and scrolling within the page.

Internationalization

Slow default way

If you add the translation files to your project as described above in step 3, the PDF viewer uses the browser language setting to determine which language to load. First, it loads the locale.properties, scans it for the desired language files, and loads the language file from the corresponding folder. That's two additional HTTP calls. That's slow, and it may even lead to errors if the network is already congested loading other resource files.

Don't forget to set the attribute useBrowserLocale="true" if you follow this approach.

Slow way with custom translation files

If you want to use the slow way, but prefer to load the language files from a different URL, add a link to your application like so:

<link rel="resource" type="application/l10n" href="https://www.example.com/locale/locale.properties" />

In this case, don't set useBrowserLocale (or set it explicitly to false).

Inlining (aka embedding) the language files

Alternatively, you can provide the translations as a Json file. This Json file has to be part of an HTML page. That's especially useful if you need only one or two languages, because the are loaded a lot faster. To get familiar with this approach, embed the Json file in the index.html like so:

<script type="application/l10n">
  {"default_locale":"de","locales":{"de": ... }}
</script>

The folder node_modules/ngx-extended-pdf-viewer/assets/inline-locale-files contains snippet files you can simply copy into your HTML page.

Hint: You can also add the language definition in another HTML file. The bottom line is that the HTML snippet is already part of the DOM when the PDF viewer is initialized. Cluttering the root index file with the translations is an ugly and inflexible hack, but it works.

If you're using the "inline" approach, don't set useBrowserLocale (or set it explicitly to false).

Troubleshooting

See https://github.com/stephanrauh/ngx-extended-pdf-viewer/tree/main/projects/ngx-extended-pdf-viewer/troubleshooting.md

Feedback, pull requests and bug reports

Pull requests and bug reports are welcome. Please send them to the bug tracker of the project page: https://github.com/stephanrauh/ngx-extended-pdf-viewer/issues

Building the library from scratch (and updating to the latest version of Mozilla's pdf.js)

Have a look at this walkthrough.

License and Kudos

The license of the ngx-extended-pdf-viewer is the Apache V2 license.

The library is based on https://github.com/mozilla/pdf.js, which has been published under an Apache V2 license.

Some of the default icons have been published under a SIL Open Font License 1.1 license at Material Design Icons. The other icons have either been published under an Apache V2 license by Google or by the pdf.js team at Mozilla.

Thanks to the awesome pdf.js team and all the users who've reported bugs and even sent me pull requests!

Internet Explorer 11 is no longer supported

Reluctantly, I have to drop support for Internet Explorer 11. The base library, Mozilla's pdf.js, now generates binaries that are no longer compatible to Internet Explorer 11, and it seems there's no easy fix. That's a pity because IE11 support was the original use-case of the library and because I frequently get messages from developers who need IE11 support. The last version known to be compatible is 5.3. Version 7.3.2 should be compatible, too, but a user reported crashes.

Changelog

See https://github.com/stephanrauh/ngx-extended-pdf-viewer/tree/main/projects/ngx-extended-pdf-viewer/changelog.md