Annotation-Saving Mechanism

Server-Backed Deployments

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

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 to the annotation before the server responds. If you’d like to ensure a new annotation has been saved by the server, you can use Instance#ensureChangesSaved:

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'

Before annotations are saved, annotations.willSave is emitted. When this event occurs, you can be sure we will commit changes to the underlying backend. As an example, this event can be used to display a loading indicator.

After the server responds to our changes, annotations.didSave is emitted. This event will always follow annotations.willSave.

Standalone Deployments

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


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

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 Annotations are saved whenever something changes, so long as they are in a valid state. This is useful for real-time updates but increases server load.
PSPDFKit.AutoSaveMode.INTELLIGENT Annotations 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 Annotations 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, ... });