Interface: Configuration

PSPDFKit.Configuration

This describes the properties of a PSPDFKit.load configuration.

Members



Members

(nullable) XFDF: string
Standalone Only

Standalone only

XFDF can be used to instantiate a viewer with a diff that is applied to the raw PDF. This format can be used to store annotation and form fields changes on your server and conveniently instantiate the viewer with the same content at a later time.

Instead of storing the updated PDF, this serialization only contains a diff that is applied on top of the existing PDF and thus allows you to cache the PDF and avoid transferring a potentially large PDF all the time.

You can export this format from a standalone instance by using PSPDFKit.Instance#exportXFDF.

Type:
  • string
Example
PSPDFKit.load({
  XFDF: xfdfString,
  // ...
});

(nullable) XFDFIgnorePageRotation: boolean
Standalone Only

Standalone only

Whether the imported XFDF should ignore the page rotation.

The default import behavior will take the page rotation into account.

This is useful when you have PDF pages that look the same, but have different underlying page rotations. Use in connection with PSPDFKit.Instance#exportXFDF ignorePageRotation parameter.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  XFDF: xfdfString,
  XFDFIgnorePageRotation: true,
  // ...
});

(nullable) XFDFKeepCurrentAnnotations: boolean
Standalone Only

Standalone only

Whether the annotations embedded in the PDF document should be kept instead of replaced importing XFDF.

The default import behavior will replace all annotations.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  XFDF: xfdfString,
  XFDFKeepCurrentAnnotations: true,
  // ...
});

(nullable) aiDocumentAssistant: AIDocumentAssistantConfiguration
Server Only

Server only

This configuration describes a connection with AI Document Assistant service which provides AI capabilities directly in the viewer.

Type:
  • AIDocumentAssistantConfiguration
Example
PSPDFKit.load({
  aiDocumentAssistant: {
    sessionId: 'session-id',
    jwt: 'xxx.xxx.xxx'
    backendUrl: 'https://localhost:4000',
  },
  // ...
});

(nullable) allowLinearizedLoading: boolean
Standalone Only

Standalone only

Enables or disables loading of linearized PDFs. When enabled, the SDK takes advantage of linearized (also known as "fast web view") PDFs, allowing portions of the document to be displayed while it's still being downloaded. If enabled, the PDF viewer will render the document progressively, starting with the first pages, while the rest of the file is downloaded in the background. The user interface will be in read-only mode during the download.

A indicator is displayed in the toolbar showing that the document is being downloaded.

Note: Linearized loading requires the server to support byte-range requests and the PDF document to be linearized.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  allowLinearizedLoading: true,
  // ...
});

(nullable) annotationPresets: object

optional

This property allows you to change a default list of annotation presets for the PSPDFKit instance. This can be used to customize the main toolbar buttons behaviour before the application mounts.

When omitted, it will default to PSPDFKit.defaultAnnotationPresets.

Type:
  • object
Default Value:
Example
const annotationPresets = PSPDFKit.defaultAnnotationPresets
annotationPresets.mypreset = {
  strokeWidth: 10,
};
PSPDFKit.load({ annotationPresets, ... });

(nullable) annotationToolbarItems: PSPDFKit.AnnotationToolbarItemsCallback

optional

You can customise the items inside the annotation toolbars by using this callback. The callback will receive the annotation which is being created or selected and based on it, you can have different annotation toolbars for different annotations.

You can do the following modifications using this API:

  • Add new annotation toolbar items
  • Remove existing annotation toolbar items
  • Change the order of the existing annotation toolbar items
  • Modify selected properties of the annotation toolbar items

You can also use the hasDesktopLayout to determine if the current UI is being rendered on mobile or desktop layout mode, which depends on the current viewport width. Based on that, you can implement different designs for Desktop and Mobile.

This callback gets called every time the annotation toolbar is mounted.

Type:
Example

Add a new annotation toolbar item

PSPDFKit.load({
  annotationToolbarItems: (annotation, { defaultAnnotationToolbarItems, hasDesktopLayout }) => {
    const node = document.createElement('node')
    node.innerText = "Custom Item"

    const icon = `<svg xmlns="http://www.w3.org/2000/svg" height="24" width="24" fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4" /></svg>`

    return [{
      id: "custom",
      type: "custom",
      node: node,
      icon: icon,
      className: 'Custom-Node',
      onPress: () => alert("Custom item pressed!")
    }, ...defaultAnnotationToolbarItems];
  }
});

(nullable) appName: string

optional

When integrating PSPDFKit for Electron with context isolation enabled, this property needs to be set for the SDK to work. It will be ignored in any other case.

The value of this property needs to match the provided license key's bundle ID.

Type:
  • string
Example
PSPDFKit.load({ appName: "my-electron-app" })

authPayload: object
Server Only

required, Server only

The authPayload is the configuration for the JSON Web Token.

Please refer to this guide article for information how to create valid JWTs.

Type:
  • object
Example
PSPDFKit.load({ authPayload: { jwt: 'xxx.xxx.xxx' }, ... });

autoCloseThreshold: number

optional

Threshold in pixels determines when the active anchor should automatically close and snap to the origin anchor, effectively closing the shape.

Type:
  • number
Default Value:
  • 4px
Example
PSPDFKit.load({
  autoCloseThreshold: 50,
});

(nullable) autoSaveMode: PSPDFKit.AutoSaveMode

optional

This property allows you to set the auto save mode, which controls when annotations or form field values get saved.

When using instant: true, the default auto save mode is IMMEDIATE, otherwise it's INTELLIGENT.

Type:
Example
PSPDFKit.load({ autoSaveMode: PSPDFKit.AutoSaveMode.INTELLIGENT })

(nullable) baseCoreUrl: string

optional

This allows you to overwrite the auto-detected URL for the Core worker PSPDFKit assets in Standalone mode. This setting may be necessary when you integrate PSPDFKit for Web JavaScript in an environment that limits the size of the static assets, like Salesforce.

If your Core assets are served from a different origin, you have to include proper CORS headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

