Namespace: PSPDFKit

PSPDFKit

The main PSPDFKit namespace is exported in the global PSPDFKit.

Classes

Namespaces

Members

Methods

Type Definitions



Members

(static, readonly) AutoSaveMode

When working with annotations and form field values, there are multiple options when the data can get saved. The AutoSaveMode controls this behavior.

Properties:
Name Type Description
IMMEDIATE PSPDFKit.AutoSaveMode

Saves immediately whenever an attribute of the annotation changed, or whenever a form field value got updated.
INTELLIGENT PSPDFKit.AutoSaveMode

Saves annotations automatically, when the user finishes editing an annotation. For form fields, this behaves like PSPDFKit.AutoSaveMode.IMMEDIATE.
DISABLED PSPDFKit.AutoSaveMode

Never saves annotations or form field values automatically. Annotations and form field values can still be saved via PSPDFKit.Instance#saveAnnotations or PSPDFKit.Instance#saveFormFieldValues

(static, readonly) defaultAnnotationPresets: Object.<PSPDFKit.AnnotationPreset>

Returns a deep copy of an object containing the default annotation presets.

The default annotation presets for annotations include the default values for the annotation models, and can be retrieved before loading the instance.

The default annotation presets for annotation variants also include the modified properties corresponding to each annotation variant.

Used by toolbar buttons like line or arrow.

  1. arrow
  2. highlighter
  3. line
  4. rectangle
  5. ellipse
  6. polygon
  7. polyline
  8. text-highlighter
  9. ink
  10. ink-signature
  11. note
  12. text
  13. stamp
  14. image
  15. widget
  16. strikeout
  17. underline
  18. squiggle
  19. highlight
Type:
  • Object.<PSPDFKit.AnnotationPreset>

(static, readonly) defaultStampAnnotationTemplates: Array.<(PSPDFKit.Annotations.StampAnnotation|PSPDFKit.Annotations.ImageAnnotation)>

Returns a deep copy of an array containing the default stamp and image annotation templates, which are stamp annotation instances. However, image annotation templates can also be added to this Array using PSPDFKit.setStampAnnotationTemplates. Used by the stamp picker UI. Initially it contains only the following stamp annotations:

  1. Approved
  2. NotApproved
  3. Draft
  4. Final
  5. Completed
  6. Confidential
  7. ForPublicRelease
  8. NotForPublicRelease
  9. ForComment
  10. Void
  11. PreliminaryResults
  12. InformationOnly
  13. Rejected
  14. Accepted
  15. InitialHere
  16. SignHere
  17. Witness
  18. AsIs
  19. Departmental
  20. Experimental
  21. Expired
  22. Sold
  23. TopSecret
  24. Revised
  25. RejectedWithText
Type:

(static, readonly) defaultToolbarItems: Array.<PSPDFKit.Annotations.Annotation>

Returns a deep copy of an array containing the default editable annotation types.

Type:

(static, readonly) defaultToolbarItems: Array.<PSPDFKit.ToolbarItem>

Returns a deep copy of an array containing the default toolbar items ordered by PSPDFKit.ToolbarItem#type in the following way:

  1. sidebar-thumbnails
  2. sidebar-document-outline
  3. sidebar-annotations
  4. sidebar-bookmarks
  5. pager
  6. pan
  7. zoom-out
  8. zoom-in
  9. zoom-mode
  10. spacer
  11. annotate
  12. ink
  13. highlighter
  14. text-highlighter
  15. ink-signature
  16. image
  17. stamp
  18. note
  19. text
  20. line
  21. arrow
  22. rectangle
  23. ellipse
  24. polygon
  25. polyline
  26. print
  27. search
  28. debug

Please keep in mind that under some circumstances some items may be removed from the final list.

Items hidden for touch devices:

  • pan

Items hidden for touch devices when the media query (max-width: 992px) for medium devices matches:

  • zoom-out
  • zoom-in
  • zoom-mode

Please keep in mind that the media query is only added for touch devices. You can change this behavior by defining your own mediaQueries and replacing the original item. To learn more about how to do so please refer to our guide.

Items hidden for small screens (max-width: 992px)

  • text
  • ink
  • highlighter
  • text-highlighter
  • line
  • arrow
  • rectangle
  • ellipse
  • polygon
  • polyline
  • ink-signature
  • image
  • stamp
  • note

Items shown on small screens (max-width: 992px)

  • annotate

Items hidden when in read-only mode:

  • text
  • ink
  • highlighter
  • text-highlighter
  • line
  • arrow
  • rectangle
  • ellipse
  • polygon
  • polyline
  • ink-signature
  • image
  • stamp
  • note

Hidden when not in debug mode:

  • debug

Hidden by default and only available when explicitly set via the API:

  • layout-config
Type:
  • Array.<PSPDFKit.ToolbarItem>

