Configuration Options

The ui.ISetupOptions interface defines all configuration options for the PDF Web SDK. 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`	ui.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`	ui.ILayoutConfig	Configuration for the editor layout (header, sidebar, etc.).	No
`brandingConfig`	ui.IBrandingConfig	Configuration for branding (colors, logos).	No
`themeConfig`	ui.IThemeConfig	Configuration for the theme (light/dark).	No
`languageConfig`	ui.ILanguageConfig	Configuration for the language.	No
`translateConfig`	ui.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, opening Office files). Defaults to `https://api-developers.avanquest.com`.	No
`apiAuthMode`	ui.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
`apiCallbackUrls`	ui.IApiCallbackUrlsConfig	Per-tool webhooks (`X-Callback-Url`) the API calls when it finishes a job in the background. See Basic Setup.	No
`defaultFont`	ui.IDefaultFontConfig	Configuration for the default font.	No
`unitsAndGuides`	ui.IUnitsAndGuidesConfig	Configuration for units and guides.	No
`ocrAdvancedConfig`	ui.IOcrAdvancedConfig	OCR Advanced settings; hidden until `available: true`.	No
`userManagementConfig`	ui.IUserManagementConfig	Sign-in / account integration. See Sign-in & Cloud Drives.	No
`oneDriveConfig`	ui.IOneDriveConfig	OneDrive card on the home screen. See Sign-in & Cloud Drives.	No
`googleDriveConfig`	ui.IGoogleDriveConfig	Google Drive card on the home screen. See Sign-in & Cloud Drives.	No
`dropboxConfig`	ui.IDropboxConfig	Dropbox card on the home screen. See Sign-in & Cloud Drives.	No
`netExplorerConfig`	ui.INetExplorerConfig	NetExplorer card on the home screen. See Sign-in & Cloud Drives.	No
`customProviders`	ui.ICustomFilesProvider`[]`	Host-owned storage sources shown as extra home-screen tabs.	No
`recentsConfig`	ui.IRecentsConfig	Persistence for the recent-documents history.	No
`deviceConfig`	ui.IDeviceConfig	"This device" as a save target. See Saving.	No
`userName`	`string`	The name of the user (for annotations).	No
`disableDefaultNotifications`	`boolean`	If `true`, suppresses all snackbars (including `showSnackbar`).	No
`container`	`HTMLElement`	The DOM element where the viewer will be rendered.	No
`initialDocument`	sdk.IOpenDocumentOptions	Initial document (`File` object) to open automatically upon viewer initialization.	No
`onLoadingStateChange`	`(isLoading: boolean) => void`	Callback for loading state changes.	No
`onError`	`(error: Error) => void`	Callback for errors.	No
`onConfigChange`	`(config:` ui.IConfigChangeData`) => void`	Callback for configuration changes.	No
`onOpenFile`	`() => Promise<void>`	Custom handler for opening files.	No
`openFormatsConfig`	ui.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, claims) => void`	Custom handler for exported files (Download, extractions, conversion results); `claims` names what the contents went through.	No
`onPrint`	`(file, newTab, claims) => void`	Custom handler for printing files; `claims` names what the contents went through.	No
`onFullscreenRequested`	`(fullscreen: boolean) => void`	Hands the Fullscreen button to a host that owns the window — see Callbacks.	No
`onPasswordRequired`	ui.IPasswordRequiredCallback	Custom handler for password-protected files.	No
`onSnapshotArea`	`(blob: Blob, claims) => void`	Receives the captured snapshot area.	No
`onAddSignature`	`(appearanceType: AppearanceType) => void`	Replaces the built-in "add signature / initials" flow.	No
`onOperationRequested`	ui.IOperationRequestedCallback	Called before each document operation; resolve `false` to deny it.	No
`onRemoveSignatureRequested`	ui.IRemoveSignatureRequestedCallback	Custom confirmation for "remove all signatures".	No
`onESignFieldFillRequested`	ui.IESignFieldFillRequestedCallback	Replaces the E-Sign signature-capture modal — see E-Sign.	No
`onESignFieldEditRequested`	ui.IESignFieldEditRequestedCallback	Custom editing UI for a placed E-Sign field — see E-Sign.	No
`onESignSignRequested`	ui.IESignSignRequestedCallback	Replaces the E-Sign Sign pipeline — see E-Sign.	No
`onContextMenuRequested`	ui.IContextMenuRequestedCallback	Replace the built-in context menu; return `true` when handled.	No
`onActivity`	ui.IActivityCallback	Structured UI activity feed for analytics.	No
`userFonts`	sdk.IUserFontData	Custom fonts (`{ fonts, baseUrl }`) to make available in the editor.	No
`userInitial`	ui.AppearanceModel`[]`	User's initial appearances.	No
`userSignature`	ui.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
`restoreLastViewSettings`	`boolean`	If `true` (default), reopening a document returns it to the page, zoom and layout it was last closed at. Needs `recentsConfig` to outlive a restart.	No
`sidebarCollapsed`	`boolean`	If `true`, the `navigationSidebar` layout's rail starts collapsed to icons. Default `false`; ignored by layouts without a rail.	No
`sidebarExpandOnHover`	`boolean`	If `true`, a collapsed rail peeks open over the document while the pointer is on it. Default `false` — it stays collapsed.	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: {
    name: 'My Company',
    logoSvg: '<svg>...</svg>',
  },

  // Theme
  themeConfig: {
    pallet: 'light',
    customStyles: {
      '--pwv-main-background-default': '#FFFFFF',
    },
  },

  // 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 `ISessionTokens` (`{ accessToken, refreshToken }`) — a host that interpolated the result into a `Bearer` header must read `.accessToken` from it.

PDF Web SDK Documentation