pdf-live
v1.0.20
Published
A drop-in PDF viewer Web Component powered by mozilla/pdf.js. Toolbar, thumbnails, zoom, print, download, dark mode, i18n, and password protection out of the box.
Maintainers
takuya-motoshimaReadme
pdf-live
Features
- Zero config — works as a single HTML tag
- Toolbar — zoom in/out, fit to page/width, page navigation, print, download
- Thumbnail panel — collapsible side panel with page previews
- Dark / Light theme — toggle at runtime, persisted via
localStorage - Ctrl+Wheel zoom — smooth zoom with mouse wheel
- Password protection — built-in password modal with sync/async verification
- i18n — 12 languages (de, en, es, fr, it, ja, ko, nl, pt_br, ru, zh_cn, zh_tw)
- CJK support — optional CMap for fonts that require it
- Mobile-ready — responsive layout, thumbnail panel auto-hides on small viewports
Demo
| Demo | Description |
|------|-------------|
| Light Theme | Default light theme viewer. |
| Dark Theme | Dark theme with restoretheme="false". |
| Password | Synchronous password verification. |
| Async Password | Asynchronous (server-side) password verification. |
| Events | documentLoaded and pageChange event handling. |
| i18n | Japanese locale (lang="ja") with password protection. |
Install
npm i pdf-liveQuick Start
CSS — add the stylesheet to your
<head>:<link rel="stylesheet" href="node_modules/pdf-live/dist/pdf-live.css">HTML — place the
<pdf-live>element in your<body>:<pdf-live src="sample.pdf" lang="en" worker="node_modules/pdf-live/dist/pdf.worker.js" ></pdf-live>JS — import the module:
<!-- ES Module --> <script type="module"> import './node_modules/pdf-live/dist/pdf-live.esm.js'; </script> <!-- UMD --> <script src="node_modules/pdf-live/dist/pdf-live.js"></script>With a bundler (webpack, Vite, etc.) you can use the package name directly:
import 'pdf-live';
Usage
const pdflive = document.querySelector('pdf-live');
pdflive
.on('documentLoaded', () => {
console.log('PDF loaded');
})
.on('pageChange', pageNum => {
console.log(`Page ${pageNum}`);
});API
Attributes
| Attribute | Required | Description |
|-----------|:--------:|-------------|
| src | Yes | URL of the PDF document. |
| worker | Yes | Path to the pdf.js worker script. Use node_modules/pdf-live/dist/pdf.worker.js. |
| lang | | UI language. One of de, en, es, fr, it, ja, ko, nl, pt_br, ru, zh_cn, zh_tw. Defaults to en. |
| title | | Document title shown in the toolbar, browser tab, and used as the print/download filename. Falls back to the filename in the src URL. |
| protected | | Enables password protection. A password modal is shown before loading the document. Requires a passwordEnter event listener. |
| cmap | | Path to CMap files for CJK font support. Use node_modules/pdf-live/dist/cmaps. |
| restoretheme | | Set to "false" to disable automatic theme restoration from localStorage. |
Static Methods
PDFLiveElement.define()
Registers the <pdf-live> custom element with the browser. Called automatically on import, so manual invocation is usually unnecessary.
Returns PDFLiveElement class.
PDFLiveElement.createElement()
Convenience factory that registers the custom element (if needed) and creates a new instance. Useful for programmatic usage in frameworks.
Returns PDFLiveElement instance.
import PDFLiveElement from 'pdf-live';
const pdflive = PDFLiveElement.createElement();
pdflive.setAttribute('src', 'document.pdf');
pdflive.setAttribute('worker', 'node_modules/pdf-live/dist/pdf.worker.js');
document.body.appendChild(pdflive);Instance Methods
on(type, listener) → PDFLiveElement
Registers an event listener. Returns the element for chaining.
pdflive.on('pageChange', pageNum => { /* ... */ });Parameters:
| Name | Type | Description |
|------|------|-------------|
| type | string | Event type: "pageChange", "documentLoaded", or "passwordEnter". |
| listener | Function | Callback function. |
getCurrentPageNumber() → number
Returns the current 1-based page number.
const page = pdflive.getCurrentPageNumber(); // 1print() → Promise<void>
Opens the browser print dialog with the loaded PDF.
await pdflive.print();download() → Promise<void>
Downloads the PDF. Uses the title attribute as the filename if set.
await pdflive.download();Events
Listen with on(). All listeners are chainable.
documentLoaded
Fired when the PDF document has finished loading and rendering.
pdflive.on('documentLoaded', () => {
console.log('Ready');
});pageChange
Fired when the visible page changes. Receives the 1-based page number.
pdflive.on('pageChange', pageNum => {
console.log(`Page ${pageNum}`);
});passwordEnter
Fired when the user submits a password. The listener must return true if the password is correct, false otherwise. Supports async listeners.
// Sync
pdflive.on('passwordEnter', password => {
return password === 'secret';
});
// Async (server-side verification)
pdflive.on('passwordEnter', async password => {
const res = await fetch('/api/verify', {
method: 'POST',
body: JSON.stringify({ password }),
});
return (await res.json()).ok;
});Note: The
<pdf-live>element must have theprotectedattribute for this event to work.
Changelog
See CHANGELOG.md.
Author
shumatsumonobu · GitHub · X · Facebook