Configuring PSPDFKitView properties

The configuration property of a PSPDFKitView is of type PDFConfiguration and defines its behavior. Here’s an example showing how you can set your PSPDFKitView’s configuration:

<PSPDFKitView
  document={DOCUMENT}
  configuration={{
    pageTransition: 'scrollPerSpread',
    scrollDirection: 'vertical',
    pageMode: 'single',
    showPageLabels: true,
    showThumbnailBar: 'scrollable',
    // Only stamps and square annotations will be editable; other annotations can't be selected or otherwise modified.
    editableAnnotationTypes: ['Stamp', 'Square'],
  }}
  ref="pdfView"
  fragmentTag="PDF1"
  style={{ flex: 1 }}
  pageIndex={3}
/>

You can find API documentation of the available configuration options here.

Retrieving the current configuration

The current configuration can be retrieved using the getConfiguration API available on the PSPDFKitView instance. The PDFConfiguration object can then be inspected or persisted and reapplied to a new PSPDFKitView instance to preserve the configuration:

const configuration = await this.pdfRef?.current?.getConfiguration();

Configuration options

Here’s the complete list of configuration options supported by each platform. Note that some options are only supported on a single platform — that’s because of differences in the behavior of both of these platforms. Options that work on only one platform are prefixed with the appropriate platform name: android or iOS. The options, grouped roughly by category, are shown below.

Document interaction options

Configuration OptionData TypePossible ValuesiOSAndroidDocumentation
scrollDirectionStringhorizontal, vertical✅✅Configures the direction of page scrolling in the document view.
pageTransitionStringscrollPerSpread, scrollContinuous, curl✅✅Configures the page scrolling mode. Note that curl mode is only available for iOS and will be ignored on Android.
documentPasswordString
✅✅The password to unlock the document.
enableTextSelectionBooleantrue / false✅✅Allow / disallow text selection.
autosaveEnabledBooleantrue / false✅✅Determines whether PSPDFKit should save automatically in response to certain UI triggers, such as the app entering the background or the view disappearing.
disableAutomaticSavingBooleantrue / false✅✅Determines whether PSPDFKit should save automatically in response to certain UI triggers, such as the app entering the background or the view disappearing.
signatureSavingStrategyStringalwaysSave, neverSave, saveIfSelected✅✅Determines whether signatures should be saved after creation.
iOSShouldScrollToChangedPageBooleantrue / false✅❌Scrolls to the affected page during an undo / redo operation.
iOSScrollViewInsetAdjustmentStringnone, fixedElements, allElements✅❌Sets the scroll view inset adjustment mode.
iOSFormElementZoomEnabledBooleantrue / false✅❌Option to automatically focus on selected form elements.
iOSImageSelectionEnabledBooleantrue / false✅❌Allow / disallow image selection.
iOSTextSelectionShouldSnapToWordBooleantrue / false✅❌Configure if text selection should snap to words.
iOSFreeTextAccessoryViewEnabledBooleantrue / false✅❌Shows a toolbar with text editing options above the keyboard while editing free text annotations.
iOSInternalTapGesturesEnabledBooleantrue / false✅❌Enable / disable all internal gesture recognizers.
iOSAllowBackgroundSavingBooleantrue / false✅❌Determines whether automatic saving should happen on a background thread.
iOSMinimumZoomScalefloat
✅❌Minimum zoom scale for the scroll view.
iOSMaximumZoomScalefloat
✅❌Maximum zoom scale for the scroll view.
iOSDoubleTapActionStringnone, zoom, smartZoom✅❌The action that happens when the user double taps somewhere in the document.
iOSTextSelectionModeStringregular, simple, automatic✅❌Defines how the text is selected.
iOSTypesShowingColorPresetsSetnone, undefined, all, Link, Highlight, Underline, Squiggly, StrikeOut, Text, Caret, FreeText, Ink, Square, Circle, Line, Signature, Stamp, Eraser, Image, Widget, FileAttachment, Sound, Polygon, PolyLine, RichMedia, Screen, Popup, Watermark, TrapNet, 3D, Redact✅❌Shows a custom cell with configurable color presets for the provided annotation types.

Document presentation options

Configuration OptionData TypePossible ValuesiOSAndroidDocumentation
pageModeStringsingle, double, automatic✅✅Configure the page mode.
firstPageAlwaysSingleBooleantrue / false✅✅Option to show the first page separately.
showPageLabelsBooleantrue / false✅✅Displays the current page number.
documentLabelEnabledBooleantrue / false✅✅Shows an overlay displaying the document name.
spreadFittingBooleantrue / false✅✅Controls the page fitting mode. adaptive mode only works on iOS and has no effect on Android.
invertColorsBooleantrue / false✅✅Inverts the document color if true.
androidGrayScaleBooleantrue / false❌✅Converts the document colors to grayscale.
iOSClipToPageBoundariesBooleantrue / false✅❌Option to clip content to page boundaries.
iOSBackgroundColorUIColor
✅❌Background color behind the page view.
iOSRenderAnimationEnabledBooleantrue / false✅❌Shows a UIActivityIndicatorView in the top-right corner while the page is rendering.
iOSRenderStatusViewPositionStringtop, centered✅❌Position of the render status view.
iOSAllowedAppearanceModesStringdefault, sepia, night, all✅❌Allowed appearance modes for BrightnessViewController.

User interface options

