Interface: Configuration

PSPDFKit.Configuration

This describes the properties of a PSPDFKit.load configuration.

Members




Members

(nullable) annotationPresets: Object

optional

This property allows you to set an initial 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
const annotationPresets.mypreset = {
  strokeWidth: 10,
};
PSPDFKit.load({ annotationPresets, ... });

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' }, ... });

(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) 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. Please be aware that due to security restrictions, this URL has to match the domain your client is running on.

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) 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
Example
PSPDFKit.load({ disableHighQualityPrinting: true })

(nullable) disableIndexedDBCaching: boolean
Standalone Only

Standalone only

When disableIndexedDBCaching is set to true, PSPDFKit for Web won't cache the WASM module in IndexedDB.

Type:
  • boolean
Example
PSPDFKit.load({
  disableIndexedDBCaching: 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) disableWebAssembly: boolean
Standalone Only

Standalone only

When disableWebAssembly is set to true, the viewer will always use ASM.js. While WebAssembly is the recommended option, there are cases where ASM.js makes more sense (for example, when you want to optimize startup time vs. render time).

For an overview about the benefits of WebAssembly, check out our blog article: https://pspdfkit.com/blog/2017/webassembly-a-new-hope/

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

(nullable) disableWebAssemblyStreaming: boolean
Standalone Only

Standalone only

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

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 Server API.

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

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

(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 Server-backed deployment, check out: https://pspdfkit.com/guides/server/current/configuration/overview/

Type:
  • boolean
Example
PSPDFKit.load({
  enableAutomaticLinkExtraction: 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,
  // ...
});

(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 ViewState({ currentPageIndex: 2 });
PSPDFKit.load({ initialViewState: initialViewState, ... });

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 aw 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', ...},
    ],
  },
  // ...
});

licenseKey: string
Standalone Only

required, Standalone only

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

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

(nullable) overrideMemoryLimit: number
Standalone Only

optional, Standalone only

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 will also continue to work.

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

pdf: string|ArrayBuffer
Standalone Only

required, Standalone only

The URL to the PDF document. It will be loaded with the origin of the website where you include pspdfkit.js.

Type:
  • string | ArrayBuffer
Examples

Load a PDF document from an URI

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

Load a PDF document from an ArrayBuffer

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

(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
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) 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. If you're using PSPDFKit Server, consider including the JWT flag:

https://pspdfkit.com/guides/server/current/pspdfkit-server/client-authentication/#permissions

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

(nullable) printMode: PSPDFKit.PrintMode

optional

This property allows you to set the PSPDFKit.PrintMode to use.

Type:
Default Value:
  • PSPDFKit.PrintMode.DOM
Example
PSPDFKit.load({ printMode: PSPDFKit.PrintMode.DOM })

(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
    );
  }
  // ...
});

(nullable) serverUrl: string

optional

This allows you to overwrite the auto-detected PSPDFKit Server URL. This setting is necessary when your PSPDFKit Server 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' })

(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 modify 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) 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) XFDF: string
Standalone Only

Standalone only

XFDF) can be used to instantiate a viewer with a diff that is applied to the aw 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) 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,
  // ...
});