pdfjs-viewer-element

Standalone, isolated, drop-in 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)
• 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

import '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. | <package-url>/pdf.worker.min.mjs | | 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 resolves worker-src to the worker shipped with this package (pdf.worker.min.mjs in dist).

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/[email protected]/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