This guide explains how to integrate the PDF Web Viewer UI into your application using the PdfEditor function.
npm install @avanquest/pdf-web-viewer
To use the UI, you need to import PdfEditor from the package and initialize it.
import { PdfEditor } from '@avanquest/pdf-web-viewer';
// OR
import { PdfEditor } from './node_modules/@avanquest/pdf-web-viewer/ui/index.js';
The PdfEditor function is the entry point for the library:
export async function PdfEditor(options: ISetupOptions): Promise<IPdfEditorResult>;
Returns: Promise<IPdfEditorResult> - Contains:
ui object with access to the pdfWebElement (wrapper), pdfWebService, documentTabs (headless API), and showSnackbar (notifications)sdk field for headless PDF operationsisLoading state indicatorinterface IPdfEditorResult {
ui: {
pdfWebElement: IDocumentViewerWrapperElement; // The PDF editor wrapper element
pdfWebService: IDocumentViewService; // Service for managing document view instances
documentTabs: IDocumentTabsAPI; // Headless API for custom tab bars
showSnackbar: (type: SnackbarType, message: string) => void; // Show a notification
};
sdk: IPdfSdk; // Initialized SDK for headless operations
isLoading?: boolean;
error?: Error;
}
When you provide a container element, the PDF Web Viewer renders its full user interface inside that element. This is the standard mode for displaying PDFs to users.
Important: The container element must have a fixed size (height and width) defined in your CSS.
import { PdfEditor, IPdfEditorResult } from '@avanquest/pdf-web-viewer';
/* 1. Get the container element */
const containerElement = document.getElementById('pdf-viewer-container');
/* 2. Initialize the editor with the container */
const editor: IPdfEditorResult = await PdfEditor({
license: 'YOUR_LICENSE_KEY',
basePath: '/assets',
container: containerElement /* UI will be rendered here */,
});
/* 3. Open a document using pdfWebService */
await editor.ui.pdfWebService.openDocument(myPdfFile);
/* 4. Or use SDK for advanced operations */
const doc = await editor.sdk.openDocument({ file: myPdfFile });
CSS Example:
#pdf-viewer-container {
width: 100%;
height: 800px; /* Must be defined */
border: 1px solid #ccc;
}
When you set hideToolsPanel: true, the editor initializes with only the document view (no toolbar, sidebar, or navigation bar). Useful for read-only document display.
const editor = await PdfEditor({
license: 'YOUR_LICENSE_KEY',
container: containerElement,
hideToolsPanel: true /* Hides all toolbar and sidebar UI */,
});
/* Use SDK to open document programmatically */
await editor.sdk.openDocument({ file: myPdfFile });
If you omit the container option, the PdfEditor initializes in headless mode. This allows you to use the PDF processing capabilities (like merging, splitting, or extracting text) without rendering any UI.
import { PdfEditor, IPdfEditorResult } from '@avanquest/pdf-web-viewer';
/* 1. Initialize without a container */
const editor: IPdfEditorResult = await PdfEditor({
license: 'YOUR_LICENSE_KEY',
basePath: '/assets',
/* No container provided = headless mode */
});
/* 2. Use the SDK for programmatic operations */
const doc = await editor.sdk.openDocument({ file: myPdfFile });
You can also use PdfSdk directly from '@avanquest/pdf-web-viewer/sdk' without going through PdfEditor.
Important: When using PdfSdk directly, you must call PdfSdk.initialize() before any operations.
import { PdfSdk } from '@avanquest/pdf-web-viewer/sdk';
/* 1. Initialize the SDK manually */
await PdfSdk.initialize({
license: 'YOUR_LICENSE_KEY',
basePath: '/assets',
});
/* 2. Now you can use SDK operations */
const doc = await PdfSdk.openDocument({ file: myPdfFile });
const fonts = await PdfSdk.listSystemFonts();
The viewer reports its own results — a completed merge, a failed attachment — in a snackbar at the bottom of the document area. showSnackbar lets your application post to that same place, so a message of yours reads as part of the viewer instead of arriving in a dialog of its own.
editor.ui.showSnackbar('error', 'The file is open in another application.');
type picks the styling: 'success', 'error' or 'warning' (exported as SnackbarType). Each draws its colours from the --pwv-snackbar-* palette tokens, so restyling them follows the usual Theme Configuration.
message is resolved as a translation key first, and rendered verbatim when no translation matches. So a key from the viewer's dictionary gets localized, while a plain sentence — as above — is shown as written. Either way the text is inserted as text, never as markup.
Snackbars auto-close after a few seconds, stack when several are shown, and can be dismissed by the user. Up to five stay visible at once; older ones are dropped as new ones arrive.
Note:
disableDefaultNotifications: trueturns off all snackbars, including the ones you raise withshowSnackbar. Leave it unset if your application relies on this API.