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:

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

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

Type:

(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.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-eraser
  16. ink-signature
  17. image
  18. stamp
  19. note
  20. text
  21. line
  22. arrow
  23. rectangle
  24. ellipse
  25. polygon
  26. polyline
  27. print
  28. search
  29. 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
  • ink-eraser
  • 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
  • ink-eraser
  • 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:

(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.
INK_ERASER PSPDFKit.InteractionMode

When this mode is activated, removing of current ink annotation points will be enabled. This transforms the page to a canvas where the cursor can remove ink annotation points by hand, as well as choose the cursor width.
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.
WIDGET PSPDFKit.InteractionMode

When this mode is activated, the selected widget annotation can be resized, moved and deleted using the pointer.

This mode is only available if the license includes editable_forms feature and the current backend supports forms editing.
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, 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. "2019.2.4").

(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) preloadWorker(configuration) → {Promise.<void>}

Preloads the standalone WASM worker.

In cases where you don't want to load a PDF right away, the first invocation of PSPDFKit.load after allowing this function to resolve will be significantly faster.

If PSPDFKit.load is called while this function has not yet resolved, then PSPDFKit.load will simply reuse the request from this function without adding any overhead.

Parameters:
Name Type Description
configuration PSPDFKit.Configuration

A configuration Object
Returns:

Promise that resolves when preloading is complete

Type
Promise.<void>
Example
// Fetches worker asynchronously
PSPDFKit.preloadWorker(configuration);
document.querySelector("#open-pdf-button").addEventListener(async () => {
  await PSPDFKit.load({ ...configuration, pdf: "my-doc.pdf" });
});

(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
    );
  }
  // ...
});