Configuring PDF View Properties

The configuration property for PspdfkitWidget enables you to customize various properties of the PDF view. Here’s an example showcasing how you can set your PDF view’s configuration:

// First copy the document from assets to the temporary directory.
PspdfkitWidget(
	documentPath: document.path,
	configuration: PdfConfiguration(
		toolbarTitle: 'PSPDFKit Flutter Example',
		scrollDirection: PspdfkitScrollDirection.horizontal,
		pageLayoutMode: PspdfkitPageLayoutMode.single,
		pageTransition: PspdfkitPageTransition.scrollContinuous,
		spreadFitting: PspdfkitSpreadFitting.fit,
		immersiveMode: false,
		showPageLabels: true,
		showActionNavigationButtons: true,
		userInterfaceViewMode:
			PspdfkitUserInterfaceViewMode.automatic,
		androidShowSearchAction: true,
		inlineSearch: false,
		showThumbnailBar: PspdfkitThumbnailBarMode.floating,
		androidShowThumbnailGridAction: true,
		androidShowOutlineAction: true,
		androidShowAnnotationListAction: true,
		documentLabelEnabled: false,
		invertColors: false,
		androidGrayScale: false,
		startPage: 2,
		enableAnnotationEditing: true,
		enableTextSelection: false,
		androidShowBookmarksAction: false,
		androidEnableDocumentEditor: false,
		androidShowShareAction: true,
		androidShowPrintAction: false,
		androidShowDocumentInfoView: true,
		appearanceMode: PspdfkitAppearanceMode.defaultMode,
		androidDefaultThemeResource: 'PSPDFKit.Theme.Example',
		iOSRightBarButtonItems: [
			'thumbnailsButtonItem',
			'activityButtonItem',
			'searchButtonItem',
			'annotationButtonItem'
		],
		iOSLeftBarButtonItems: ['settingsButtonItem'],
		iOSAllowToolbarTitleChange: false,
		firstPageAlwaysSingle: true,
		enableInstantComments: true,
		webConfiguration: PdfWebConfiguration(
			allowPrinting: false,
			disableForms: false,
			showAnnotationNotes: true,
			showSignatureValidationStatus:
				ShowSignatureValidationStatusMode.ifSigned,
			sideBarMode: PspdfkitSidebarMode.annotations,
			spreadSpacing: 20,
			enableClipboardActions: true,
			autoSaveMode: PspdfkitAutoSaveMode.disabled,
		)),
	);

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 for Android and iOS. Meanwhile, for Web, they’re grouped into the webConfiguration property. The options, grouped by category, are shown below.

Document Interaction Options

Configuration Option Data Type Possible Values iOS Android Web Description
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.

Document Presentation Options

Configuration Option Data Type Possible Values iOS Android Web Description
pageMode String single, double, automatic ✅ ✅ ✅ Configure the page mode.
spreadFitting String fit, fill, adaptive ✅ ✅ ✅ Controls the page fitting mode. adaptive mode only works on iOS and has no effect on Android.
showPageLabels Boolean true / false ✅ ✅ ❌ Displays the current page number.
startPage Integer - ✅ ✅ ✅ Configures the starting page number.
documentLabelEnabled Bool true / false ✅ ✅ ✅ Shows an overlay displaying the document name.
firstPageAlwaysSingle Boolean true / false ✅ ✅ ❌ Option to show the first page separately.
invertColors Boolean true / false ✅ ✅ ✅ Inverts the document color if true.
password String - ✅ ✅ ✅ The password needed to unlock the document.
androidGrayScale Boolean true / false ❌ ✅ ❌ Converts the document colors to grayscale.

User Interface Options