Configuration OptionData TypePossible ValuesiOSAndroidDocumentation
userInterfaceViewModeStringautomatic, automaticBorderPages, automaticNoFirstLastPage, always, alwaysVisible, alwaysHidden, never✅✅Configures the user interface visibility.
inlineSearchBooleantrue / false✅✅Sets the type of search bar to be inline or modular.
immersiveModeBooleantrue / false✅✅Hides the user interface if set to true.
toolbarTitleString
✅✅Sets the title of the toolbar. Note: For iOS, you need to set documentLabelEnabled, iOSUseParentNavigationBar, and iOSAllowToolbarTitleChange to false in your configuration before setting the custom title.
iOSShouldHideUserInterfaceOnPageChangeBooleantrue / false✅❌Option to hide / show the user interface when changing pages.
iOSShouldShowUserInterfaceOnViewWillAppearBooleantrue / false✅❌Option to hide / show the user interface when the page appears.
iOSShouldHideStatusBarWithUserInterfaceBooleantrue / false✅❌Option to hide / show the status bar with the user interface.
iOSShouldHideNavigationBarWithUserInterfaceBooleantrue / false✅❌Option to hide / show the navigation bar with the user interface.
iOSSearchModeStringmodal, inline✅❌Sets the type of search bar to be inline or modal.
iOSScrollOnEdgeTapEnabledBooleantrue / false✅❌Determines whether tapping on leading / trailing edges of the document view should trigger changing to the previous / next page.
iOSScrollOnEdgeTapMarginfloat
✅❌The margin in points from the view’s sides in which tapping should trigger scrolling to the previous / next page.
iOSUseParentNavigationBarBooleantrue / false✅❌Set this to true to allow this controller to access the parent navigationBar / navigationController to add custom buttons.
iOSAllowToolbarTitleChangeBooleantrue / false✅❌Allow PSPDFKit to change the title of this view controller.
iOSShouldHideStatusBarBooleantrue / false✅❌If true, the status bar will always remain hidden (regardless of the shouldHideStatusBarWithUserInterface setting).
iOSShowBackActionButtonBooleantrue / false✅❌Shows a floating back button in the lower part of the screen.
iOSShowForwardActionButtonBooleantrue / false✅❌Shows a floating forward button in the lower part of the screen.
iOSShowBackForwardActionButtonLabelsBooleantrue/ false✅❌Adds text labels representing the destination name to the back and forward buttons.
iOSSearchResultZoomScalefloat
✅❌Increase this to zoom to the search result.
iOSAdditionalScrollViewFrameInsetsUIEdgeInsets
✅❌Additional insets to apply to the document scroll view’s frame.
iOSAdditionalContentInsetsUIEdgeInsets
✅❌Additional insets to apply to the layout’s content.
iOSAllowedMenuActionsStringnone, search, define, wikipedia, speak, all✅❌May be used to customize other displayed menu actions when text is selected.
iOSSettingsOptionsSetscrollDirection, pageTransition, appearance, brightness, pageMode, spreadFitting, default, all✅❌Options that will be presented by PDFSettingsViewController. Defaults to .default.
iOSShadowEnabledBooleantrue / false✅❌Enable / disable page shadow.
iOSShadowOpacityfloat
✅❌Set the default shadowOpacity.

Thumbnail options

Configuration OptionData TypePossible ValuesiOSAndroidDocumentation
showThumbnailBarStringnone, default, floating, pinned, scrubberBar, scrollable✅✅Thumbnail bar mode controls the display of page thumbnails viewing a document.
iOSScrubberBarTypeStringhorizontal, verticalLeft, verticalRight✅❌Controls the placement of the scrubber bar.
iOSThumbnailGroupingStringautomatic, never, always✅❌Option to set the grouping of thumbnails.

Annotation, forms, and bookmark options

Configuration OptionData TypePossible ValuesiOSAndroidDocumentation
editableAnnotationTypesSetnone, undefined, all, Link, Highlight, Underline, Squiggly, StrikeOut, Text, Caret, FreeText, Ink, Square, Circle, Line, Signature, Stamp, Eraser, Image, Widget, FileAttachment, Sound, Polygon, PolyLine, RichMedia, Screen, Popup, Watermark, TrapNet, 3D, Redact✅✅Set containing the annotation types that should be editable.
enableAnnotationEditingBooleantrue / false✅✅Configuration to enable / disable editing all annotations. To selectively enable editing for specific types of annotations, use editableAnnotationTypes.
enableFormEditingBooleantrue / false✅✅Configuration to enable / disable editing forms. This can also be accomplished by adding / removing the Widget annotation type from editableAnnotationTypes.
androidShowAnnotationListActionBooleantrue / false❌✅Enables the list of annotations.
iOSShouldAskForAnnotationUsernameBooleantrue / false✅❌If true, asks the user to specify a custom annotation user name ("author") when creating a new annotation.
iOSLinkActionStringnone, alertView, openSafari, inlineBrowser, InlineWebViewController✅❌Sets the default link action for pressing on LinkAnnotations.
iOSDrawCreateModeStringseparate, mergeIfPossible✅❌Determines whether new annotations are created when strokes end.
iOSAnnotationGroupingEnabledBooleantrue / false✅❌If set to true, you can group / ungroup annotations with the multi-select tool.
iOSNaturalDrawingAnnotationEnabledBooleantrue / false✅❌Enables natural drawing for ink annotations.
iOSNaturalSignatureDrawingEnabledBooleantrue / false✅❌Enables natural drawing for signatures.
iOSAnnotationEntersEditModeAfterSecondTapEnabledBooleantrue / false✅❌Controls if a second tap to an annotation that allows inline editing enters edit mode.
iOSCreateAnnotationMenuEnabledBooleantrue / false✅❌If set to true, a long tap that ends on a page area that isn’t a text / image will show a new menu to create annotations.
iOSAnnotationAnimationDurationfloat
✅❌Overlay annotations are faded in. Set the global duration for this fade here.
iOSSoundAnnotationTimeLimitfloat
✅❌Describes the time limit for recording sound annotations, in seconds.
iOSBookmarkSortOrderStringcustom, pageBased✅❌Controls how bookmarks are displayed and managed.