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}
/>
Information

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 Option Data Type Possible Values iOS Android Documentation
scrollDirection String horizontal, vertical Configures the direction of page scrolling in the document view.
pageTransition String scrollPerSpread, scrollContinuous, curl Configures the page scrolling mode. Note that curl mode is only available for iOS and will be ignored on Android.
documentPassword String - The password to unlock the document.
enableTextSelection Boolean true / false Allow / disallow text selection.
autosaveEnabled Boolean true / false Determines whether PSPDFKit should save automatically in response to certain UI triggers, such as the app entering the background or the view disappearing.
disableAutomaticSaving Boolean true / false Determines whether PSPDFKit should save automatically in response to certain UI triggers, such as the app entering the background or the view disappearing.
signatureSavingStrategy String alwaysSave, neverSave, saveIfSelected Determines whether signatures should be saved after creation.
iOSShouldScrollToChangedPage Boolean true / false Scrolls to the affected page during an undo / redo operation.
iOSScrollViewInsetAdjustment String none, fixedElements, allElements Sets the scroll view inset adjustment mode.
iOSFormElementZoomEnabled Boolean true / false Option to automatically focus on selected form elements.
iOSImageSelectionEnabled Boolean true / false Allow / disallow image selection.
iOSTextSelectionShouldSnapToWord Boolean true / false Configure if text selection should snap to words.
iOSFreeTextAccessoryViewEnabled Boolean true / false Shows a toolbar with text editing options above the keyboard while editing free text annotations.
iOSInternalTapGesturesEnabled Boolean true / false Enable / disable all internal gesture recognizers.
iOSAllowBackgroundSaving Boolean true / false Determines whether automatic saving should happen on a background thread.
iOSMinimumZoomScale float - Minimum zoom scale for the scroll view.
iOSMaximumZoomScale float - Maximum zoom scale for the scroll view.
iOSDoubleTapAction String none, zoom, smartZoom The action that happens when the user double taps somewhere in the document.
iOSTextSelectionMode String regular, simple, automatic Defines how the text is selected.
iOSTypesShowingColorPresets Set none, 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 Option Data Type Possible Values iOS Android Documentation
pageMode String single, double, automatic Configure the page mode.
firstPageAlwaysSingle Boolean true / false Option to show the first page separately.
showPageLabels Boolean true / false Displays the current page number.
documentLabelEnabled Boolean true / false Shows an overlay displaying the document name.
spreadFitting Boolean true / false Controls the page fitting mode. adaptive mode only works on iOS and has no effect on Android.
invertColors Boolean true / false Inverts the document color if true.
androidGrayScale Boolean true / false Converts the document colors to grayscale.
iOSClipToPageBoundaries Boolean true / false Option to clip content to page boundaries.
iOSBackgroundColor UIColor - Background color behind the page view.
iOSRenderAnimationEnabled Boolean true / false Shows a UIActivityIndicatorView in the top-right corner while the page is rendering.
iOSRenderStatusViewPosition String top, centered Position of the render status view.
iOSAllowedAppearanceModes String default, sepia, night, all Allowed appearance modes for BrightnessViewController.

User interface options