Configuration Option Data Type Possible Values iOS Android Web Description
inlineSearch Boolean true / false ✅ ✅ ❌ Sets the type of search bar to be inline or modular.
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.
showActionNavigationButtons Boolean true / false ✅ ✅ ❌ Show action navigation buttons.
userInterfaceViewMode String automatic, automaticBorderPages, automaticNoFirstLastPage, always, alwaysVisible, alwaysHidden, never ✅ ✅ ✅ Configures the user interface visibility.
immersiveMode Boolean true / false ✅ ✅ ❌ Hides the user interface if set to true.
appearanceMode String default, night, sepia ✅ ✅ ✅ Sets the appearance mode for the document.
settingsMenuItems [Array of String] pageTransition, scrollDirection, androidTheme, iOSAppearance, androidPageLayout, iOSPageMode, iOSSpreadFitting, androidScreenAwake, iOSBrightness ✅ ✅ ❌ Options that will be presented in the settings menu. The options prefixed with iOS or Android only work on the respective platform. Options without any prefix work on both platforms.
androidShowSearchAction Boolean true / false ❌ ✅ ❌ Enables / disables document search functionality. For iOS, add searchButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidShowOutlineAction Boolean true / false ❌ ✅ ❌ Enables / disables outline menu in the activity. For iOS, add outlineButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidShowBookmarksAction Boolean true / false ❌ ✅ ❌ Enables / disables the bookmark list. For iOS, add bookmarkButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidShowShareAction Boolean true / false ❌ ✅ ❌ Enables the display of share features. For iOS, add activityButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidShowPrintAction Boolean true / false ❌ ✅ ❌ Enables the printing option in the menu, if applicable, for the document and the device. For iOS, add printButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidShowDocumentInfoView Boolean true / false ❌ ✅ ❌ Enables the display of document information. For iOS, add outlineButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidEnableDocumentEditor Boolean true / false ❌ ✅ ❌ Enables / disables the document editor button. For iOS, add documentEditorButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.
androidDarkThemeResource String - ❌ ✅ ❌ The resource string for the dark theme.
androidDefaultThemeResource String - ❌ ✅ ❌ The resource string for the default theme.
iOSLeftBarButtonItems [Array of String] closeButtonItem, outlineButtonItem, searchButtonItem, thumbnailsButtonItem, documentEditorButtonItem, printButtonItem, openInButtonItem, emailButtonItem, messageButtonItem, annotationButtonItem, bookmarkButtonItem, brightnessButtonItem, activityButtonItem, settingsButtonItem, readerViewButtonItem ✅ ❌ ❌ Set the left bar button items. For Android, set individual options such as androidShowOutlineAction, androidShowSearchAction, etc. to achieve the same functionality.
iOSRightBarButtonItems [Array of String] closeButtonItem, outlineButtonItem, searchButtonItem, thumbnailsButtonItem, documentEditorButtonItem, printButtonItem, openInButtonItem, emailButtonItem, messageButtonItem, annotationButtonItem, bookmarkButtonItem, brightnessButtonItem, activityButtonItem, settingsButtonItem, readerViewButtonItem ✅ ❌ ❌ Set the right bar button items. For Android, set individual options such as androidShowOutlineAction, androidShowSearchAction, etc. to achieve the same functionality.
iOSAllowToolbarTitleChange Boolean true / false ✅ ❌ ❌ Allow PSPDFKit to change the title of this view controller.

Thumbnail Options

Configuration Option Data Type Possible Values iOS Android Web Description
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. For iOS, add thumbnailsButtonItem to iOSLeftBarButtonItems or iOSRightBarButtonItems to achieve the same functionality.

Annotation, Form, and Bookmark Options

Configuration Option Data Type Possible Values iOS Android Web Description
enableAnnotationEditing Boolean true / false ✅ ✅ ✅ Configuration to enable / disable editing all annotations.
androidShowAnnotationListAction Boolean true / false ❌ ✅ ❌ Enables the list of annotations. For iOS, add outlineButtonItem to iOSLeftBarButtonItems, or iOSRightBarButtonItems to achieve the same functionality.

Web-Only Options

The Web-specific options are grouped into webConfiguration, which takes a PdfWebConfiguration object. The options are shown below.

