Saving PDF Annotations

PSPDFKit for Web allows making changes to documents in these two fundamental ways:

This article explains the annotation saving mechanism. Refer to the Save a Document guides to learn more about document saving itself.

The annotation saving mechanism depends on whether PSPDFKit for Web is deployed as server-backed or standalone.


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. You can learn more about this option in our Auto-Save guide.

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.

ℹ️ Note: Each change sent to the server requires a unique ID. If you need to reference the annotation ID before it’s created (for example, when creating form fields with their widgets), a suitable ULID can be generated via PSPDFKit#generateInstantId().

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'

Before annotations are saved, annotations.willSave is emitted. When this event occurs, you can be sure we’ll 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.


In a PSPDFKit for Web installation that’s deployed as standalone, annotations will be stored in memory until they’re exported. Please see the guide on exporting and importing XFDF, Instant JSON or using PSPDFKit Server for more information.

Standalone deployments have the same annotation persistence steps as server-backed deployments. This means we still differentiate between saved and unsaved annotations in standalone, and the exported Instant JSON will only contain annotations that are saved. You can configure the auto-save behavior by the instantiation configuration option, Configuration#autoSaveMode. Learn more about this option in our Auto-Save guide.