Saving Mechanism

PSPDFKit for Web allows modification of multiple domain objects. These objects include annotations, bookmarks, comments, form fields, and form field values.

Server-Backed Deployments

By default, local changes are always synced to the server. This means you can always use the backend API to interact with these objects. This auto-save behavior can be configured by the Configuration#autoSaveMode configuration option.

Before the change is sent to the server, we assign a stable ID (ULID). This ID is also used by the server, and it allows you to track updates that happen before the server responds. If you’d like to ensure a local change has been saved by the server, you can use Instance#ensureChangesSaved method:

PSPDFKit.load(configuration).then(async instance => {
  const createdAnnotations = await instance.create(newAnnotation);
  const [savedAnnotation] = await instance.ensureChangesSaved(
  console.log(; // => '01BS964AM5Z01J9MKBK64F22BQ'
PSPDFKit.load(configuration).then(function(instance) {
    .then(function([savedAnnotation]) {
      console.log(; // => '01BS964AM5Z01J9MKBK64F22BQ'

Standalone Deployments

In a standalone PSPDFKit for Web installation, changes will be stored in memory until they are exported. The same persisting steps are traversed, which means we still differentiate between saved and unsaved changes, and exported Instant JSON will only contain changes that were saved. Please see the guide on importing and exporting for more information.


If nothing else is configured, PSPDFKit for Web will have auto-save enabled. This means that local changes are automatically synced. You can use Configuration#autoSaveMode to configure exactly when saving occurs.

Save Mode Use Case
default If nothing is configured, PSPDFKit.AutoSaveMode.INTELLIGENT or PSPDFKit.AutoSaveMode.IMMEDIATE will be used, based on the presence of Instant.
PSPDFKit.AutoSaveMode.IMMEDIATE Changes are saved whenever something changes, as long as they are in a valid state. This is useful for real-time updates but increases server load.
PSPDFKit.AutoSaveMode.INTELLIGENT Changes are saved whenever we detect a complete operation. This merges multiple operations into one server request and saves, for example, on deselect.
PSPDFKit.AutoSaveMode.DISABLED Changes aren’t saved by default. You can use Instance#save to trigger a save manually whenever you want.
PSPDFKit.load({ autoSaveMode: PSPDFKit.AutoSaveMode.INTELLIGENT, ... });
PSPDFKit.load({ autoSaveMode: PSPDFKit.AutoSaveMode.INTELLIGENT, ... });

Reacting to Unsaved Changes

You can check to see if there are any unsaved changes by calling Instance#hasUnsavedChanges.

If you wish to react to save state changes, you can register listeners for the document.saveStateChange event. The emitted event contains the property hasUnsavedChanges with the current value of the Instance#hasUnsavedChanges method:

instance.addEventListener("document.saveStateChange", event => {
  console.log(`Save state changed: ${event.hasUnsavedChanges}`);
instance.addEventListener("document.saveStateChange", function(event) {
  console.log("Save state changed: ".concat(event.hasUnsavedChanges));