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.