This must end with a trailing slash, and the Core assets (pspdfkit-[hash].wasm.js and pspdfkit-[hash].wasm) must be located in a pspdfkit-lib subfolder accessible from the baseCoreUrl.

Type:
  • string
Default Value:
  • Auto-detected it will use the same value as `baseUrl` if set, or the auto-detected value from the currently executed `<script>` tag.
Example
PSPDFKit.load({ baseCoreUrl: 'https://public-server.pspdfkit.com/pspdfkit-core/' });

(nullable) baseProcessorEngineUrl: string

optional, Standalone only

This allows you to overwrite the auto-detected URL for the processor engine worker PSPDFKit assets in Standalone mode. This setting may be necessary when you integrate PSPDFKit for Web JavaScript in an environment that limits the size of the static assets, like Salesforce.

If these assets are served from a different origin, you have to include proper CORS headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

This must end with a trailing slash, and the assets in the /pspdfkit-lib/gdpicture-[hash]/ folder must be directly located in the folder pointed to by baseProcessorEngineUrl.

Type:
  • string
Default Value:
  • Auto-detected it will use the same value as `baseUrl` if set, or the auto-detected value from the currently executed `<script>` tag.
Example
PSPDFKit.load({ baseProcessorEngineUrl: 'https://public-cdn.example.com/pspdfkit-processor-engine/' });

(nullable) baseUrl: string

optional

This allows you to overwrite the auto-detected URL for all PSPDFKit assets. This setting is necessary when you load PSPDFKit for Web JavaScript from a different URL.

If your assets are served from a different origin, you have to include proper CORS headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

This must end with a trailing slash.

Type:
  • string
Default Value:
  • Auto-detected based on the currently executed `<script>` tag.
Example
PSPDFKit.load({ baseUrl: 'https://public-server.pspdfkit.com/' });

container: string|HTMLElement

required

Selector or element where PSPDFKit for Web will be mounted.

The element must have a width and height that's greater than zero. PSPDFKit for Web adapts to the dimensions of this element. This way, applying responsive rules will work as expected.

The element can be styled using relative values as you would expect it to (CSS media queries are encouraged).

Type:
  • string | HTMLElement
Example
// In your HTML
<div class="foo"></div>

// In your JavaScript
PSPDFKit.load({ container: '.foo', ... });
// or
const element = document.getElementsByClassName('foo')[0]
PSPDFKit.load({ container: element, ... });

(nullable) customFonts: Array.<PSPDFKit.Font>
Standalone Only

optional, Standalone only

This property allows you to provide custom fonts you want to use when loading a Standalone instance.

From the callback defined on each PSPDFKit.Font instance you can return a promise that resolves to a Blob of the font you want to use. You are free to fetch it in whatever way you want, and optimize its loading by retrieving it from a cache using the Cache API, get it from IndexedDB, etc.

See this guide article to learn more.

Type:
Example

Fetch and use a custom set of fonts (Standalone)

const fetcher = name =>
  fetch(`https://example.com/${name}`).then(r => {
    if (r.status === 200) {
      return r.blob();
    } else {
      throw new Error();
    }
  });

const customFonts = ["arial.ttf", "helvetica.ttf", "tahoma.ttf"]
   .map(font => new PSPDFKit.Font({ name: font, callback: fetcher }));

PSPDFKit.load({
  customFonts,
  // ...
});

optional

Allows you to customize how to format dates displayed in the UI.

When a date is about to be rendered in specific UI elements, this function is called so the date can be formatted as desired instead of using the default date formatter.

UI elements with customizable dates currently include the annotations sidebar, and comment threads.

This function is called for each date to be formatted, and receives the corresponding Date object, the UI element to which it belongs (either the annotations sidebar or a comment thread) and the AnnotationsUnion or PSPDFKit.Comment instance to which it is associated.

Type:
Example
PSPDFKit.load({
  dateTimeString: ({ dateTime, element }) => {
    if(element === PSPDFKit.UIDateTimeElement.ANNOTATIONS_SIDEBAR) {
      return new Intl.DateTimeFormat("en-US", {
        dateStyle: "short",
        timeStyle: "short",
      }).format(dateTime);
    } else {
      return new Intl.DateTimeFormat("en-US", {
        dateStyle: "full",
        timeStyle: "long",
      }).format(dateTime);
    }
  }
  // ...
});

(nullable) disableForms: boolean

optional

This property is used to force the disabling of form rendering and parsing, even if your license would permit it.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({ disableForms: true })

(nullable) disableHighQualityPrinting: boolean

optional

This property allows you to disable high quality printing, which will print the document in a higher resolution (300dpi) than the default (150dpi). When not explicitly set, high quality printing is disabled for iOS and Android devices on standalone deployments to improve performances.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({ disableHighQualityPrinting: true })

disableMultiSelection: boolean

optional

Disable multi selection for annotations. Disabled by default, when enabled it doesn't allow multiple selection of annotations by calling PSPDFKit.Instance.setSelectedAnnotations, or using the multiple annotations selection UI button.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  disableMultiSelection: true,
});

(nullable) disableOpenParameters: boolean

optional

By default, PSPDFKit for Web will initialize using PDF Open Parameters that are supported by our viewer. This option can be used if you want to opt-out from this behavior.

Setting a custom PSPDFKit.ViewState will overwrite these defaults. You can use PSPDFKit#viewStateFromOpenParameters to manually extract those values.

Currently, we only support the page parameter.

Type:
  • boolean
Example
PSPDFKit.load({
  disableOpenParameters: true,
});

(nullable) disableTextSelection: boolean

optional

When this property is set to true, text in the document can not be highlighted.

Type:
  • boolean
Example
PSPDFKit.load({ disableTextSelection: true })

(nullable) disableWebAssemblyStreaming: boolean
Standalone Only

Optional

When disableWebAssemblyStreaming is set to true, we force disable WebAssembly streaming instantiation. More info about this optimization can be found at: https://pspdfkit.com/blog/2018/optimize-webassembly-startup-performance/#streaming-instantiation-combining-download-and-instantiation-2dc410

Type:
  • boolean