Configuration Option Data Type Possible Values iOS Android Documentation
userInterfaceViewMode String automatic, automaticBorderPages, automaticNoFirstLastPage, always, alwaysVisible, alwaysHidden, never Configures the user interface visibility.
inlineSearch Boolean true / false Sets the type of search bar to be inline or modular.
immersiveMode Boolean true / false Hides the user interface if set to true.
toolbarTitle String - 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.
iOSShouldHideUserInterfaceOnPageChange Boolean true / false Option to hide / show the user interface when changing pages.
iOSShouldShowUserInterfaceOnViewWillAppear Boolean true / false Option to hide / show the user interface when the page appears.
iOSShouldHideStatusBarWithUserInterface Boolean true / false Option to hide / show the status bar with the user interface.
iOSShouldHideNavigationBarWithUserInterface Boolean true / false Option to hide / show the navigation bar with the user interface.
iOSSearchMode String modal, inline Sets the type of search bar to be inline or modal.
iOSScrollOnEdgeTapEnabled Boolean true / false Determines whether tapping on leading / trailing edges of the document view should trigger changing to the previous / next page.
iOSScrollOnEdgeTapMargin float - The margin in points from the view’s sides in which tapping should trigger scrolling to the previous / next page.
iOSUseParentNavigationBar Boolean true / false Set this to true to allow this controller to access the parent navigationBar / navigationController to add custom buttons.
iOSAllowToolbarTitleChange Boolean true / false Allow PSPDFKit to change the title of this view controller.
iOSShouldHideStatusBar Boolean true / false If true, the status bar will always remain hidden (regardless of the shouldHideStatusBarWithUserInterface setting).
iOSShowBackActionButton Boolean true / false Shows a floating back button in the lower part of the screen.
iOSShowForwardActionButton Boolean true / false Shows a floating forward button in the lower part of the screen.
iOSShowBackForwardActionButtonLabels Boolean true/ false Adds text labels representing the destination name to the back and forward buttons.
iOSSearchResultZoomScale float - Increase this to zoom to the search result.
iOSAdditionalScrollViewFrameInsets UIEdgeInsets - Additional insets to apply to the document scroll view’s frame.
iOSAdditionalContentInsets UIEdgeInsets - Additional insets to apply to the layout’s content.
iOSAllowedMenuActions String none, search, define, wikipedia, speak, all May be used to customize other displayed menu actions when text is selected.
iOSSettingsOptions Set scrollDirection, pageTransition, appearance, brightness, pageMode, spreadFitting, default, all Options that will be presented by PDFSettingsViewController. Defaults to .default.
iOSShadowEnabled Boolean true / false Enable / disable page shadow.
iOSShadowOpacity float - Set the default shadowOpacity.

Thumbnail options

Configuration Option Data Type Possible Values iOS Android Documentation
showThumbnailBar String none, default, floating, pinned, scrubberBar, scrollable Thumbnail bar mode controls the display of page thumbnails viewing a document.
iOSScrubberBarType String horizontal, verticalLeft, verticalRight Controls the placement of the scrubber bar.
iOSThumbnailGrouping String automatic, never, always Option to set the grouping of thumbnails.

Annotation, forms, and bookmark options

Configuration Option Data Type Possible Values iOS Android Documentation
editableAnnotationTypes Set none, 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.
enableAnnotationEditing Boolean true / false Configuration to enable / disable editing all annotations. To selectively enable editing for specific types of annotations, use editableAnnotationTypes.
enableFormEditing Boolean true / false Configuration to enable / disable editing forms. This can also be accomplished by adding / removing the Widget annotation type from editableAnnotationTypes.
androidShowAnnotationListAction Boolean true / false Enables the list of annotations.
iOSShouldAskForAnnotationUsername Boolean true / false If true, asks the user to specify a custom annotation user name ("author") when creating a new annotation.
iOSLinkAction String none, alertView, openSafari, inlineBrowser, InlineWebViewController Sets the default link action for pressing on LinkAnnotations.
iOSDrawCreateMode String separate, mergeIfPossible Determines whether new annotations are created when strokes end.
iOSAnnotationGroupingEnabled Boolean true / false If set to true, you can group / ungroup annotations with the multi-select tool.
iOSNaturalDrawingAnnotationEnabled Boolean true / false Enables natural drawing for ink annotations.
iOSNaturalSignatureDrawingEnabled Boolean true / false Enables natural drawing for signatures.
iOSAnnotationEntersEditModeAfterSecondTapEnabled Boolean true / false Controls if a second tap to an annotation that allows inline editing enters edit mode.
iOSCreateAnnotationMenuEnabled Boolean true / 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.
iOSAnnotationAnimationDuration float - Overlay annotations are faded in. Set the global duration for this fade here.
iOSSoundAnnotationTimeLimit float - Describes the time limit for recording sound annotations, in seconds.
iOSBookmarkSortOrder String custom, pageBased Controls how bookmarks are displayed and managed.