New Programs Makers

    ngx-extended-pdf-viewer
    TypeScript icon, indicating that this package has built-in type declarations

    15.0.11 • Public • Published

    ngx-extended-pdf-viewer

    downloads npm version

    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 15?

    Version 15 updates to pdf.js 2.16 (default branch) and pdf.js 3.0 (bleeding edge branch). It also plays nicely with other libraries which are using the AMD module system, and it supports documents a wider range of documents using East-Asian fonts than previous versions. Plus, it ships with a couple of bug fixes.

    What's new in version 14.5?

    Version 14.5 replaces the way the PDF viewer injects it global CSS rules. Until version 14.0.x, most CSS rules were injected using a regular component with ViewEncapsulation.None. However, it turned out that this CSS code is never removed. In rare cases, the remaining CSS rules cause problems. Printing, in particular, was broken because of a global @page setting. Version 14.5.0 fixes this. I've increased the version number to indicate there a tiny probability it's a breaking change - but I don't think it is one.

    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

    Even I have to admit my pet project doesn't match every requirement. There are several alternatives out there. Feel free to expand the description to learn what other developers have in store for you:

    Expand to learn more about the other options to display PDF files in Angular If you only need the base functionality, I'll happily pass you to the project of Vadym Yatsyuk. Vadym does a great job delivering a no-nonsense PDF viewer. However, if you need something that can easily pass as the native viewer on a gloomy day, ngx-extended-pdf-viewer is your friend.

    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 whether 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 12. The idea is to support the four most current versions of Angular, which gives you roughly two years to update. However, supporting so many version isn't always possible.

    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

    Expand to learn how to translate ngx-extended-pdf-viewer to 120+ languages

    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

    Install

    npm i ngx-extended-pdf-viewer

    DownloadsWeekly Downloads

    38,993

    Version

    15.0.11

    License

    Apache-2.0

    Unpacked Size

    49.3 MB

    Total Files

    1149

    Last publish

    Collaborators

    • beyondjava