pdfjs-viewer

Standalone, isolated, drop-in PDF viewer web component, based on PDF.js default viewer.

Features

• Standalone isolated web component with no runtime dependencies
• Drop-in, iframe-based PDF.js default viewer for any web app
• Works with same-origin and cross-origin PDF documents
• Configure via attributes (page, zoom, search, pagemode, locale)
• Resource path attributes for PDF.js internals (worker-src, c-map-url, icc-url, standard-font-data-url, wasm-url, and more)
• Built-in worker is enabled by default for stricter CSP compatibility
• Configure PDFViewerApplicationOptions via the setViewerOptions method
• Access to PDFViewerApplication via the initPromise property
• Built-in Paper & Ink default theme, with theme control (automatic/light/dark) and custom CSS injection
• Locale override support using PDF.js viewer locales
• Supports all major browsers and most JS frameworks.

Docs

Getting started

API playground

CodePen demo

CodePen demo with React

CodePen demo with Vue

Usage examples

Install

Using module bundlers:

# With npm
npm install pdfjs-viewer-element
# With pnpm
pnpm add pdfjs-viewer-element

Using browser and CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/pdfjs-viewer-element/dist/pdfjs-viewer-element.js"></script>

Usage

<pdfjs-viewer-element
  src="https://alekswebnet.github.io/sample-pdf-with-images.pdf"
  style="height: 100dvh">
</pdfjs-viewer-element>

The element is block-level and needs an explicit height.

Framework usage

• React integration example
• Vue integration example

Attributes

Attribute	Description	Default
src	PDF file URL.	''
iframe-title	Title for the internal iframe (recommended for accessibility).	PDF viewer window
page	Page number.	''
search	Search query text.	''
phrase	Phrase search mode, set to true to enable phrase matching.	''
zoom	Zoom level (for example auto, page-width, 200%).	''
pagemode	Sidebar mode: thumbs, bookmarks, attachments, layers, none.	none
locale	Viewer UI locale (for example en-US, de, uk). Available locales	''
locale-src-template	Locale file URL template. Must contain {locale} placeholder. Used together with locale.	https://cdn.jsdelivr.net/gh/mozilla-l10n/firefox-l10n@main/{locale}/toolkit/toolkit/pdfviewer/viewer.ftl
viewer-css-theme	Viewer theme: AUTOMATIC, LIGHT, DARK.	AUTOMATIC
worker-src	PDF.js worker URL override.	bundled worker (./build/pdf.worker.mjs in dev, ./pdf.worker.min.mjs in dist)
debugger-src	PDF.js debugger script URL (debuggerSrc option).	./debugger.mjs
c-map-url	CMap directory URL (cMapUrl option).	../web/cmaps/
icc-url	ICC profile directory URL (iccUrl option).	../web/iccs/
image-resources-path	Image resources directory (imageResourcesPath option).	./images/
sandbox-bundle-src	Sandbox bundle URL (sandboxBundleSrc option).	../build/pdf.sandbox.mjs
standard-font-data-url	Standard fonts directory (standardFontDataUrl option).	../web/standard_fonts/
wasm-url	WASM assets directory (wasmUrl option).	../web/wasm/

Play with attributes on API docs page.

Runtime updates

Most attributes can be updated dynamically:

• src updates by calling PDF.js open({ url }) without rebuilding the viewer.
• page, search, phrase, zoom, pagemode update via hash parameters.
• viewer-css-theme updates the viewer theme at runtime.
• worker-src, debugger-src, c-map-url, icc-url, image-resources-path, sandbox-bundle-src, standard-font-data-url, wasm-url update viewer options for subsequent document loads.
• locale rebuilds the viewer so localization resources can be applied.

Worker source

By default, the component uses the bundled worker (same-origin), which is CSP-friendly in strict script-src 'self' environments.

• Dev mode default: ./build/pdf.worker.mjs
• Dist/default package default: ./pdf.worker.min.mjs

Set worker-src only if you want to serve the worker from a custom location (for example your own CDN or static assets path).

• The URL must point to a valid PDF.js module worker file.
• The worker version should match the bundled PDF.js version.

<pdfjs-viewer-element
  src="/file.pdf"
  worker-src="https://cdn.jsdelivr.net/npm/pdfjs-dist@6.2.108/build/pdf.worker.min.mjs">
