Configuration Options

The index.ISetupOptions interface defines all configuration options for the PDF Web Viewer. This section provides comprehensive examples and guides for each configuration category.

Configuration Categories

Explore detailed documentation for each configuration area:

Basic Setup - Essential options: license, asset paths, container, UI mode
Layout Configuration - Customize header tabs, sidebar panels, and visible tools
Branding - Company logo, name, contact URL, custom descriptions
Theme - Light/dark mode, custom color pallets, component styling
Language - UI language configuration for different regions
Localization - Measurement units, rulers, guides, and grid settings
User Customization - User name, custom fonts, signatures
Event Callbacks - Handle events and customize file operations

Options Table

Option	Type	Description	Required
`license`	`string`	Your license key.	Yes
`basePath`	`string`	URL prefix under which the `pwv-*` asset folders (worker, fonts, i18n, cursors, stamps) are served. Defaults to the domain root.	No
`hideToolsPanel`	`boolean`	If `true`, hides the toolbar and sidebar (Minimal UI).	No
`defaultPageView`	index.PdfPageView	Initial zoom/fit mode applied to every document on open (e.g. `fit-width`). Defaults to `fit-width` on narrow viewports (<1024px), `fit-page` otherwise.	No
`layoutConfig`	index.ILayoutConfig	Configuration for the editor layout (header, sidebar, etc.).	No
`brandingConfig`	index.IBrandingConfig	Configuration for branding (colors, logos).	No
`themeConfig`	index.IThemeConfig	Configuration for the theme (light/dark).	No
`languageConfig`	index.ILanguageConfig	Configuration for the language.	No
`translateConfig`	index.ITranslateConfig	Configuration for Translate workflow behavior, including OCR scan prompt preference.	No
`apiToolsUrl`	`string`	Base URL of the online tools API (Translate, OCR, Convert, HTML to PDF, eSign). Defaults to `https://api-developers.avanquest.com`.	No
`apiAuthMode`	index.ApiAuthMode	How calls to `apiToolsUrl` are authenticated: `'apiKey'` (default), `'umToken'` or `'none'`. See Basic Setup.	No
`apiToolsHeaders`	`Record<string, string> \| (() => Record<string, string> \| Promise<Record<string, string>>)`	Extra HTTP headers merged into every call to `apiToolsUrl`, after the `apiAuthMode` header. See Basic Setup.	No
`defaultFont`	index.IDefaultFontConfig	Configuration for the default font.	No
`unitsAndGuides`	index.IUnitsAndGuidesConfig	Configuration for units and guides.	No
`userName`	`string`	The name of the user (for annotations).	No
`container`	`HTMLElement`	The DOM element where the viewer will be rendered.	No
`initialDocument`	`IOpenDocumentOptions`	Initial document (`File` object) to open automatically upon viewer initialization.	No
`dialogs`	`CustomDialogs`	Custom dialog implementations.	No
`onLoadingStateChange`	`(isLoading: boolean) => void`	Callback for loading state changes.	No
`onError`	`(error: Error) => void`	Callback for errors.	No
`onConfigChange`	`(config:` index.IConfigChangeData`) => void`	Callback for configuration changes.	No
`onOpenFile`	`() => Promise<void>`	Custom handler for opening files.	No
`openFormatsConfig`	`{@link index.IOpenFormatsConfig}`	Extra file formats the open UI offers, on top of the built-in list. Opening them is yours to handle — see Callbacks.	No
`onExportFile`	`(file: File) => void`	Custom handler for exported files (Download, extractions, conversion results).	No
`onPrint`	`(file: File, newTab?: boolean) => void`	Custom handler for printing files.	No
`onPasswordRequired`	index.IPasswordRequiredCallback	Custom handler for password-protected files.	No
`userFonts`	`IUserFont[]`	List of user-defined fonts.	No
`userInitial`	index.AppearanceModel`[]`	User's initial appearances.	No
`userSignature`	index.AppearanceModel`[]`	User's signature appearances.	No
`openDocumentsInNewTab`	`boolean`	If `true` (default), new documents open in a new tab. If `false`, replaces the current view.	No

Quick Reference

Minimal Configuration

The simplest setup requires only a license key:

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
});

Full UI Configuration

Display the complete PDF editor interface:

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
});

Customized Setup

Configure with custom branding and theme:

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),

  // Branding
  brandingConfig: {
    logo: 'https://example.com/logo.png',
    colors: {
      primary: '#FF6B35',
    },
  },

  // Theme
  themeConfig: {
    mode: 'light',
  },

  // User settings
  userName: 'John Doe',
  languageConfig: {
    code: 'en',
  },
  translateConfig: {
    ocrScanPreference: 'ask',
  },
});

Migrating from earlier versions

The save-model rework changed a few options in ways the compiler will not always catch — plain-JavaScript hosts especially should check each of these:

Before	Now
`onSaveFile` callback	Removed. Save writes back to the file's source; a desktop shell wires the local write through `deviceConfig.saveOver` / `saveInto` — see Saving.
`exportMode`	Removed. On a web page with no `deviceConfig`, Save falls through to the export ("Download") by itself.
`onDownloadFile(file)`	Renamed to `onExportFile(file)` — same signature, now the single exit point for every export.
Recents callbacks (`getRecents(): {name, path}[]`, `getRecent`, `clearRecents`, `getRecentThumbnail(recent)`)	Replaced by `recentsConfig`: `getRecents` / `setRecents` over `IRecentEntry`, `getRecentThumbnail(key)` / `setRecentThumbnail(key, blob)`. Entries stored in the old shape are ignored.
`getAccessToken(): Promise<string \| null>`	Now resolves index.ISessionTokens (`{ accessToken, refreshToken }`) — a host that interpolated the result into a `Bearer` header must read `.accessToken` from it.