Configuration Option Data Type Possible Values iOS Android Web Description
PspdfkitAutoSaveMode Boolean disabled, immediate, intelligent The auto-save mode to use.
allowPrinting Boolean true / false ❌ ❌ ✅ Whether to allow printing.
disableForms Boolean true / false ❌ ❌ ✅ Whether to disable forms.
showAnnotationNotes Boolean true / false ❌ ❌ ✅ Whether to show annotation notes.
showSignatureValidationStatus String always, ifSigned, never ❌ ❌ ✅ The mode for showing signature validation status.
sideBarMode String annotations, bookmarks, thumbnails, documentInfo, outline ❌ ❌ ✅
spreadSpacing Number - ❌ ❌ ✅ The spacing between spreads.
enableClipboardActions Boolean true / false ❌ ❌ ✅ Whether to enable clipboard actions.
interactionMode String automatic, selectionOnly, inkOnly ❌ ❌ ✅ The interaction mode to use.
sidebarMode String annotations, bookmarks, thumbnails, documentInfo, outline ❌ ❌ ✅ The sidebar mode to use.
canScrollWhileDrawing Boolean true / false ❌ ❌ ✅ Whether to allow scrolling while drawing.
keepFirstSpreadAsSinglePage Boolean true / false ❌ ❌ ✅
keepSelectedTool Boolean true / false ❌ ❌ ✅
pageSpacing Number - ❌ ❌ ✅ The spacing between pages.
pageRotation Number - ❌ ❌ ✅ The rotation of the page.
previewRedactionMode Boolean true / false ❌ ❌ ✅ Whether to preview redaction mode.
showAnnotationNotes Boolean true / false ❌ ❌ ✅ Whether to show annotation notes.
customFonts Array - ❌ ❌ ✅ An array of custom fonts to load.
customRenderers Object - ❌ ❌ ✅ Custom renderers to use.
customUIConfiguration Object - ❌ ❌ ✅ Custom UI configuration to use.
electronicSignatures Object - ❌ ❌ ✅ Electronic signatures configuration to use.
formDesignMode Boolean true / false ❌ ❌ ✅ Whether to enable form design mode.
maxMentionSuggestions Number - ❌ ❌ ✅ The maximum number of mention suggestions to show.
mentionableUsers Array - ❌ ❌ ✅ An array of mentionable users.
restrictAnnotationToPageBounds Boolean true / false ❌ ❌ ✅ Restrict annotations to page bounds.
stampAnnotationTemplates Array - ❌ ❌ ✅ An array of stamp annotation templates.
styleSheets Array - ❌ ❌ ✅ An array of style sheets to load.
theme String light, dark ❌ ❌ ✅ The web theme to use.
toolbarPlacement String top, bottom ❌ ❌ ✅ The toolbar placement to use.
zoom Number - ❌ ❌ ✅ The zoom level to use.
minDefaultZoomLevel Number - ❌ ❌ ✅ The minimum default zoom level.
maxDefaultZoomLevel Number - ❌ ❌ ✅ The maximum default zoom level.
zoomStep Number - ❌ ❌ ✅ The zoom step to use.
toolbarItems Array - ❌ ❌ ✅ An array of items to show in the toolbar.
xfdf String - ❌ ❌ ✅ The XFDF string to load into the document.
xfdfKeepCurrentAnnotations bool true / false ❌ ❌ ✅ Whether to keep the current annotations when loading XFDF.
autoCloseThreshold Number - ❌ ❌ ✅ The threshold for automatically closing the document.
baseCoreUrl String - ❌ ❌ ✅ The base URL for the PSPDFKit Core library.
baseUrl String - ❌ ❌ ✅ The base URL for Document Engine.
container String - ❌ ❌ ✅ The ID of the container element for the viewer.
disableHighQualityPrinting bool true / false ❌ ❌ ✅ Whether to disable high-quality printing.
disableMultiSelection bool true / false ❌ ❌ ✅ Whether to disable multi-selection.
disableOpenParameters bool true / false ❌ ❌ ✅ Whether to disable open parameters.
disableTextSelection bool true / false ❌ ❌ ✅ Whether to disable text selection.
disableWebAssemblyStreaming bool true / false ❌ ❌ ✅ Whether to disable WebAssembly streaming.
documentEditorFooterItems Array - ❌ ❌ ✅ An array of items to show in the document editor footer.
documentEditorToolbarItems Array - ❌ ❌ ✅ An array of items to show in the document editor toolbar.
documentId String - ❌ ❌ ✅ The ID of the document to load.
editableAnnotationTypes Array - ❌ ❌ ✅ An array of editable annotation types.
enableAutomaticLinkExtraction bool true / false ❌ ❌ ✅ Whether to enable automatic link extraction.
enableHistory bool true / false ❌ ❌ ✅ Whether to enable history.
enableServiceWorkerSupport bool true / false ❌ ❌ ✅ Whether to enable service worker support.
formFieldsNotSavingSignatures Array - ❌ ❌ ✅ An array of form fields that should not save signatures.
headless bool true / false ❌ ❌ ✅ Whether to run in headless mode.
instant bool true / false ❌ ❌ ✅ Whether to run in Instant mode (Server only).
instantJSON Object - ❌ ❌ ✅ The JSON configuration for Instant mode (Server only).
locale String - ❌ ❌ ✅ The locale to use.
maxPasswordRetries Number - ❌ ❌ ✅ The maximum number of password retries.
overrideMemoryLimit Number - ❌ ❌ ✅ The memory limit to override.
preventTextCopy bool true / false ❌ ❌ ✅ Whether to prevent text copy.
printOptions Object - ❌ ❌ ✅ The print options to use.
serverUrl String - ❌ ❌ ✅ The URL of Document Engine (Server only).
standaloneInstancesPoolSize Number - ❌ ❌ ✅ The size of the Standalone instances pool.
viewportPadding Number - ❌ ❌ ✅ The viewport padding to use.
annotationToolbarItems Array - ❌ ❌ ✅ An array of items to show in the annotation toolbar.