</pdfjs-viewer-element>

Locale source template

Use locale-src-template when you need to load localization files from a custom host.

• The template must include {locale}.
• {locale} is replaced by the locale attribute value (for example de, uk, en-US).
• If locale is not set, no locale file is loaded.
• Changes to locale-src-template are applied when the viewer is (re)initialized, for example after setting/changing locale.

Example:

<pdfjs-viewer-element
  src="/file.pdf"
  locale="de"
  locale-src-template="https://cdn.example.com/pdfjs-locales/{locale}/viewer.ftl">
</pdfjs-viewer-element>

Viewer CSS theme

The component includes and applies a default Paper & Ink theme from src/themes/paper-and-ink.css.

Use viewer-css-theme attribute to set light or dark theme manually:

<pdfjs-viewer-element 
  src="/file.pdf" 
  viewer-css-theme="DARK">
</pdfjs-viewer-element>

Runtime example:

const viewerElement = document.querySelector('pdfjs-viewer-element')
viewerElement.setAttribute('viewer-css-theme', 'DARK')
viewerElement.setAttribute('viewer-css-theme', 'LIGHT')
viewerElement.setAttribute('viewer-css-theme', 'AUTOMATIC')

PDF.js resource attributes

You can override additional PDF.js viewer resource paths when needed:

<pdfjs-viewer-element
  src="/file.pdf"
  worker-src="/pdf.worker.min.mjs"
  debugger-src="/debugger.mjs"
  c-map-url="/cmaps/"
  icc-url="/iccs/"
  image-resources-path="/images/"
  sandbox-bundle-src="/pdf.sandbox.mjs"
  standard-font-data-url="/standard_fonts/"
  wasm-url="/wasm/">
</pdfjs-viewer-element>

Viewer custom styles

You can add your own CSS rules to the viewer application using injectViewerStyles(styles: string):

<pdfjs-viewer-element id="viewer" src="/file.pdf">
</pdfjs-viewer-element>

const viewerElement = document.querySelector('#viewer')
viewerElement.injectViewerStyles(`
  #toolbarViewerMiddle, #toolbarViewerRight { display: none; }
`)

injectViewerStyles(...) applies styles immediately when the viewer document is ready, and keeps them for future rebuilds.

Methods and properties

injectViewerStyles(styles: string) - Adds custom CSS to the viewer now (when ready) and for future rebuilds.

const viewerElement = document.querySelector('pdfjs-viewer-element')

await viewerElement.injectViewerStyles(`
  #toolbarViewerRight { display: none; }
  #findbar { border-top: 2px solid #0200a8; }
`)

initPromise: Promise<InitializationData> - Resolves after internal viewer is completely loaded and initialized, returning { viewerApp }, that gives a programmatic access to PDF.js viewer app (PDFViewerApplication).

const viewerElement = document.querySelector('pdfjs-viewer-element')
const { viewerApp } = await viewerElement.initPromise

viewerApp.open({ url: '/sample.pdf' })

setViewerOptions(options: Record<string, string | number>): Promise<{ viewerOptions: IframeWindow['PDFViewerApplicationOptions'] }>

Updates PDF.js viewer options at runtime. Call this method with an object of key-value pairs to set options such as resource paths, rendering settings, or other PDFViewerApplicationOptions. Resolves after the viewer is initialized and returns the viewerOptions for testing purpose.

const viewerElement = document.querySelector('pdfjs-viewer-element')
await viewerElement.setViewerOptions({
  enableComment: true,
  enableSignatureEditor: true
})

iframe: PdfjsViewerElementIframe - Public reference to the internal iframe element. Useful when you need direct access to contentWindow/contentDocument.

const viewerElement = document.querySelector('pdfjs-viewer-element')

// Access iframe window directly when needed.
const iframeWindow = viewerElement.iframe.contentWindow

// Read current location hash applied to the viewer.
console.log(iframeWindow.location.hash)

// Inspect iframe document title.
console.log(viewerElement.iframe.contentDocument.title)

You can also react to source changes dynamically:

const viewerElement = document.querySelector('pdfjs-viewer-element')
viewerElement.setAttribute('src', '/another-file.pdf')

Accessibility

Use iframe-title to add a title to the iframe element and improve accessibility.

License

MIT