2022.3 Migration Guide

PSPDFKit for Web 2022.3 introduces some new APIs and includes several bug fixes. We recommend verifying your implementation to check if it needs updating.

Notable Changes

  • (#33563) Updates the behavior of note, comment, and annotation note icons to keep dimensions persistent across zoom levels.

Note, comment, and annotation note icons used to resize across zoom levels. This behavior, although consistent with how annotations in general are rendered, made interacting with these icons difficult at some zoom levels, which in turn made the icon too small to access or too big that it concealed parts of the document.

To better align PSPDFKit for Web with other PSPDFKit platforms and other viewers, as well as to accommodate customer requests, we updated the note, comment, and annotation note icons to keep their dimensions persistent across zoom levels.

If you need to keep the former behavior, you can listen to the viewState.zoom.change event and resize the bounding box of note annotations by multiplying their width and height by the current zoom level. You can also adjust their top and left coordinates accordingly.

Contact support if you need any help with your use case.

  • (#32553) Fixes an issue where we didn’t register an annotationPresets.update event when changing the ink eraser width.

Previously changing the width of the ink eraser tool didn’t trigger an annotationPresets.update event, but now it does.

The ink preset was updated to also support specifying an inkEraserWidth value that will determine the width of the ink eraser tool in the UI:

const annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.ink = {
  inkEraserWidth: 40

Setting the default ink eraser width via PSPDFKit.Options.DEFAULT_INK_ERASER_CURSOR_WIDTH is now deprecated.

  • (#32893) Adds support for customizing the color pickers for individual annotation properties.

This new API allows users to pass a configuration for each color dropdown rendered in the annotation toolbars. See configuration#annotationToolbarColorPreset. This deprecates Options.COLOR_PRESETS. With this release, using Options.COLOR_PRESETS will log a warning, but it’ll be removed in the next major release.

Please use the new annotationToolbarColorPreset to pass a custom color array to the color dropdown:

  annotationToolbarColorPreset: function () {
    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: "Deep Blue"
          color: new PSPDFKit.Color({ r: 243, g: 149, b: 0 }),
          localization: {
            id: "orange",
            defaultMessage: "Orange"
  • (#34921) Updating form field values has always been possible using instance.setFormFieldValues(). However, with the Form Designer license component, it was also possible (involuntarily) by updating the form field itself:

await instance.update(formField.set("value", "New value"));

Even though this approach seemed to work in most cases, it opens the door to multiple potential race conditions where form fields are updated in a way that invalidates the last form field value set, either by the API or by users.

Updating the form field value this way has been disabled, and now the only way to do it is through the corresponding method, to which you should change your implementation if it used to rely on the above approach:

await instance.setFormFieldValues({
  [formField.name]: "New value"

More information can be found in our guides and in our API description. For a full list of changes, please check out the changelog.

Migrate PSPDFKit Server

For more information, please take a look at the PSPDFKit Server 2022.3 Migration Guide.