Example
PSPDFKit.load({
  disableWebAssemblyStreaming: true,
  // ...
});

document: string|ArrayBuffer
Standalone Only

required, Standalone only

The URL to a supported document or its content as ArrayBuffer.

PSPDFKit supports the following type of documents:

  • PDF
  • Image

Note that all the formats except for PDF require a dedicate license. Please contact sales to find out more about this.

When providing a URL keep in mind that Cross-Origin Resource Sharing (CORS) apply.

Type:
  • string | ArrayBuffer
Examples

Load a PDF document from an URI

PSPDFKit.load({ document: 'https://example.com/document.pdf', ... });

Load a document from an ArrayBuffer

PSPDFKit.load({ document: arrayBuffer, ... });

(nullable) documentEditorFooterItems: Array.<PSPDFKit.DocumentEditorFooterItem>

optional

This property allows you to set an initial list of document editor footer items for the PSPDFKit instance.

When omitted, it will default to PSPDFKit.defaultDocumentEditorFooterItems.

Type:
Example
const footerItems = PSPDFKit.defaultDocumentEditorFooterItems;
footerItems.reverse();
PSPDFKit.load({ documentEditorFooterItems: footerItems, ... });

(nullable) documentEditorToolbarItems: Array.<PSPDFKit.DocumentEditorToolbarItem>

optional

This property allows you to set an initial list of document editor toolbar items for the PSPDFKit instance.

When omitted, it will default to PSPDFKit.defaultDocumentEditorToolbarItems.

Type:
Example
const toolbarItems = PSPDFKit.defaultDocumentEditorToolbarItems;
toolbarItems.reverse();
PSPDFKit.load({ documentEditorToolbarItems: toolbarItems, ... });

documentId: string
Server Only

required, Server only

The document ID for the document that should be displayed. You can create a document via the PSPDFKit Document Engine API.

Please refer to the Server API documentation for a guide on how to create valid documents.

Type:
  • string
Example
PSPDFKit.load({ documentId: '85203', ... });

dynamicFonts: string
Standalone Only

optional, Standalone only

This property allows you to provide a URL to JSON file with fonts available for downloading, associated with specific ranges of characters and font variations.

The downloadable font files need to be in the same scope as the JSON file.

The JSON file needs to be in the following format:

type FontName = {
// The full name of the font.
fullName: string;
// The next four properties are from the `name` table in the font.
// See https://learn.microsoft.com/en-us/typography/opentype/spec/name#name-ids
// Name ID 1: Font Family name
family?: string;
// Name ID 2: Font Subfamily name
subfamily?: string;
// Name ID 16: Typographic Family name
typographicFamily?: string;
// Name ID 17: Typographic Subfamily name
typographicSubfamily?: staring;
}

// Represents a font that can be downloaded.
// filePath + faceIndex should be unique.
type Font = {
name: FontName;
// Path to the font file.
filePath: string;
// If the font file is a collection, this specifies the face index.
faceIndex?: int;
// A list of all code points supported by the font.
// This can either be a range ([number, number]) or a single codepoint.
codePoints: [[number, number] | number];
// The unicode ranges from the OS/2 table: https://learn.microsoft.com/en-us/typography/opentype/spec/os2#ur
unicodeRanges?: [4 numbers];
// A sha1 of the font file. For collections, this is a SHA of the whole file, not a single font.
sha1: string;
// Specifies true if the font is allowed to be embedded, false otherwise.
// Should only be used to make a decision to download the font, proper licensing handling should be done with the downloaded font.
allowedToEmbed: boolean;
// The boldness of the font. See https://learn.microsoft.com/en-us/typography/opentype/spec/os2#wtc
weight?: number;
}

type DynamicFonts = {
availableFonts: [Font];
v: 1;
}
Type:
  • string
Example

Provide a list of downloadable font files (Standalone)

PSPDFKit.load({
  dynamicFonts: "https://example.com/assets/fonts.json",
  // ...
});

editableAnnotationTypes: Array.<AnnotationsUnion>

optional

This property defines all annotation types that a user is able to modify. If it's not set, the user is allowed to select, create, edit or delete every annotation type. By allowing only certain annotation types for modification, you can be sure that there is no annotation type that gets introduced in the future that your user is then able to modify.

Type:
Example

Allow only the modification of ink annotations

PSPDFKit.load({
  editableAnnotationTypes: [PSPDFKit.Annotations.InkAnnotation],
  // ...
});

(nullable) electronAppName: string

optional

When integrating PSPDFKit for Electron with context isolation enabled, this property needs to be set for the SDK to work. It will be ignored in any other case.

The value of this property needs to match the provided license key's bundle ID.

Type:
  • string
Example
PSPDFKit.load({ electronAppName: "my-electron-app" })

(nullable) enableAutomaticLinkExtraction: boolean
Standalone Only

Standalone only

By default, only links that are represented as valid link annotations in the PDF will be enabled. When enableAutomaticLinkExtraction is set to true, the text of the PDF will be scanned and links will automatically be created.

To enable automatic link extraction on a PSPDFKit Document Engine (server-backed) deployment, check out: https://pspdfkit.com/guides/server/current/configuration/overview/

Type:
  • boolean
Example
PSPDFKit.load({
  enableAutomaticLinkExtraction: true,
  // ...
});

enableClipboardActions: boolean

optional

Enable actions like cut, copy, paste and duplicate for annotations using keyboard shortcuts Cmd/Ctrl+X, Cmd/Ctrl+C, Cmd/Ctrl+V and Cmd/Ctrl+D respectively.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  enableClipboardActions: true,
});

enableHistory: boolean

optional

Enable actions history for annotations. Disabled by default, when enabled it allows to undo and redo annotation actions consecutively by calling PSPDFKit.Instance.history.undo or PSPDFKit.Instance.history.redo, or using the undo and redo UI buttons, which can be optionally enabled:

Actions history tracking can be enabled and disabled at any moment by calling PSPDFKit.Instance.history.enable or PSPDFKit.Instance.history.disable.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({
  enableHistory: true,
  toolbarItems: PSPDFKit.defaultToolbarItems.reduce((acc, item) => {
    if (item.type === "spacer") {
      return acc.concat([item, { type: "undo" }, { type: "redo" }]);
    }
    return acc.concat([item]);
  }, [])
});