(static, readonly) InteractionMode

Controls the current interaction mode in the viewer.

Properties:
Name Type Description
TEXT_HIGHLIGHTER PSPDFKit.InteractionMode

When this mode is activated, the creation of new highlight annotations will be enabled and the text will be highlighted as it's selected.
INK PSPDFKit.InteractionMode

When this mode is activated, the creation of new ink annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
INK_SIGNATURE PSPDFKit.InteractionMode

When this mode is activated, the creation of new ink signatures will be enabled. This this shows a dialog where it is possible to select an existing ink signature or create a new one and store it.
STAMP_PICKER PSPDFKit.InteractionMode

When this mode is activated, the stamp annotation templates picker modal UI will be shown. Once a template is selected, the new annotation is configured and created\ in the document.
STAMP_CUSTOM PSPDFKit.InteractionMode

When this mode is activated, the custom stamp annotation template editor modal UI will be shown. Once a the custom template is edited, the new custom stamp annotation will be created in the document.
SHAPE_LINE PSPDFKit.InteractionMode

When this mode is activated, the creation of new line annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it.
SHAPE_RECTANGLE PSPDFKit.InteractionMode

When this mode is activated, the creation of new rectangle annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it.
SHAPE_ELLIPSE PSPDFKit.InteractionMode

When this mode is activated, the creation of new ellipse annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
SHAPE_POLYGON PSPDFKit.InteractionMode

When this mode is activated, the creation of new polygon annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
SHAPE_POLYLINE PSPDFKit.InteractionMode

When this mode is activated, the creation of new polyline annotations will be enabled. This transforms the page to a drawable canvas and an annotation is created while drawing on it. If properties (e.g. color) or the page index changes, a new annotation is created.
NOTE PSPDFKit.InteractionMode

When this mode is activated, the creation of new note annotations will be enabled. This transforms the page to a clickable area where the annotation will be created at the position of the click.
TEXT PSPDFKit.InteractionMode

When this mode is activated, the creation of new text annotations will be enabled. This transforms the page to a clickable area where the annotation will be created at the position of the click.
PAN PSPDFKit.InteractionMode

This enables the pan tool to allow the user to navigate on a desktop browser using mouse dragging. This will disable text selection.

On a touch device, this will have no effect since panning is already the default technique for scrolling on websites.
SEARCH PSPDFKit.InteractionMode

Enables the search mode and focuses the search input field.

(static, readonly) LayoutMode

Describes how the pages will be laid out in the document view.

Properties:
Name Type Description
SINGLE PSPDFKit.LayoutMode

Pages will always be displayed in the single page mode.

This is the default mode.
DOUBLE PSPDFKit.LayoutMode

Pages will always be displayed in groups of two.
AUTO PSPDFKit.LayoutMode

Automatically sets the layout mode to PSPDFKit.LayoutMode.SINGLE or PSPDFKit.LayoutMode.DOUBLE depending on the available space.

Specifically PSPDFKit.LayoutMode.DOUBLE is chosen when the PSPDFKit container is in landscape mode and its size is greater than 992px.

This mode is a perfect fit for tablets in particular since it will automatically update the layout mode then device orientation changes.

When the dimensions of the viewport change (i.e. the browser window is resized), the view will be restored to make the current page visible.

(static, readonly) NoteIcon

Available icons for Note Annotations.

Properties:
Name Type Description
COMMENT
RIGHT_POINTER
RIGHT_ARROW
CHECK
CIRCLE
CROSS
INSERT
NEW_PARAGRAPH
NOTE
PARAGRAPH
HELP
STAR
KEY

(static) Options: Object

optional

Custom values for default options. These values will be frozen the first time PSPDFKit.load is called, and won't be modifiable after that.

Type:
  • Object
Properties:
Name Type Default Description
MIN_TEXT_ANNOTATION_SIZE number 5

Minimum size of text annotations, in pixels.
MIN_INK_ANNOTATION_SIZE number 128

Minimum size of ink annotations, in pixels.
MIN_SHAPE_ANNOTATION_SIZE number 128

Minimum size of shape annotations, in pixels.
MIN_IMAGE_ANNOTATION_SIZE number 5

Minimum size of image annotations, in pixels.
MIN_STAMP_ANNOTATION_SIZE number 10

Minimum size of stamp annotations, in pixels.
ENABLE_INK_SMOOTH_LINES boolean true

Enable smooth lines for ink annotations.
INK_EPSILON_RANGE_OPTIMIZATION number 0

Minimum range between two points for an ink annotation, in pixels.
SIGNATURE_SAVE_MODE PSPDFKit.SignatureSaveMode PSPDFKit.SignatureSaveMode.USING_UI

Saving strategy for ink signatures.
IGNORE_DOCUMENT_PERMISSIONS boolean false

