npm package: @pdfli/viewer
Description: Fast, lightweight PDF viewer component for React
Author: @romajs
Latest version: 1.3.0

# @pdfli/viewer

Fast, lightweight PDF viewer component for React, powered by [PDF.js](https://mozilla.github.io/pdf.js/).

**[Live demo](https://www.pdfli.co)** · **[Full API docs](https://www.pdfli.co/docs)**

---

## Installation

```bash
npm install @pdfli/viewer
```

## Quick Start

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

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

Or let the user open a file from disk (no `src` needed):

```tsx
<PdfViewer />
```

---

## License Setup

`@pdfli/viewer` requires a license key. Get one at [www.pdfli.co](https://www.pdfli.co).

```tsx
import { PdfViewer, setPdfViewerLicense } from '@pdfli/viewer';
import '@pdfli/viewer/styles';

setPdfViewerLicense(process.env.NEXT_PUBLIC_PDFLI_LICENSE_KEY ?? '');

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

Call `setPdfViewerLicense()` once at app startup (before any `<PdfViewer>` renders). Verification runs entirely offline in the browser via the Web Crypto API.

---

## Props

| Prop           | Type                                                 | Default  | Description                                                                             |
| -------------- | ---------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `src`          | `string`                                             | —        | URL of the PDF to load on mount                                                         |
| `showSidebar`  | `boolean`                                            | `true`   | Show/hide the thumbnail sidebar and its toggle button                                   |
| `showOpen`     | `boolean`                                            | `true`   | Show/hide the Open file button                                                          |
| `showRotate`   | `boolean`                                            | `true`   | Show/hide the Rotate button                                                             |
| `showPrint`    | `boolean`                                            | `true`   | Show/hide the Print button                                                              |
| `showDownload` | `boolean`                                            | `true`   | Show/hide the Download button                                                           |
| `initialPage`  | `number`                                             | `1`      | 1-based page number to scroll to on load                                                |
| `initialScale` | `number`                                             | —        | Initial zoom multiplier (e.g. `1.5` = 150%). Overrides the responsive default when set. |
| `theme`        | `'auto' \| 'dark' \| 'light'`                        | `'dark'` | Color theme. `'auto'` follows the OS `prefers-color-scheme` and updates live.           |
| `onFileOpen`   | `(fileName: string, fileSizeBytes: number) => void`  | —        | Called when the user opens a local file via the toolbar                                 |
| `onDownload`   | `(fileName: string, fileSizeBytes?: number) => void` | —        | Called when the user triggers a download                                                |
| `onPrint`      | `(fileName?: string) => void`                        | —        | Called when the user triggers the print dialog                                          |

---

## Features

- Virtualized page rendering — only visible pages are mounted in the DOM
- Zoom control (25%–500%), fit-to-width, fit-to-page
- Page navigation with direct page-number input
- Rotate, print (native dialog), download
- Collapsible thumbnail sidebar
- Dark / light / auto theme with toolbar toggle and `theme` prop
- Configurable toolbar — show/hide individual buttons via props
- Responsive defaults (fit-to-width on mobile, fit-to-width on desktop)
- Open local files from disk or load remote PDFs via `src`

---

## Framework Examples

### Next.js (App Router)

```tsx
// app/page.tsx
import dynamic from 'next/dynamic';

const PdfViewer = dynamic(() => import('@pdfli/viewer').then((m) => m.PdfViewer), { ssr: false });

export default function Page() {
  return <PdfViewer src="/document.pdf" />;
}
```

### Vite / React

```tsx
import { PdfViewer, setPdfViewerLicense } from '@pdfli/viewer';
import '@pdfli/viewer/styles';

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

export default function App() {
  return <PdfViewer src="/document.pdf" />;
}
```

---

## Exports

```ts
import {
  PdfViewer, // Main viewer component
  setPdfViewerLicense, // Set license key at app startup
  clearLicenseCache, // Clear the 24-hour revalidation cache (useful in tests)
} from '@pdfli/viewer';

import type { PdfViewerProps, FitMode } from '@pdfli/viewer'; // TypeScript types

import '@pdfli/viewer/styles'; // Required CSS
```

---

## Full Documentation

See **[www.pdfli.co/docs](https://www.pdfli.co/docs)** for the complete API reference, troubleshooting, and more examples.

---

## License

MIT