genus-pdf-viewer

Framework-agnostic PDF viewer built on pdfjs-dist with a custom element and a small TypeScript API.

Highlights

• Single-row toolbar with horizontal overflow when space is tight
• Continuous-scroll document mode for reader-style PDFs
• Canvas-based rendering with packaged download controls
• Works as either a custom element or a JS API mount

Install

npm install genus-pdf-viewer

The package ships pdf.worker.bootstrap.mjs and pdf.worker.min.mjs. Unbundled package usage resolves the worker beside the built package; bundled app usage resolves assets/pdf.worker.bootstrap.mjs, so host apps should copy both worker files into their deployed assets.

Breaking Change

0.2.0 replaces the older Angular-specific 0.1.x package with a framework-agnostic runtime. If you still need the Angular library API from npm, stay on 0.1.13 or earlier.

TypeScript Usage

import { createGenusPdfViewer } from "genus-pdf-viewer";

const root = document.getElementById("pdf-root");

if (root) {
  const viewer = createGenusPdfViewer(root, {
    src: "https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf",
    fit: "width",
    continuous: true,
    showToolbar: true,
    zoomStep: 0.15,
  });

  viewer.addEventListener("genus-ready", (event) => {
    console.log("ready", event.detail.pageCount);
  });
}

Custom Element

Register the element yourself when you want to use declarative markup without first calling createGenusPdfViewer().

import { defineGenusPdfViewerElement } from "genus-pdf-viewer";

defineGenusPdfViewerElement();

<genus-pdf-viewer
  src="https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf"
  proxy-url="/api/pdf-proxy"
  page="1"
  zoom="1"
  fit="width"
  continuous="true"
  toolbar="true"
  download="true"
></genus-pdf-viewer>

API

createGenusPdfViewer(container, config) appends and returns a GenusPdfViewerElement.

Config fields:

• src: string | URL | Uint8Array | Blob
• title?: custom download filename
• page?, zoom?, minZoom?, maxZoom?, zoomStep?
• fit?: "width" | "page" | "none"
• continuous?, showToolbar?, allowDownload?
• workerSrc?: override the default worker URL
• proxyUrl?: route cross-origin URL PDFs through your own same-origin proxy endpoint If omitted, the viewer first tries "/__proxy" for cross-origin URL sources and falls back to the direct URL if that route is unavailable. Set proxyUrl: false if you want to skip the proxy attempt.
• withCredentials?, httpHeaders?: network request options for URL sources

Element methods:

• configure(config)
• reload()
• goToPage(page)
• nextPage()
• prevPage()
• setZoom(zoom)
• zoomIn()
• zoomOut()
• download()
• destroy()

Events

The viewer emits bubbling custom events:

• genus-ready
• genus-pagechange
• genus-zoomchange
• genus-error

Package Exports

• genus-pdf-viewer: main TypeScript and custom-element API
• genus-pdf-viewer/pdf.worker.bootstrap.mjs: optional bootstrap worker asset for strict CSP deployments
• genus-pdf-viewer/pdf.worker.min.mjs: optional worker asset if you need to host it yourself
• genus-pdf-viewer/styles.css: packaged stylesheet export

Angular / Vite Setup

The default setup is npm-install-only. The viewer creates a self-contained Blob worker URL for pdf.js, so Angular, Vite, Amplify, and other static hosts do not need to copy pdf.worker*.mjs into /assets.

import { createGenusPdfViewer } from "genus-pdf-viewer";

const host = document.getElementById("pdf-root");

if (host) {
  createGenusPdfViewer(host, {
    src: pdfUrl,
    fit: "width",
    continuous: true,
    showToolbar: true,
    zoomStep: 0.15,
  });
}

If your app has a strict Content Security Policy that blocks blob: workers, copy the package worker assets into your app assets folder and pass workerSrc explicitly.

{
  "glob": "pdf.worker*.mjs",
  "input": "node_modules/genus-pdf-viewer/dist",
  "output": "/assets"
}

import { createGenusPdfViewer } from "genus-pdf-viewer";

const host = document.getElementById("pdf-root");

if (host) {
  createGenusPdfViewer(host, {
    src: pdfUrl,
    fit: "width",
    continuous: true,
    showToolbar: true,
    zoomStep: 0.15,
    workerSrc: "/assets/pdf.worker.bootstrap.mjs",
  });
}

If a remote PDF URL loads in the browser but fails inside the viewer with a CORS-style error, the PDF host is blocking fetch access for your app origin. This package cannot bypass that browser restriction. Fix it by either:

• allowing your app origin in the PDF host's CORS policy
• fetching the PDF in your app/backend and passing a Blob or Uint8Array to the viewer instead of the remote URL
• routing the request through your own same-origin proxy and passing proxyUrl

createGenusPdfViewer(host, {
  src: pdfUrl,
  fit: "width",
  continuous: true,
  proxyUrl: "/api/pdf-proxy",
});

Demo

npm run build
npm run demo:serve

Open http://127.0.0.1:4175/examples/.

Validate

npm run typecheck
npm run test
npm run build
npm pack --dry-run

Publish

This repo is configured to publish the npm package genus-pdf-viewer.

npm publish