Using Annotation Presets

Annotation presets (PSPDFKit.AnnotationPreset) are preconfigured settings for annotation buttons. They allow you to, for example, set the default color of an ink annotation.

PSPDFKit.AnnotationPreset

Annotation presets are modified either when a user changes the settings using the annotation toolbar, or by programmatically using the API function PSPDFKit.setAnnotationPresets. You can opt out of the updates made using the toolbar by preventing them in the PSPDFKit.AnnotationPresetsUpdateEvent handler.

PSPDFKit for Web includes default annotation presets PSPDFKit.defaultAnnotationPresets for all the annotation buttons and their variants. These default presets can be overridden in the initial configuration before loading a PDF instance:

Copy
1
2
3
4
5
const annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.ink = {
  strokeWidth: 10
};
PSPDFKit.load({ annotationPresets });
Copy
1
2
3
4
5
var annotationPresets = PSPDFKit.defaultAnnotationPresets;
annotationPresets.ink = {
  strokeWidth: 10
};
PSPDFKit.load({ annotationPresets: annotationPresets });

Annotation presets can also be modified after the instance has been loaded.

In the example below, the line item preset is modified so that line annotations have a black color by default. If the user modifies the annotation settings via the toolbar, the corresponding annotation preset is updated, so these changes are persisted in the annotation preset by default. Preset updates can be prevented by intercepting annotationPresets.update and opting out of the update with event.preventDefault():

Copy
1
2
3
4
5
6
7
8
9
10
instance.setAnnotationPresets(presets => {
  presets.line = {
    ...presets.line,
    strokeColor: new PSPDFKit.Color({ r: 0, g: 0, b: 0 })
  };
  return presets;
});
instance.addEventListener("annotationPresets.update", event => {
  event.preventDefault();
});
Copy
1
2
3
4
5
6
7
8
9
instance.setAnnotationPresets(function(presets) {
  presets.line = Object.assign(presets.line, {
    strokeColor: new PSPDFKit.Color({ r: 0, g: 0, b: 0 })
  });
  return presets;
});
instance.addEventListener("annotationPresets.update", function(event) {
  event.preventDefault();
});

Annotation button variants can be modified as well. In this example, we modify the preset for the arrow variant of PSPDFKit.Annotations#LineAnnotation so that it uses a thicker stroke and a different title:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
instance.setAnnotationPresets(presets => {
  presets.thick = {
    ...presets.arrow,
    strokeWidth: 15
  };
  return presets;
});
instance.setToolbarItems(items => {
  return items.map(i => {
    if (i.type === "arrow") {
      return {
        ...i,
        preset: "thick",
        title: "My thick arrow"
      };
    }
    return i;
  });
});
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
instance.setAnnotationPresets(function(presets) {
  presets.thick = Object.assign(presets.arrow, { strokeWidth: 15 });
  return presets;
});
instance.setToolbarItems(function(items) {
  return items.map(function(i) {
    if (i.type === "arrow") {
      return Object.assign(i, {
        preset: "thick",
        title: "My thick arrow"
      });
    }
    return i;
  });
});

Custom annotation presets can also be created and used by annotation toolbar items (PSPDFKit.ToolbarItem). In the example below, a custom preset is created and associated with the line annotation toolbar item:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
instance.setAnnotationPresets(presets => ({
  ...presets,
  customPreset: {
    strokeWidth: 15
  }
}));
instance.setToolbarItems(items =>
  items.map(
    item =>
      item.type === "line" ? { ...item, preset: "customPreset" } : item
  )
);
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
instance.setAnnotationPresets(function(presets) {
  presets.customPreset = {
    strokeWidth: 15
  };
  return presets;
});
instance.setToolbarItems(function(items) {
  return items.map(function(item) {
    if (item.type === "line") {
      item.preset = "customPreset";
    }
    return item;
  });
});

Please refer to the API documentation to learn more about annotation presets.