UI Integration Guide

This guide explains how to integrate the PDF Web SDK UI into your application using the PdfEditor function.

Installation

npm install https://cdn-developers.avanquest.com/websdk-files/packages/pdf-web-viewer/0.11.8/avanquest-pdf-web-viewer-0.11.8.tgz

Basic Usage

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';

Initialization

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 operations
isLoading state indicator

Result Structure

interface 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, options?: ShowSnackbarOptions) => ISnackbarHandle; // Show a notification
  };
  sdk: IPdfSdk; // Initialized SDK for headless operations
  isLoading?: boolean;
  error?: Error;
}

Usage Modes

1. Full UI Mode (Default)

When you provide a container element, the PDF Web SDK 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;
}

2. Minimal UI Mode (hideToolsPanel)

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 */,
});

/* Open the document into the view (editor.sdk.openDocument opens it headless, without displaying it) */
await editor.ui.pdfWebService.openDocument(myPdfFile);

3. Headless Mode (Without Container)

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 });

4. Direct SDK Usage (Alternative)

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();

Notifications

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', 'warning' or 'info' (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.

Reporting a long-running job

A third options argument turns the snackbar into a progress report: a ring ahead of the message, and an action button after it. showSnackbar hands back a handle that drives it while it is up.

const bar = editor.ui.showSnackbar('info', 'Recognizing your document’s content…', {
  duration: null, // sticky — it closes when you say so
  progress: 0, // 0–100 — the arc's length, and the arc spins
  action: { label: 'Cancel', onClick: () => job.abort() },
});

job.onProgress((percent) => (bar.progress = percent));
job.onStage((label) => (bar.message = label));
job.onDone(() => bar.close());

progress is a 0–100 number (clamped). It sets the length of the ring's arc, and that arc spins for as long as the snackbar is up — so the ring reads as busy while still showing how far the work has got. Each new value eases into place rather than snapping. Omit progress for an ordinary snackbar, and pair it with duration: null so the snackbar stays up for as long as the work runs.

action draws a single trailing button, and takes the place of the default close button — an action snackbar has one trailing control, not two. label is resolved the same way as message, and onClick fires on press. The snackbar closes first unless you pass closeOnClick: false; since that also removes the user's way out, pair it with a duration or close it yourself through the handle.

The handle

showSnackbar always returns an ISnackbarHandle, whatever happened to the snackbar:

Member
`progress`	Read or write the ring, `0`–`100`. Reads `0` on a snackbar shown without `progress`.
`message`	Read or write the text, in place — no re-animation.
`isClosed`	`true` once it has left the screen, whether by timeout, the close button, its action, or `close()`.
`close()`	Dismiss it early. Safe to call more than once.

Writes are ignored once the snackbar has closed, so a late tick from a finished job cannot resurrect it — you never have to guard a progress callback. The ring is only moved on a snackbar that was shown with a progress value, never added retroactively.

A snackbar that was never shown — suppressed by disableDefaultNotifications, or de-duplicated against a live one with the same key — still returns a handle, one that reports isClosed: true and ignores every write. So the calling code stays the same either way and never needs a null check.

Note: disableDefaultNotifications: true turns off all snackbars, including the ones you raise with showSnackbar. Leave it unset if your application relies on this API.

Next Steps

Explore the Configuration Options
Learn about the Document View Service
Learn about the Document Viewer Wrapper Element
Learn about the Document View Element
Learn about the E-Sign Flow
Check the Framework Integrations

PDF Web SDK Documentation