This call back defines which text annotations should be treated as rich text annotation. By default, all the text annotations are treated as plain text annotations, which means that when you edit them, you will see the plain text editor. You can change this behavior by returning true for the text annotations that you want to be treated as rich text annotations.

Type:
Example
PSPDFKit.load({ enableRichText: annotation => true });

(nullable) enableServiceWorkerSupport: boolean

optional

When you're using a ServiceWorker, set this flag to true to be able to use PSPDFKit for Web offline. Due to a browser bug, loading CSS files would bypass service workers and we therefore load all CSS files via XHR and embed the content. Instead of loading files like SVGs by using url in your CSS, please add them as base64, otherwise these requests would bypass the service worker as well.

Type:
  • boolean
Example
PSPDFKit.load({
  enableServiceWorkerSupport: true,
  // ...
});

fontSubstitutions: Array.<FontSubstitution>

Allows specifying fonts that you would like to substitute in a document and the fonts you would like to use for that substitution.

Patterns are matched using the following rules:

  • * matches multiple characters.
  • ? matches a single character.

Ordering matters - As names could match multiple patterns, it's important to note that the order of the patterns matters.

Case-insensitive - Both the pattern and the target name are case-insensitive.

Type:
  • Array.<FontSubstitution>
Example

Substitute all Noto fonts found in the document with Awesome font

PSPDFKit.load({
  fontSubstitutions: [
    {
      pattern: "Noto*",
      target: "AwesomeFont"
    }
  ]
});

(nullable) formFieldsNotSavingSignatures: Array.<string>

optional

List of signature form fields names that are not allowed to store Ink Signatures.

When a signature form field name is on this list, any new ink signature for this field that is created via the UI won't be stored.

Type:
  • Array.<string>
Default Value:
  • []
Example

.

PSPDFKit.load({
  formFieldsNotSavingSignatures: ['signatureField1'],
  // ...
});

(nullable) headless: boolean

Loads PSPDFKit for Web in Headless mode i.e. without a UI. Some UI-specific APIs, like the Toolbars API, are not available in this mode and, when used, will throw an error.

Type:
  • boolean
Example
PSPDFKit.load({
  headless: true,
  // ...
});

(nullable) initialViewState: PSPDFKit.ViewState

optional

This property allows you to set an initial viewing state for the PSPDFKit instance.

This can be used to customize behavior before the application mounts (e.g Scroll to a specific page or use the SINGLE_PAGE mode)

It will default to a view state with its default properties (see PSPDFKit.ViewState).

If the initial view state is invalid (for example, when you define a page index that does not exist), the method will fall back to the default value for the invalid property. This means when you set the initial currentPageIndex to 5 but the document only has three pages, PSPDFKit will start on the first page but will still apply other rules defined in this initial view state.

Type:
Default Value:
Example
const initialViewState = new PSPDFKit.ViewState({ currentPageIndex: 2 });
PSPDFKit.load({ initialViewState: initialViewState, ... });

(nullable) inlineTextSelectionToolbarItems: PSPDFKit.InlineTextSelectionToolbarItemsCallback

optional

You can customize the items inside the inline text selection toolbar that is rendered every time some text is selected on the document. The callback will receive the default items of the inline toolbar and the text that is currently selected {@linkPSPDFKit.TextSelection}

You can do the following modifications using this API:

  • Add new toolbar items
  • Remove existing toolbar items
  • Change the order of the existing annotation toolbar items
  • Customise each item eg change the icon of the a default toolbar item.

You can also use the hasDesktopLayout to determine if the current UI is being rendered on mobile or desktop layout mode, which depends on the current viewport width. Based on that, you can implement different designs for Desktop and Mobile.

This callback gets called every time the inline text selection toolbar is mounted.

Type:
Example

Add a custom button and a custom node to the toolbar in desktop layout.

PSPDFKit.load({
inlineTextSelectionToolbarItems: ({ defaultItems, hasDesktopLayout }, selection) => {
 console.log(selection)
 if (hasDesktopLayout) {
   const node = document.createElement("div");
   node.innerText = "Custom Item";
     return [
       ...defaultItems,
       {
         type: "custom",
         id: "custom-1",
         node: node,
         className: "Custom-Node",
         onPress: () => alert("Custom node pressed!"),
       },
       {
         type: "custom",
         id: "custom-2",
         title: "custom-button-2",
         onPress: () => alert("Custom item pressed!"),
       },
     ];
    }
 return defaultItems
  },
})

(nullable) inlineWorkers: boolean
Standalone Only

Standalone only

By default, we load the required Web Workers inline. That means that the Web Workers are loaded as a blob URL, which allows us to load a Worker from other domains. However, this might interfere with strict CSP policies like worker-src: 'self'. In that case, you can disable the inline loading of the Web Workers by setting this option to false.

Note: This option is currently not supported in Salesforce environment.

Type:
  • boolean
Default Value:
  • true
Example
PSPDFKit.load({
  inlineWorkers: false,
  // ...
});

instant: boolean
Server Only

required, Server only

PSPDFKit Instant is a real-time collaboration platform that enables your users to annotate documents using PSPDFKit across iOS, Android and their browser simultaneously. Annotations synchronized using PSPDFKit Instant are pushed in real-time to every connected device.

All document editing features, such as text annotations, ink drawing or text highlighting, are instantly saved and propagated across all connected devices.

When this flag is set to true, different parts of the API will also be enabled, for example: PSPDFKit.Instance#connectedInstantClients.

This value does not have a default. You either need to define instant: true or instant: false in your PSPDFKit configuration.

Type:
  • boolean
Example
PSPDFKit.load({ instant: true, ... });

(nullable) instantJSON: object
Standalone Only

Standalone only

Instant JSON can be used to instantiate a viewer with a diff that is applied to the raw PDF. This format can be used to store annotation changes on your server and conveniently instantiate the viewer with the same content at a later time.