Enables all the features by ignoring the document permissions.
Example

Set minimum ink annotation size.

PSPDFKit.Options.MIN_INK_ANNOTATION_SIZE = 64;
PSPDFKit.load();

(static, readonly) PrintMode

Describes mode used to print a PDF document.

Properties:
Name Type Description
DOM PSPDFKit.PrintMode

This method will render all pages of the PDF document in advance before it sends the results to the printer. This works in all major browsers and will not give your users access to the source PDF file. However, this method is CPU-bound and memory usage scales with PDF size.

Because of its reliability and cross browsers support this method is the default.

Some caveats when using this method:

  • To achieve cross-browser support, we render the resulting images into the main window. We try to hide already existing HTML by applying display: none !important. If the printed page still contains other HTML elements, make sure to apply an appropriate print stylesheet to your web app.
  • This method will produce incorrect results, when pages of the document have different sizes. Unfortunately, there's no way to work around this issue since it's a CSS limitation.
EXPORT_PDF PSPDFKit.PrintMode

This method is built to be resource efficient and to avoid having to render all pages in advance, which might balloon memory usage to multi-GB on PDFs with 100+ pages.

It supports all common browsers, however some fall back to opening the PDF file in a new tab, which might give your users unwanted access to the source files.

Google Chrome and Microsoft Internet Explorer provide the APIs required to use the native renderer, as a fallback on other browser we generate and open a PDF in a new tab. This allows users to print the PDF in a native PDF reader which can, as opposed to browser-built implementations, talk directly to the connected printer.

When using this print mode, we can not call the PSPDFKit.RenderPageCallback when printing pages.

Note: If the PDF is password-protected, we always fall back to opening the PDF in a new tab.

(static, readonly) ScrollMode

Describes mode of page scrolling in the document view - either continuous or per spread (paginated).

Properties:
Name Type Description
CONTINUOUS PSPDFKit.ScrollMode

Render all pages as a list and allow smooth scrolling.

This is the default mode.
PER_SPREAD PSPDFKit.ScrollMode

Makes scrolling only possible within a spread. Whenever this mode is activated, or pages are changed when this mode is active, the zoom mode will be reset to PSPDFKit.ZoomMode.FIT_TO_VIEWPORT.

(static, readonly) SidebarMode

Controls the current sidebar mode in the viewer.

Properties:
Name Type Description
ANNOTATIONS PSPDFKit.SidebarMode

Annotations sidebar.
BOOKMARKS PSPDFKit.SidebarMode

Bookmarks.
DOCUMENT_OUTLINE PSPDFKit.SidebarMode

Document Outline (table of contents).
THUMBNAILS PSPDFKit.SidebarMode

Thumbnails preview.

(static, readonly) SidebarPlacement

Controls the sidebar placement.

Properties:
Name Type Description
START PSPDFKit.SidebarPlacement

The sidebar is shown before the content in the reading direction. For any LTR languages this will be the left side, for RTL languages this will be the right side.
END PSPDFKit.SidebarPlacement

The sidebar is shown after the content in the reading direction. For any LTR languages this will be the right side, for RTL languages this will be the left side.

(static, readonly) SignatureSaveMode

Selects the save mode for ink signatures.

Properties:
Name Type Description
ALWAYS PSPDFKit.SignatureSaveMode

Always store new ink signatures.
NEVER PSPDFKit.SignatureSaveMode

Never store new ink signatures.
USING_UI PSPDFKit.SignatureSaveMode

Store new ink signatures if the option is selected in the UI.

(static, readonly) version

Returns the framework version (e.g. "2018.7.1").

(static, readonly) ZoomMode

A specific zoom mode that will always be applied whenever the viewport is resized.

Properties:
Name Type Description
AUTO PSPDFKit.ZoomMode

Generates a zoomLevel that will automatically align the page for the best viewing experience.
FIT_TO_WIDTH PSPDFKit.ZoomMode

Uses a zoomLevel that will fit the width of the broadest page into the viewport. The height might overflow.
FIT_TO_VIEWPORT PSPDFKit.ZoomMode

Uses a zoomLevel that will fit the current page into the viewport completely.

Methods

(static) load(configuration) → {Promise.<PSPDFKit.Instance, PSPDFKit.Error>}

Creates a new PSPDFKit instance.

Returns a Promise resolving to a new PSPDFKit.Instance, or rejecting with a PSPDFKit.Error.

It requires a configuration object. When the configuration is invalid, the promise will be rejected with a PSPDFKit.Error.

Parameters:
Name Type Description
configuration PSPDFKit.Configuration

A configuration Object
Returns:

Promise that resolves in an PSPDFKit.Instance

Type
Promise.<PSPDFKit.Instance, PSPDFKit.Error>
Examples

Load PSPDFKit for Web Server

