pdflipdfli
On this page

@pdfli/viewer

A fast, embeddable PDF viewer component for React. Runs fully in the browser — no server required.

Installation

npm install @pdfli/viewer

Peer dependencies: react ≥ 18 and react-dom ≥ 18.

Import the bundled stylesheet once, at the top level of your app:

import '@pdfli/viewer/styles';

Quick start

import { PdfViewer } from '@pdfli/viewer';
import '@pdfli/viewer/styles';

export default function App() {
  return <PdfViewer src="https://example.com/file.pdf" />;
}

Omit src to start with an empty viewer — the user can open a file or paste a URL from the toolbar.

License setup

Call setPdfViewerLicense once before any <PdfViewer> renders. Without a valid license the viewer still works but logs a warning to the console and a banner may appear.

Obtain a signed license token from pdfli.co and store it in an environment variable.

// Next.js — call from a Client Component in your root layout
'use client';

import { setPdfViewerLicense } from '@pdfli/viewer';

setPdfViewerLicense(process.env.NEXT_PUBLIC_PDFLI_LICENSE_KEY ?? '');
# .env.local
NEXT_PUBLIC_PDFLI_LICENSE_KEY=<your license JWT>

Verification runs entirely offline using the Web Crypto API — no network request is made on every render. A background revalidation call is made at most once every 24 hours.

PdfViewer props

PropTypeDefaultDescription
srcstring—URL of the PDF to load on mount. Omit to start empty; the user can open a file via the toolbar.
showSidebarbooleantrueShow the thumbnail sidebar and its toggle button.
showOpenbooleantrueShow the file-open / URL button in the toolbar.
showRotatebooleantrueShow the rotate button in the toolbar.
showPrintbooleantrueShow the print button in the toolbar.
showDownloadbooleantrueShow the download button in the toolbar.
initialPagenumber11-based page number to open on load.
initialScalenumber—Initial zoom multiplier (e.g. 1.5 = 150%). Overrides the default mobile/desktop zoom.
onFileOpen(fileName: string, fileSizeBytes: number) => void—Fired when the user opens a local file via the toolbar.
onDownload(fileName: string, fileSizeBytes?: number) => void—Fired when the user triggers a download.
onPrint(fileName?: string) => void—Fired when the user triggers the print dialog.
theme'auto' | 'dark' | 'light''dark'Color theme. 'dark' and 'light' are static; 'auto' follows the OS preference and updates live.

All exports

ExportKindDescription
PdfViewercomponentThe main PDF viewer React component.
PdfViewerPropstypeTypeScript props interface for PdfViewer.
setPdfViewerLicense(key)functionSets the global license key. Call once before any PdfViewer renders.
clearLicenseCache()functionClears the 24-hour online-revalidation cache from localStorage. Useful in tests.
FitModetype'custom' | 'fit-width' | 'fit-page'

Examples

Full working starter projects examples. Inline snippets below show the key integration points.

Next.js App Router

// app/layout.tsx
import { LicenseInit } from './LicenseInit';
import '@pdfli/viewer/styles';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <LicenseInit />
        {children}
      </body>
    </html>
  );
}

// app/LicenseInit.tsx
'use client';
import { setPdfViewerLicense } from '@pdfli/viewer';
setPdfViewerLicense(process.env.NEXT_PUBLIC_PDFLI_LICENSE_KEY ?? '');
export function LicenseInit() { return null; }

Vite / CRA

// main.tsx
import { setPdfViewerLicense } from '@pdfli/viewer';
import '@pdfli/viewer/styles';

setPdfViewerLicense(import.meta.env.VITE_PDFLI_LICENSE_KEY ?? '');

// App.tsx
import { PdfViewer } from '@pdfli/viewer';

export default function App() {
  return (
    <PdfViewer
      src="https://example.com/file.pdf"
      showSidebar={false}
    />
  );
}

See the full runnable project in examples/vite-react.

Minimal embed (no toolbar buttons)

<PdfViewer
  src="/report.pdf"
  showSidebar={false}
  showOpen={false}
  showRotate={false}
  showPrint={false}
  showDownload={false}
/>

Live playground

Adjust props below to see the viewer update in real time, then copy the generated snippet into your project.

Generated code

<PdfViewer
  src="https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf"
/>

Troubleshooting

"Invalid or missing license key" warning in console

Call setPdfViewerLicense() with a valid JWT before any <PdfViewer> renders. Check that your NEXT_PUBLIC_PDFLI_LICENSE_KEY env var is set and non-empty.

License shows "unavailable"

crypto.subtle requires a secure context — HTTPS or localhost. Serving over plain http:// in production will disable offline verification. Always deploy behind HTTPS.

License shows "domain" error

The token was issued for a different hostname. Issue a new token with --domain <your-hostname> or contact pdfli.co to update your license.

License shows "expired"

Re-issue a new token and update the NEXT_PUBLIC_PDFLI_LICENSE_KEY env var before redeploying.

PDF does not render in production

Ensure the PDF URL is reachable from the browser and that the server sends appropriate CORS headers. For local files, use the toolbar Open button — the src prop only accepts URLs.