@capgo/capacitor-pdf-viewer

v8.2.7

Published

2 days ago

Capacitor plugin for opening PDFs inside the app.

0High
0Medium
0Low

riderx

torichancapgo

capacitor pdf pdf-viewer pdfkit document plugin native

@capgo/capacitor-pdf-viewer

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-pdf-viewer in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-pdf-viewer to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

@capgo/capacitor-pdf-viewer embeds native PDF viewing in Capacitor apps on iOS, Android, and web. Instead of fighting WebView limitations or shipping a heavy JavaScript PDF renderer, you open files from a path, HTTPS URL (with custom headers), or base64 and get system-grade rendering: page navigation, pinch zoom, continuous or single-page scrolling, password-protected documents, fullscreen or inline layout, and events for load, errors, page changes, link taps, and close. On iOS it uses PDFKit; on Android it uses Pdfium; on web it uses the browser PDF viewer with blob URLs.

Features

Open PDFs from a device path, file:// URL, HTTPS URL, or base64 (including data: URIs)
Optional headers when downloading remote URLs (auth tokens, cookies)
Password support for encrypted PDFs on iOS and Android
Fullscreen overlay or inline mode anchored to a DOM element (elementId)
Continuous vertical scrolling or single-page mode
Programmatic goToPage, setZoom, and close
Events: load, pageChange, error, close, linkTap

Use cases

Invoices, manuals, and tickets stored on device or returned from your API as base64
Authenticated document download from a signed URL with custom HTTP headers
Embedded PDF preview in a form or dashboard region (inline mode)
Guided reading flows that jump to a page and listen for link taps inside the PDF

Documentation

Plugin docs on capgo.app
Tutorial with install steps and examples
Capgo for live updates, native builds, and plugin support

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | On demand |

Policy:

New plugins start at version 8.0.0 (Capacitor 8 baseline).
Backward compatibility for older Capacitor majors is supported on demand.

Install

npm i @capgo/capacitor-pdf-viewer
npx cap sync

With Bun:

bun add @capgo/capacitor-pdf-viewer
bunx cap sync

iOS setup

No extra Info.plist keys or entitlements are required by this plugin. It uses Apple PDFKit. Remote PDFs use URLSession with the headers you pass in open. For HTTPS URLs, follow your app's usual App Transport Security rules.

Android setup

The plugin library targets minSdk 24 (Android 7.0) and bundles Pdfium (io.legere:pdfiumandroid). The plugin AndroidManifest.xml is empty: it does not declare INTERNET, storage, or FileProvider entries. If you open https sources, add INTERNET to your app manifest:

<uses-permission android:name="android.permission.INTERNET" />

Local files and base64 do not need extra permissions beyond what your app already uses to read those paths.

Web

No Capacitor sync steps are required for web. URL sources are fetched with your headers; setZoom is a no-op because zoom is controlled by the browser viewer. Passwords cannot be injected on web; the browser may prompt on its own.

Usage

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

await PdfViewer.addListener('pageChange', ({ page, pageCount }) => {
  console.log(`Page ${page} of ${pageCount}`);
});

const { pageCount, page } = await PdfViewer.open({
  source: 'https://example.com/manual.pdf',
  headers: { Authorization: 'Bearer YOUR_TOKEN' },
  mode: 'fullscreen',
  scrollMode: 'continuous',
  page: 1,
});

await PdfViewer.goToPage({ page: 2 });
await PdfViewer.setZoom({ scale: 1.25 });
await PdfViewer.close();

Inline preview in a div:

await PdfViewer.open({
  source: base64FromYourApi,
  sourceType: 'base64',
  mode: 'inline',
  elementId: 'pdf-host',
});

Password-protected file (iOS and Android):

await PdfViewer.open({
  source: '/path/on/device/encrypted.pdf',
  sourceType: 'path',
  password: 'secret',
});

On native shells, loading a PDF from the WebView origin URL often fails because that origin is not a real file server. Fetch the bytes in JavaScript and pass sourceType: 'base64' instead (see example-app/).

API

Native PDF viewer for Capacitor (PDFKit on iOS, Pdfium on Android, browser viewer on web).

open(...)

open(options: OpenPdfOptions) => Promise<OpenPdfResult>

Open a PDF from a file, path, URL, or base64 source.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | OpenPdfOptions |

Returns: Promise<OpenPdfResult>

Since: 8.0.0

close()

close() => Promise<void>

Close the active viewer and remove any overlay.

Since: 8.0.0

goToPage(...)

goToPage(options: GoToPageOptions) => Promise<void>

Jump to a 1-based page number in the open document.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | GoToPageOptions |

Since: 8.0.0

setZoom(...)

setZoom(options: SetZoomOptions) => Promise<void>

Set the zoom scale multiplier (1 is the default fit scale on native). On web this resolves without changing the browser viewer zoom.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | SetZoomOptions |

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Get the native or web implementation version marker.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

addListener('load', ...)

addListener(eventName: 'load', listenerFunc: (event: PdfLoadEvent) => void) => Promise<PluginListenerHandle>

Listen for successful PDF load.

| Param | Type | | ------------------ | ------------------------------------------------------------------------- | | eventName | 'load' | | listenerFunc | (event: PdfLoadEvent) => void |