Instead of storing the updated PDF, this serialization only contains a diff that is applied on top of the existing PDF and thus allows you to cache the PDF and avoid transferring a potentially large PDF all the time.

You can export this format from a standalone instance by using PSPDFKit.Instance#exportInstantJSON.

annotations will follow the Instant Annotation JSON format specification.

Type:
  • object
Example
PSPDFKit.load({
  instantJSON: {
    format: 'https://pspdfkit.com/instant-json/v1',
    skippedPdfObjectIds: [1],
    annotations: [
      { id:  1, pdfObjectId: 1, type: 'pspdfkit/text', content: 'Hello World', ...},
      { id: -1, type: 'pspdfkit/text', content: 'Hello Universe', ...},
    ],
  },
  // ...
});

(nullable) isEditableAnnotation: PSPDFKit.IsEditableAnnotationCallback

optional

By implementing this callback you have a fine grained control over which annotations are read-only. This callback will receive the Annotation a user wants to modify and by returning true or false you can define if the annotation should be read-only (false) or modifiable (true).

This API will not disable ToolbarButtons for you, but will not allow the user to create a new Annotation with the UI.

Type:
Examples

Only allow the modification of annotations from the same author

PSPDFKit.load({
  isEditableAnnotation: function(annotation) {
    return annotation.creatorName === myCurrentUser.name;
  },
});

Do not allow changing the value of a specific form field

PSPDFKit.load({
  isEditableAnnotation: function(annotation) {
    // Check if the annotation is associated with a specific form field
    if (
      annotation instanceof PSPDFKit.Annotations.WidgetAnnotation &&
      annotation.formFieldName === "MyFormField"
    ) {
      // If it is, disallow editing it
      return false;
    }
    // Otherwise, allow editing
    return true;
  },
});

(nullable) isEditableComment: PSPDFKit.IsEditableCommentCallback

optional

By implementing this callback you have a fine grained control over which comments are read-only. This callback will receive the Comment a user wants to modify and by returning true or false you can define if the comment should be read-only (false) or modifiable (true).

To learn more check this guide article.

Type:
  • PSPDFKit.IsEditableCommentCallback
Example

Only allow the modification of comment from the same author.

PSPDFKit.load({
  isEditableComment: function(comment) {
    return comment.creatorName === myCurrentUser.name;
  },
});

(nullable) licenseKey: string
Standalone Only

Standalone only

PSPDFKit for Web license key from https://customers.pspdfkit.com.

If not provided, the instance will run in trial mode for a limited time and then request the user to visit https://pspdfkit.com/try/ to request a trial license.

Type:
  • string
Example

Activate with a license key

PSPDFKit.load({ licenseKey: "YOUR_LICENSE_KEY_GOES_HERE", ... });

(nullable) locale: string

The initial locale (language) for the application. All the available locales are defined in PSPDFKit.I18n.locales. When a locale is not provided PSPDFKit for Web tries to autodetect the locale using window.navigator.language. If the detected locale is not supported then the en locale is used instead.

Type:
  • string
Example
PSPDFKit.load({
  locale: 'de',
  // ...
});

(nullable) maxDefaultZoomLevel: number

optional

This property allows you to configure the maximum zoom level. The largest zoom level at a given time will be calculated based on the page proportions and this option. This is not necessarily a hard limit. For example, in order to satisfy the 'fit to width' and 'fit to page' zoom modes, the actual maximum zoom may be higher.

When omitted, the default is 10.

Type:
  • number
Default Value:
  • 10
Example
PSPDFKit.load({ maxDefaultZoomLevel: 20 })

maxMentionSuggestions: number

optional, Server only

The maximum number of users that will be shown in the suggestion dropdown when mentioning a user in a comment.

Type:
  • number
Default Value:
  • 5
Example
PSPDFKit.load({ maxMentionSuggestions: 5 });

(nullable) maxPasswordRetries: number

optional

Defines how often the password modal is presented after a wrong password has been entered. By default, there won't be a limit for a regular PSPDFKit for Web installation.

When running in the headless mode, this option is ignored as we don't have an interface where we could request a password (This is the same as setting maxPasswordRetries to 0).

Type:
  • number
Example
PSPDFKit.load({
  maxPasswordRetries: 3,
  // ...
});

measurementPrecision: PSPDFKit.MeasurementPrecision

Set the precision value of all the newly created measurement annotations.

Type:
Default Value:
  • PSPDFKit.MeasurementPrecision.TWO
Example
PSPDFKit.load({ measurementPrecision: PSPDFKit.MeasurementPrecision.THREE });

measurementScale: PSPDFKit.MeasurementScale

Set the default value of scale for all newly created measurement annotations.

Type:
Default Value:
  • 1 inch = 1 inch
Example
PSPDFKit.load(new PSPDFKit.MeasurementScale({
  unitFrom: PSPDFKit.MeasurementScaleUnitFrom.CENTIMETERS,
  unitTo: PSPDFKit.MeasurementScaleUnitTo.INCHES,
  fromValue: 1,
  toValue: 2,
}));

(nullable) measurementSnapping: boolean

optional

Allows the user to toggle the snapping behavior while creation of measurement annotations. The snapping points are the points are a combination of endpoints, midpoints and intersections.

Type:
  • boolean
Default Value:
  • false
Example
PSPDFKit.load({ measurementSnapping: false });

mentionableUsers: Array.<MentionableUser>

optional, Server only

A list of users that can be mentioned in comments.

Type:
Example
PSPDFKit.load({ mentionableUsers: [
  { id: "1", name: "John Doe", displayName: "John", avatar: "https://example.com/avatar.png", description: "[email protected]" },
  { id: "2", name: "Jane Doe", displayName: "Jane", avatar: "https://example.com/avatar.png", description: "[email protected]" },
  { id: "3", name: "John Smith", displayName: "John", avatar: "https://example.com/avatar.png", description: "[email protected]" },
] });

(nullable) minDefaultZoomLevel: number

optional

This property allows you to configure the minimum zoom level. The smallest zoom level at a given time will be calculated based on the page proportions and this option. This is not necessarily a hard limit. For example, in order to zoom out to show the entire page, the actual minimum zoom may be lower.

