Skip to content

pdf-viewer

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

pdf-viewer

README.md

Capacitor PDF Viewer Plugin

Capacitor plugin to display PDF documents in a fullscreen native viewer.

Features

  • 📄 Fullscreen Viewer: Display PDF documents in a fullscreen native viewer with a toolbar.
  • 📖 Paging: Scroll through pages and jump to an initial page.
  • 🔍 Zoom: Pinch to zoom in and out.
  • 🔑 Password Protection: Open password-protected PDF documents.
  • 🔔 Events: Listen for page changes and the closing of the viewer.
  • 🔒 App Store safe: Uses only official platform APIs.
  • 🤝 Compatibility: Works alongside the File Opener and File Picker plugins.
  • 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
  • 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The PDF Viewer plugin is typically used whenever an app needs to present a PDF document to the user, for example:

  • Invoices and receipts: Display invoices or receipts that your app has generated or downloaded.
  • Reports and manuals: Let users read reports, product manuals, or other multi-page documents with paging and zoom.
  • Confidential documents: Open password-protected PDF documents such as payslips or bank statements.
  • Reading progress: Use the pageChange event to remember the last read page and reopen the document there via the page option.

Compatibility

Plugin Version Capacitor Version Status
0.x.x >=8.x.x Active support

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-pdf-viewer` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-pdf-viewer
npx cap sync

Android

On Android, this plugin uses the android-pdf-viewer library, which renders PDF documents with Pdfium. Be aware that the library bundles the Pdfium native libraries, which add about 10 to 16 MB (uncompressed, across all ABIs) to your app. If you publish your app as an Android App Bundle, each device only downloads the native libraries for its own ABI, which significantly reduces the download size. Also note that the viewer does not support text selection on Android.

Share Button

If you use the share button (see the showShareButton option), you need to specify the directories that contain the PDF files you want to share. To do this, create a new file named file_paths.xml in the res/xml directory of your Android project (e.g. android/app/src/main/res/xml/file_paths.xml). Here is an example of the content of the file:

<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
    <files-path name="files" path="." />
    <cache-path name="cache" path="." />
    <external-files-path name="external-files" path="." />
    <external-cache-path name="external-cache" path="." />
    <external-path name="external" path="." />
</paths>

More information can be found in the Android documentation.

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

  • $androidPdfViewerVersion version of io.github.oothp:android-pdf-viewer (default: 3.2.0-beta06)

iOS

On iOS, this plugin uses the PDFKit framework. No additional configuration is required.

Web

This plugin is not available on the web. Browsers ship with a built-in PDF viewer, so you can simply render a PDF document using an <iframe> or <object> element.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to open a PDF document, unlock a password-protected file, close the viewer, and listen for page changes and the viewer being closed.

The plugin only supports local files. Remote URLs must be downloaded first, for example with the downloadFile(...) method of the Filesystem plugin.

Open a PDF document

Open a local PDF file in a fullscreen native viewer. You can set a custom toolbar title and the page to display initially. Only available on Android and iOS:

import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const open = async () => {
  await PdfViewer.open({
    path: 'file:///path/to/document.pdf',
    title: 'Invoice',
    page: 1,
  });
};

Open a password-protected PDF document

Use the password option to unlock a password-protected PDF file:

import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const openWithPassword = async () => {
  await PdfViewer.open({
    path: 'file:///path/to/document.pdf',
    password: 'secret',
  });
};

Close the viewer

Close the currently open viewer from code. If no viewer is open, this method does nothing:

import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const close = async () => {
  await PdfViewer.close();
};

Listen for page changes and the viewer being closed

Use the pageChange and closed events to react to the user scrolling through the document or closing the viewer:

import { PdfViewer } from '@capawesome/capacitor-pdf-viewer';

const addListeners = async () => {
  await PdfViewer.addListener('closed', () => {
    console.log('Viewer closed');
  });
  await PdfViewer.addListener('pageChange', event => {
    console.log('Current page:', event.page);
  });
};

API

close()

close() => Promise<void>

Close the currently open viewer.

If no viewer is open, this method does nothing.

Only available on Android and iOS.

Since: 0.1.0

open(...)

open(options: OpenOptions) => Promise<void>

Open a PDF file in a fullscreen native viewer.

If a viewer is already open, it is closed before the new one is presented.

Only available on Android and iOS.

Param Type
options OpenOptions

Since: 0.1.0

addListener('closed', ...)

addListener(eventName: 'closed', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the viewer is closed.

Only available on Android and iOS.

Param Type
eventName 'closed'
listenerFunc () => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

addListener('pageChange', ...)

addListener(eventName: 'pageChange', listenerFunc: (event: PageChangeEvent) => void) => Promise<PluginListenerHandle>

Called when the current page of the viewer changes.

Only available on Android and iOS.

Param Type
eventName 'pageChange'
listenerFunc (event: PageChangeEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.1.0

Interfaces

OpenOptions

Prop Type Description Default Since
page number The page (1-based) to display initially. 1 0.1.0
password string The password to unlock the PDF file if it is password-protected. 0.1.0
path string The path of the local PDF file to display. Remote URLs are not supported. Download the file first, for example to the cache directory, and pass the local file path to this method. 0.1.0
showShareButton boolean Whether to display a share button in the toolbar of the viewer. Only available on Android and iOS. false 0.1.2
title string The title to display in the toolbar of the viewer. The file name of the PDF file. 0.1.0

PluginListenerHandle

Prop Type
remove () => Promise<void>

PageChangeEvent

Prop Type Description Since
page number The page (1-based) that is currently displayed. 0.1.0

FAQ

How is this plugin different from other similar plugins?

It displays PDF documents in a fullscreen native viewer with a toolbar, paging, pinch-to-zoom, and support for password-protected files, backed by PDFKit on iOS and Pdfium on Android for a genuinely native reading experience. Page-change and closed events let you track reading progress and reopen a document where the user left off, all through a fully typed API that uses only official platform APIs. Actively maintained against the latest Capacitor version, it also pairs naturally with the PDF Generator and File Picker plugins.

Can I display a PDF from a remote URL?

No, the plugin only supports local files. Download the file first, for example with the downloadFile(...) method of the official Filesystem plugin, and then pass the local file path to the open(...) method.

Why is the plugin not available on the Web?

Browsers ship with a built-in PDF viewer, so a plugin is not needed there. On the Web, you can simply render a PDF document using an <iframe> or <object> element.

How do I open a password-protected PDF document?

Pass the password using the password option of the open(...) method. The viewer then unlocks and displays the document. See Open a password-protected PDF document for an example.

How much does the plugin add to my Android app size?

On Android, the plugin uses the android-pdf-viewer library, which bundles the Pdfium native libraries. These add about 10 to 16 MB (uncompressed, across all ABIs) to your app. If you publish your app as an Android App Bundle, each device only downloads the native libraries for its own ABI, which significantly reduces the download size.

Can I select text in the viewer on Android?

No, the viewer does not support text selection on Android. On iOS, the plugin uses the PDFKit framework, which provides the native viewer experience of the platform.

Why does the share button not work on Android?

The share button is hidden by default. Enable it by setting the showShareButton option to true. On Android, the file is then shared using a FileProvider. Make sure that the directory containing the PDF file is declared in the file_paths.xml file of your Android project, as described in the Installation section. Without this configuration, the file can not be shared.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

  • File Opener: Open a file with the default application instead of an in-app viewer.
  • File Picker: Let the user select a PDF file from the device's file system.
  • PDF Generator: Generate paginated PDF files from HTML content or URLs.
  • Printer: Print PDF documents on Android and iOS.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.