capacitor-inline-pdf

Native PDF viewer plugin for Capacitor with inline display support

Why This Plugin Exists

"We tried everything. WebView PDF rendering? Janky zoom. PDF.js? Blurry during pinch gestures. Native viewers? They all went fullscreen."

If you've built a mobile app with PDFs, you know the struggle. Users expect the same smooth, responsive PDF experience they get in native apps - buttery smooth pinch-to-zoom, crisp text at any zoom level, and instant response to gestures. Web-based solutions just can't deliver this.

This plugin was born from the frustration of trying to display medical reference PDFs in a healthcare app. We needed:

• Smooth native performance - Medical professionals don't have time for lag
• Inline display - PDFs needed to appear within our app's navigation, not take over the screen
• Reliable zoom - When you're looking at detailed medical algorithms, precision matters
• Text search - Finding critical information quickly can make a real difference

After multiple attempts with web-based renderers and various workarounds (check our git history for the graveyard of attempts 😅), we built what we actually needed: a plugin that embeds native PDF rendering directly in your app's UI.

Features

• 🚀 True Native Performance - Uses PDFKit on iOS for the smooth zoom you expect
• 📱 Inline Display - Shows PDFs within your app layout, respecting your navigation
• 🔍 Search with Highlighting - Find and highlight text with native performance
• 🎯 Precise Zoom Control - Track zoom levels, reset to 100%, no more guessing
• 📄 Smart Page Navigation - Jump between pages with optional animations
• 🎨 Fully Customizable - Position it anywhere, style it your way

Requirements

• Capacitor 6.0+
• iOS 14.0+ (Android implementation welcome - PRs appreciated!)

Install

# Install from GitHub (until published to npm)
npm install https://github.com/ProteanHub/capacitor-inline-pdf.git
npx cap sync

# Or install from npm (coming soon)
# npm install capacitor-inline-pdf
# npx cap sync

Quick Example

Here's how simple it is to add a native PDF viewer to your app:

import { InlinePDF } from 'capacitor-inline-pdf';

// Create the viewer
const { viewerId } = await InlinePDF.create({
  containerId: 'my-pdf-container',
  rect: { x: 0, y: 100, width: 390, height: 600 }
});

// Load your PDF
await InlinePDF.loadPDF({
  viewerId,
  url: 'https://example.com/my-document.pdf'
});

// That's it! Your users can now pinch, zoom, and scroll with native performance

API

• create(...)
• loadPDF(...)
• search(...)
• goToPage(...)
• getState(...)
• updateRect(...)
• resetZoom(...)
• clearHighlights(...)
• destroy(...)
• addListener('gestureStart', ...)
• addListener('gestureEnd', ...)
• addListener('pageChanged', ...)
• addListener('zoomChanged', ...)
• Interfaces

create(...)

create(options: CreateOptions) => Promise<{ viewerId: string; }>

Create a PDF view within a container element

| Param | Type | | ------------- | ------------------------------------------------------- | | options | CreateOptions |

Returns: Promise<{ viewerId: string; }>

loadPDF(...)

loadPDF(options: LoadPDFOptions) => Promise<void>

Load a PDF from URL or file path

| Param | Type | | ------------- | --------------------------------------------------------- | | options | LoadPDFOptions |

search(...)

search(options: SearchOptions) => Promise<{ results: SearchResult[]; }>

Search functionality

| Param | Type | | ------------- | ------------------------------------------------------- | | options | SearchOptions |

Returns: Promise<{ results: SearchResult[]; }>

goToPage(...)

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

Navigate to a specific page

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

getState(...)

getState(options: GetStateOptions) => Promise<PDFState>

Get current state of the PDF viewer

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | GetStateOptions |

Returns: Promise<PDFState>

updateRect(...)

updateRect(options: UpdateRectOptions) => Promise<void>

Update the position and size of the PDF viewer

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | UpdateRectOptions |

resetZoom(...)

resetZoom(options: ResetZoomOptions) => Promise<void>

Reset zoom to 100%

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | ResetZoomOptions |

clearHighlights(...)

clearHighlights(options: ClearHighlightsOptions) => Promise<void>

Clear search highlights

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | ClearHighlightsOptions |

destroy(...)

destroy(options: DestroyOptions) => Promise<void>

Destroy a PDF viewer instance

| Param | Type | | ------------- | --------------------------------------------------------- | | options | DestroyOptions |

addListener('gestureStart', ...)

addListener(event: 'gestureStart', listener: () => void) => Promise<{ remove: () => void; }>

Add event listener for gesture start

| Param | Type | | -------------- | --------------------------- | | event | 'gestureStart' | | listener | () => void |

Returns: Promise<{ remove: () => void; }>

addListener('gestureEnd', ...)

addListener(event: 'gestureEnd', listener: () => void) => Promise<{ remove: () => void; }>

Add event listener for gesture end

| Param | Type | | -------------- | -------------------------- | | event | 'gestureEnd' | | listener | () => void |

Returns: Promise<{ remove: () => void; }>

addListener('pageChanged', ...)

addListener(event: 'pageChanged', listener: (data: { page: number; }) => void) => Promise<{ remove: () => void; }>

Add event listener for page changes

| Param | Type | | -------------- | ------------------------------------------------- | | event | 'pageChanged' | | listener | (data: { page: number; }) => void |

Returns: Promise<{ remove: () => void; }>

addListener('zoomChanged', ...)

addListener(event: 'zoomChanged', listener: (data: { zoom: number; }) => void) => Promise<{ remove: () => void; }>

Add event listener for zoom changes

| Param | Type | | -------------- | ------------------------------------------------- | | event | 'zoomChanged' | | listener | (data: { zoom: number; }) => void |

Returns: Promise<{ remove: () => void; }>

Interfaces

CreateOptions

| Prop | Type | | --------------------- | ----------------------------------------------- | | containerId | string | | rect | Rectangle | | backgroundColor | string | | initialScale | number |

Rectangle

| Prop | Type | | ------------ | ------------------- | | x | number | | y | number | | width | number | | height | number |

LoadPDFOptions

| Prop | Type | | ----------------- | ------------------- | | viewerId | string | | url | string | | path | string | | initialPage | number |

SearchResult

| Prop | Type | | ------------- | ----------------------------------------------- | | page | number | | text | string | | bounds | Rectangle | | context | string |

SearchOptions

| Prop | Type | | ------------------- | -------------------- | | viewerId | string | | query | string | | caseSensitive | boolean | | wholeWords | boolean |

GoToPageOptions

| Prop | Type | | -------------- | -------------------- | | viewerId | string | | page | number | | animated | boolean |

PDFState

| Prop | Type | | ----------------- | -------------------- | | currentPage | number | | totalPages | number | | zoom | number | | isLoading | boolean |

GetStateOptions

| Prop | Type | | -------------- | ------------------- | | viewerId | string |

UpdateRectOptions

| Prop | Type | | -------------- | ----------------------------------------------- | | viewerId | string | | rect | Rectangle |

ResetZoomOptions

| Prop | Type | | -------------- | ------------------- | | viewerId | string |

ClearHighlightsOptions

| Prop | Type | | -------------- | ------------------- | | viewerId | string |

DestroyOptions

| Prop | Type | | -------------- | ------------------- | | viewerId | string |