When omitted, the default is 0.5.

Type:
  • number
Default Value:
  • 0.5
Example
PSPDFKit.load({ minDefaultZoomLevel: 0.1 })

onAnnotationResizeStart: PSPDFKit.AnnotationResizeStartCallback

optional Allows to modify the default behavior when annotations are resized using the selection corner handles by returning an object. This provides more control over whether annotations should keep their aspect ratio when resized, for example.

Type:
Example

Unlock aspect ratio for the top left resize anchor

PSPDFKit.load({
  onAnnotationResizeStart: event => {
    return {
      maintainAspectRatio: event.resizeAnchor === 'TOP_LEFT',
    }
  }
});

onCommentCreationStart: PSPDFKit.OnCommentCreationStartCallback

optional

You can programmatically modify the properties of the comment just before it is created.

Type:
Example
PSPDFKit.load({ onCommentCreationStart: comment => comment.set('text', { format: 'xhtml', value: '<p>Default text</p>' }) });

onCreateWidgetAnnotationStart: PSPDFKit.OnWidgetAnnotationCreationStartCallback

optional

You can programmatically modify the properties of the widget annotation and the associated form field just before it is created via the Form Creator UI.

Type:
Default Value:
  • undefined
Example

Set the opacity of all widget annotations.

PSPDFKit.load({
  onWidgetAnnotationCreationStart: (annotation, formField) => {
    return { annotation: annotation.set('opacity', 0.7) };
  }
  // ...
});

onOpenURI: PSPDFKit.OnOpenUriCallback

optional

By default, all the URLs on which the user clicks explicitly open as expected but the URLs which open due to a result of JavaScript action are not opened due to security reasons. You can override this behaviour using this callback. If this callback returns true, the URL will open.

Type:
  • PSPDFKit.OnOpenUriCallback
Default Value:
  • undefined
Example
PSPDFKit.load({
  onOpenURI: (url, isUserInitiated) => {
    if (url.startsWith('https://abc.com') && isUserInitiated) {
      return true
    }

    return false;
  }
  // ...
});

(nullable) overrideMemoryLimit: number
Standalone Only

optional

Overrides the allocable maximum memory when using PSPDFKit for Web Standalone. Only set this if you know that your users have web browsers with enough memory available.

This can improve rendering of documents with large images.

Type:
  • number
Example
PSPDFKit.load({
  overrideMemoryLimit: 4096, // 4 GB
  // ...
});

(nullable) password: string

optional

If set, it will try to unlock the PDF with the provided password when loading it. PDFs which do not require a password won't open if this property is set.

Type:
  • string
Example
PSPDFKit.load({
  password: 'secr3t',
  // ...
});

(nullable) populateInkSignatures: function

optional

Loads Ink Signatures when the UI displays them for the first time.

Ink Signatures are special Ink Annotations whose pageIndex and boundingBox are defined at creation time. They can be converted to serializable objects with PSPDFKit.Annotations.toSerializableObject and stored as JSON using their InstantJSON format. Serialized JSON annotations can be deserialized with JSON.parse and then converted to annotations with PSPDFKit.Annotations.fromSerializableObject.

Type:
  • function
Deprecated
Default Value:
  • () => Promise.resolve(PSPDFKit.Immutable.List())
Example

Populate Ink Signatures on demand.

PSPDFKit.load({
  populateInkSignatures: () => {
   return fetch('/signatures')
      .then(r => r.json())
      .then(a => (
          PSPDFKit.Immutable.List(
            a.map(PSPDFKit.Annotations.fromSerializableObject))
          )
       );
  },
  // ...
});

(nullable) populateStoredSignatures: function

optional

Loads signatures when the UI displays them for the first time.

Signatures can be added as special Ink Annotations or Image Annotations whose pageIndex and boundingBox are defined at creation time. They can be converted to serializable objects with PSPDFKit.Annotations.toSerializableObject and stored as JSON using their InstantJSON format. Serialized JSON annotations can be deserialized with JSON.parse and then converted to annotations with PSPDFKit.Annotations.fromSerializableObject.

Type:
  • function
Default Value:
  • () => Promise.resolve(PSPDFKit.Immutable.List())
Example

Populate Signatures on demand.

PSPDFKit.load({
  populateStoredSignatures: () => {
   return fetch('/signatures')
      .then(r => r.json())
      .then(a => (
          PSPDFKit.Immutable.List(
            a.map(PSPDFKit.Annotations.fromSerializableObject))
          )
       );
  },
  // ...
});

(nullable) preventTextCopy: boolean

optional

When copying of text is disabled, it's still possible to select text but copying either using the shortcut or a context menu will have no effect.

This is implemented internally by listening to the copy event and prevent the default implementation.

Please note that preventing text copying only provides limited security since the text will still be transmitted to the client.

Type:
  • boolean
Example
PSPDFKit.load({
  preventTextCopy: true,
  // ...
});

(nullable) printOptions: object

optional

Allows to set different printing options like mode and printing quality.

Type:
  • object
Properties:
Name Type Description
mode PSPDFKit.PrintMode

PSPDFKit.PrintMode mode to use for printing.
quality PSPDFKit.PrintQuality

PSPDFKit.PrintQuality The option to control the quality of the printing.
Default Value:
  • { mode: PSPDFKit.PrintMode.DOM, quality: PSPDFKit.PrintQuality.HIGH }

processorEngine: PSPDFKit.ProcessorEngine

optional, Standalone only

Document processing can be a time-consuming task, especially when working with large documents. In order to improve the user experience it is possible to choose between two different processor engines with different optimizations applied: either one with a smaller bundle size (the default), but slower overall performance, or one with a larger bundle size, but faster processing time.

Either case it's recommended to enable asset compression on your Server to improve loading time.

Type:
Default Value:
  • PSPDFKit.ProcessorEngine.fasterProcessing
Example
PSPDFKit.load({ processorEngine: PSPDFKit.ProcessorEngine.fasterProcessing });

productId: PSPDFKit.ProductId