PSPDFKit.load({
  authPayload: { jwt: "xxx.xxx.xxx" },
  container: ".foo",
  documentId: "85203",
  instant: true,
}).then((instance) => {
  console.log("Successfully mounted PSPDFKit", instance);
}).catch((error) => {
  console.error(error.message);
})

Load PSPDFKit for Web Standalone

PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
  licenseKey: "YOUR_LICENSE_KEY",
}).then((instance) => {
  console.log("Successfully mounted PSPDFKit", instance);
}).catch((error) => {
  console.error(error.message);
})

(static) unload(target) → {boolean}

Unloads an existing PSPDFKit instance.

It requires an target parameter that is a CSS selector, an HTMLElement or the reference to a PSPDFKit.Instance returned by PSPDFKit.load.

Parameters:
Name Type Description
target HTMLElement | string | PSPDFKit.Instance

A target to unload
Throws:

Will throw an error when the target is invalid but will work when it does not have a mounted PSPDFKit for Web instance.

Type
PSPDFKit.Error
Returns:

When true, an instance of PSPDFKit for Web was unmounted.

Type
boolean
Examples

Unload PSPDFKit for Web using an instance

let instance = null;
PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
}).then((i) => {
  instance = i
})
.then(() => {
  // Unload the given instance
  PSPDFKit.unload(instance)
}).catch((error) => {
  console.error(error.message);
})

Unload PSPDFKit for Web using a CSS selector

PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
})
.then(() => {
  // Unload the given instance
  PSPDFKit.unload(".foo")
})

Unload PSPDFKit for Web using an HTMLElement

PSPDFKit.load({
  pdf: "/sales-report.pdf",
  container: ".foo",
})
.then(() => {
  // Unload the given instance
  PSPDFKit.unload(document.querySelector(".foo"))
})

(static) viewStateFromOpenParameters() → {PSPDFKit.ViewState}

Merges the properties extracted from the location.hash into the PSPDFKit.ViewState.

Properties will be extracted following the PDF Open Parameters spec.

Currently, we only support the page parameter.

Parameters:
Type Description
PSPDFKit.ViewState
Returns:
Type
PSPDFKit.ViewState

Type Definitions

AnnotationTooltipCallback(annotation)

This callback is called whenever an annotation gets selected and can be used to define and return an array of PSPDFKit.ToolItem that will be rendered in a tooltip for the given annotation.

If the callback returns an empty array then PSPDFKit won't show any tooltip for the selected annotation.

Parameters:
Name Type Description
annotation Annotation

The selected annotation.
Example

Register a AnnotationTooltipCallback handler to show a tooltip for text annotations only.

PSPDFKit.load({
  annotationTooltipCallback: function(annotation) {
    if (annotation instanceof PSPDFKit.Annotations.TextAnnotation) {
      var toolItem = {
        type: 'custom',
        title: 'tooltip item for text annotations',
        id: 'item-text-tooltip-annotation',
        className: 'TooltipItem-Text',
        onPress: function () {
          console.log(annotation)
        }
      }
      return [toolItem]
    } else {
      return []
    }
  }
  // ...
});

IsEditableAnnotationCallback(annotation)

This callback defines which annotations are read-only. This callback will receive the Annotation a user wants to modify and by returning true or false you can define if the annotation should be read-only (true) or modifiable (false).

For more information, see PSPDFKit.Configuration#isEditableAnnotation.

Parameters:
Name Type Description
annotation Annotation
Example

Only allow the modification of annotations from the same author

PSPDFKit.load({
  isEditableAnnotation: function(annotation) {
    return annotation.creatorName !== myCurrentUser.name;
  },
  // ...
});

RenderPageCallback(canvas, pageIndex, size)

This callback is called whenever a page is rendered or printed (only for PSPDFKit.PrintMode.DOM). You can use it to render watermarks on the page.

Make sure that the rendering commands are as efficient as possible as they might be invoked multiple times per page (once per tile).

For more information, see PSPDFKit.Configuration#renderPageCallback.

Parameters:
Name Type Description
canvas CanvasRenderingContext2D

A 2D <canvas/> rendering context.
pageIndex number

The current page index, starting with 0 for the first page.
size PSPDFKit.Geometry.Size

The size of the page that you're drawing at. The canvas is already scaled accordingly.
Example

Register a RenderPageCallback handler at configuration time.

PSPDFKit.load({
  renderPageCallback: function(ctx, pageIndex, pageSize) {
    ctx.beginPath();
    ctx.moveTo(0, 0);
    ctx.lineTo(pageSize.width, pageSize.height);
    ctx.stroke();

    ctx.font = "30px Comic Sans MS";
    ctx.fillStyle = "red";
    ctx.textAlign = "center";
    ctx.fillText(
      `This is page ${pageIndex + 1}`,
      pageSize.width / 2,
      pageSize.height / 2
    );
  }
  // ...
});