Configuring PSPDFKitView Properties

The configuration prop of a PSPDFKitView defines its behavior. Here’s an example showcasing 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}
/>

πŸ’‘ Tip: You can find the implementation of the available configuration options on Android in configurationadapter.java and on iOS in RCTConvert+Configuration.m.

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.
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 βœ… ❌ 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.
androidShowSearchAction Boolean true / false ❌ βœ… Enables / disables document search functionality.
androidShowOutlineAction Boolean true / false ❌ βœ… Enables an outline menu in the activity.
androidShowBookmarksAction Boolean true / false ❌ βœ… Enables the display of bookmarks.
androidShowShareAction Boolean true / false ❌ βœ… Enables the display of share features.
androidShowPrintAction Boolean true / false ❌ βœ… Enables the printing option in the menu (if applicable) for the document and the device.
androidShowDocumentInfoView Boolean true / false ❌ βœ… Enables the display of document information.
androidShowSettingsMenu Boolean true / false ❌ βœ… Enables the display of the settings menu.
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.
androidShowThumbnailGridAction Boolean true / false ❌ βœ… Displays an action bar icon to show a grid of thumbnail pages.
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.