optional, Standalone only

Allows specifying the environment in which the SDK is running.

Type:
Example
PSPDFKit.load({ productId: PSPDFKit.ProductId.SharePoint });

(nullable) renderPageCallback: PSPDFKit.RenderPageCallback

optional

This callback is called whenever a page is rendered or printed (only for PSPDFKit.PrintMode.DOM). You can use it to render watermarks on the page.

Type:
Example
PSPDFKit.load({
  renderPageCallback: function(ctx, pageIndex, pageSize) {
    ctx.beginPath();
    ctx.moveTo(0, 0);
    ctx.lineTo(pageSize.width, pageSize.height);
    ctx.stroke();

    ctx.font = "30px Comic Sans MS";
    ctx.fillStyle = "red";
    ctx.textAlign = "center";
    ctx.fillText(
      `This is page ${pageIndex + 1}`,
      pageSize.width / 2,
      pageSize.height / 2
    );
  }
  // ...
});

restrictAnnotationToPageBounds: boolean

This property allows you to restrict the movement of annotations to the page boundary. This is set to true by default. If you want to disable this, you can set it to false.

Type:
  • boolean
Default Value:
  • true

(nullable) serverUrl: string

optional

This allows you to overwrite the auto-detected PSPDFKit Document Engine URL. This setting is necessary when your PSPDFKit Document Engine is located under a different URL.

Type:
  • string
Default Value:
  • Auto-detected based on the currently executed `<script>` tag.
Example
PSPDFKit.load({ serverUrl: 'https://public-server.pspdfkit.com/' })

optional

This property allows you to set an initial list of stamp and image annotation templates for the PSPDFKit instance. This can be used to customize the list of available stamp and image annotation templates that will be available in the stamps picker UI before the application mounts.

When omitted, it will default to PSPDFKit.defaultStampAnnotationTemplates.

Type:
Example
const stampAnnotationTemplates = PSPDFKit.defaultStampAnnotationTemplates
const stampAnnotationTemplates.push(new PSPDFKit.Annotations.StampAnnotation({
  stampType: "Custom",
  title: "My custom text",
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 0,
    top: 0,
    width: 300,
    height: 100
  })
}));
PSPDFKit.load({ stampAnnotationTemplates, ... });

(nullable) standaloneInstancesPoolSize: number
Standalone Only

Standalone only

PSPDFKit for Web uses an object pool to keep disposed instances in memory for fast reuse. Since this process can be memory inefficient, by default we only keep one instance in memory.

With this configuration option you can tune in the number of instances to keep in memory, or disable object pooling by setting this parameter to 0.

More about this feature: https://pspdfkit.com/blog/2018/optimize-webassembly-startup-performance/#object-pooling-caching-instances-d548cb

Type:
  • number
Default Value:
  • 1
Example
PSPDFKit.load({
  standaloneInstancesPoolSize: 2,
  // ...
});

(nullable) styleSheets: Array.<string>

optional

This will load your custom CSS as a <link rel="stylesheet"> inside the PSPDFKit component. This is necessary to isolate styling of the viewer from the outside application and avoid external stylesheets overwriting important viewer attributes.

An array is allowed to load multiple stylesheets. The order in the array will also be the order in which the stylesheets get loaded.

The array will be copied by us on start up time, which means that you can not mutate it after the viewer has started.

More information on how to style PSPDFKit for Web can be found in our guides.

Type:
  • Array.<string>
Default Value:
  • []
Example
PSPDFKit.load({
  styleSheets: [
    'https://example.com/my-stylesheet.css',
    'https://example.com/other-stylesheet.css'
  ]
})

(nullable) theme: PSPDFKit.Theme

optional

This property allows you to set theme to use for the UI. See PSPDFKit.Theme

Note: Themes are not supported in IE and setting this option won't have any effect: IE users will get the default light theme. You can customize the appearance of the UI using our public CSS classes. Please refer to this guide article for information on how to customize the appearance.

Type:
Default Value:
  • PSPDFKit.Theme.LIGHT
Example
PSPDFKit.load({ theme: PSPDFKit.Theme.DARK })

(nullable) toolbarItems: Array.<PSPDFKit.ToolbarItem>

optional

This property allows you to set an initial list of toolbar items for the PSPDFKit instance. This can be used to customize the main toolbar before the application mounts.

When omitted, it will default to PSPDFKit.defaultToolbarItems.

Type:
Default Value:
Example
const toolbarItems = PSPDFKit.defaultToolbarItems;
toolbarItems.reverse();
PSPDFKit.load({ toolbarItems: toolbarItems, ... });

(nullable) toolbarPlacement: PSPDFKit.ToolbarPlacement

optional

This property allows you to configure where the toolbar is placed. If nothing is configured, it will default to the top.

Type:
Default Value:
  • PSPDFKit.ToolbarPlacement.TOP
Example
PSPDFKit.load({ toolbarPlacement: PSPDFKit.ToolbarPlacement.TOP })

(nullable) trustedCAsCallback: PSPDFKit.TrustedCAsCallback
Standalone Only

required, Standalone only

By implementing this callback you have a fine grained control over which certificates are going to be used for digital signatures validation.

The callback must return an Array of ArrayBuffer (DER) or string (PEM) containing X.509 certificates.

See this guide article to learn more.

Type:
Example

Fetch and use custom set of certificates (Standalone)

PSPDFKit.load({
  trustedCAsCallback: function() {
    return new Promise((resolve, reject) => {
       fetch("/your-certificate.cer")
        .then(res => res.arrayBuffer())
        .then(cert => resolve([cert]))
        .catch(reject)
    });
  },
  // ...
})

(static, nullable) annotationToolbarColorPresets: PSPDFKit.AnnotationToolbarColorPresetsCallback

optional

You can customize the color dropdown of individual annotation properties using this callback. This callback receives the property name associated with the color dropdown and the array of default colors used by PSPDFKit.

With this API you can:

  • render a customised color pallet in each and all color dropdowns
  • control if the custom color picker UI should be rendered in the color dropdowns
Type:
Example

Customize different color dropdowns.

PSPDFKit.load({
 annotationToolbarColorPresets: function ({ propertyName }) {
   if (propertyName === "font-color") {
     return {
       presets: [
         {
           color: new PSPDFKit.Color({ r: 0, g: 0, b: 0 }),
           localization: {
             id: "brightRed",
             defaultMessage: "Bright Red",
           },
         },
         {
           color: new PSPDFKit.Color({ r: 100, g: 100, b: 180 }),
           localization: {
             id: "deepBlue",
             defaultMessage: "deepBlue",
           },
         },
       ],
     };
   }

   if (propertyName === "stroke-color") {
     return {
       presets: [
         {
           color: new PSPDFKit.Color({ r: 0, g: 0, b: 0 }),
           localization: {
             id: "brightRed",
             defaultMessage: "Bright Red",
           },
         },
         {
           color: new PSPDFKit.Color({ r: 100, g: 100, b: 180 }),
           localization: {
             id: "deepBlue",
             defaultMessage: "deepBlue",
           },
         },
       ],
       showColorPicker: false,
     };
   }
 },
 //...
});

(static, nullable) annotationTooltipCallback: PSPDFKit.AnnotationTooltipCallback

optional

This callback is called whenever an annotation gets selected and can be used to define and return an array of PSPDFKit.ToolItem that will be rendered in a tooltip for the given annotation.

If the callback returns an empty array then PSPDFKit won't show any tooltip for the selected annotation.

Type:
Example
PSPDFKit.load({
  annotationTooltipCallback: function(annotation) {
    if (annotation instanceof PSPDFKit.Annotations.TextAnnotation) {
      var toolItem = {
        type: 'custom',
        title: 'tooltip item for text annotations',
        id: 'item-text-tooltip-annotation',
        className: 'TooltipItem-Text',
        onPress: function () {
          console.log(annotation)
        }
      }
      return [toolItem]
    } else {
      return []
    }
  }
  // ...
});

(static, nullable) customRenderers: PSPDFKit.CustomRenderers

optional

This object can include functions to be called when specific entities, like annotations, are being rendered in the viewport, and return additional or replacement DOM content for the entity instance.

Currently only annotation's rendering can be customized using the Annotation key.

If the callback returns null, the instance will be rendered normally.

Type:
Example
PSPDFKit.load({
  customRenderers: {
    Annotation: ({ annotation }) => ({
      node: document.createElement('div').appendChild(document.createTextNode('Custom rendered!')),
      append: true,
    })
  }
  // ...
});

(static) customUIConfiguration: PSPDFKit.CustomUIConfiguration

optional Object with callback methods to be called when different elements of the UI are being rendered. Can return DOM content to be appended to them, as well as callback functions to individually process different parts of the element (items) as they're rendered.

UI elements currently supported: sidebars.

Type:
Example
//Fully customized sidebar

PSPDFKit.load({
  customUI: {
    [PSPDFKit.UIElement.Sidebar]: {
      [PSPDFKit.SidebarMode.CUSTOM]({ containerNode }) {
        // ReactDOM.createPortal() can be used as well.
        // Or Vue portals, or any other framework API that allows appending components
        // to arbitrary DOM nodes.
        // Using vanilla JS, you can just append a node to parentNode.
        const div = document.createElement("div");
        div.append("My custom sidebar");
        containerNode.appendChild(div);

        return {
          // By returning the same node that was provided, we opt-out of having the node
          // appended. If we return a different node, it will be appended to the provided node.
          node: containerNode,
        };
      }
    }
  }
});

//Partially customized sidebar

PSPDFKit.load({
  customUI: {
    [PSPDFKit.UIElement.Sidebar]: {
      [PSPDFKit.SidebarMode.ANNOTATIONS]({ containerNode }) {
        containerNode.style.padding = "0.5rem";

        if (!containerNode.querySelector(".MyCustomSidebarComponentHeader")) {
          const header = document.createElement("div");
          header.classList.add("MyCustomSidebarComponentHeader");
          containerNode.prepend(header);
        }

        return {
          node: containerNode,
          onRenderItem({ itemContainerNode, item: annotation }) {
            const footerAuthor = itemContainerNode.querySelector(".PSPDFKit-Sidebar-Annotations-Footer span");
            // Change the format of the footer text by prefixing it with "Creator: " and removing the date
            footerAuthor.textContent = `Creator: ${annotation.creatorName}`;

            // Add aria label to the annotation icon
            const annotationIcon = itemContainerNode.querySelector(".PSPDFKit-Icon");
            annotationIcon.setAttribute("aria-label", `Icon for an annotation created by ${annotation.creatorName}.`);
          }
        };
      }
    }
  }
});

(static, nullable) electronicSignatures: PSPDFKit.ElectronicSignaturesConfiguration

optional

Defines specific configuration options related to the electronic signatures feature.

The creationModes key accepts an array of PSPDFKit.ElectronicSignatureCreationMode values that define which signature creation modes and in which order will be offered as part of the Electronic Signatures UI. It defaults to PSPDFKit.defaultElectronicSignatureCreationModes.

The fonts key accepts an array of PSPDFKit.Font instances that specify the name of fonts to be used as part of the 'Type' signing tab. It defaults to PSPDFKit.defaultSigningFonts.

You can specify a subset of our built-in signing fonts or specify entirely custom ones.

For using custom fonts, you need to load a custom style sheet (via PSPDFKit.Configuration#styleSheets) in which you can either specify @font-face rules for the custom font or @import other style sheets containing the fonts loading rules.

As an example of the latter, if we would wish to use the Cookie font from Google Fonts you could use the following style sheet:

@import url('https://fonts.googleapis.com/css2?family=Cookie&display=swap');

And then pass an new PSPDFKit.Font({ name: 'Cookie' }) as part of the fonts array of PSPDFKit.Configuration#electronicSignatures.

Type:
Example
PSPDFKit.load({
  electronicSignatures: {
    creationModes: [PSPDFKit.ElectronicSignatureCreationMode.IMAGE],
    fonts: [new PSPDFKit.Font("Cookie")]
  }
});