Customizing the toolbar in our React Native viewer

The main toolbar in PSPDFKit is designed to be flexible and highly configurable. This guide shows how to customize it.

Default toolbar

The default toolbar contains the following tools.

iOS	Android

Customizing the toolbar buttons

You can use the leftBarButtonItems or rightBarButtonItems props on iOS and the toolbarMenuItems prop on Android under the Toolbar object to customize the main toolbar’s buttons when loading the PSPDFKitView. The example below shows how to add the settings button as the left bar button item in the navigation bar (main toolbar) on iOS and how to customize the Android toolbar menu items:

<PSPDFKitView
	document={DOCUMENT}
	toolbar={{
		// iOS only.
		leftBarButtonItems: {
			viewMode: 'document',
			animated: true,
			buttons: ['settingsButtonItem'],
		},
		// iOS only.
		rightBarButtonItems: {
			viewMode: 'document',
			animated: true,
			buttons: [
				'searchButtonItem',
				'thumbnailsButtonItem',
				'annotationButtonItem',
			],
		},
		// Android only.
		toolbarMenuItems: {
			buttons: [
				'annotationButtonItem',
				'settingsButtonItem',
				'searchButtonItem',
				'thumbnailsButtonItem',
			],
		},
	}}
	ref="pdfView"
	fragmentTag="PDF1"
/>

The customized toolbar will look like what’s shown below.

iOS	Android

Additionally, you can use setToolbar(toolbar) to set the leftBarButtonItems or rightBarButtonItems on iOS and toolbarMenuItems on Android to customize the toolbar items after the PSPDFKitView is loaded. The example below shows how the main toolbar’s button items can be updated using a button:

<Button
	onPress={async () => {
		// Update the right bar buttons for iOS and toolbar buttons for Android.
		const toolbar = {
			// iOS only.
			rightBarButtonItems: {
				viewMode: 'document',
				animated: true,
				buttons: ['searchButtonItem', 'readerViewButtonItem'],
			},
			// Android only.
			toolbarMenuItems: {
				buttons: ['searchButtonItem', 'readerViewButtonItem'],
			},
		};
		await this.pdfRef.current?.setToolbar(toolbar);
	}}
	title="Update the right bar button items"
/>

The new customized toolbar will look like the following image.

iOS	Android

Available toolbar customization options

Due to platform differences, not all toolbar item options are available on both platforms. Below, you’ll see a table showing the options available on each platform:

For more details and sample code, see the ToolbarCustomization.tsx example from the Catalog example project.

Using custom buttons

To add a custom button to the main toolbar, you can include custom button objects inside the same leftBarButtonItems or rightBarButtonItems props on iOS and the toolbarMenuItems prop on Android, inside the Toolbar object. On iOS, the image needs to be included in your application bundle, and on Android, it needs to be specified as a drawable resource.

The id is used to uniquely identify the button when it’s tapped and the onCustomToolbarButtonTapped callback is triggered. This can be any value; however, on Android, the id also needs to be specified as a resource item inside your application’s ids.xml file:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <item name="custom_action" type="id"/>
</resources>

<PSPDFKitView
	document={DOCUMENT}
	toolbar={{
		// iOS only.
		leftBarButtonItems: {
			viewMode: 'document',
			animated: true,
			buttons: [
				'settingsButtonItem',
				{
					image: 'customImage.png', 
					id: 'myCustomButton',
				}
			],
		},
		// iOS only.
		rightBarButtonItems: {
			viewMode: 'document',
			animated: true,
			buttons: ['searchButtonItem'],
		},
		// Android only.
		toolbarMenuItems: {
			buttons: [
				'thumbnailsButtonItem',
				{
					image: 'example_toolbar_icon', 
					id: 'custom_action',
					title: 'Android title',

				}
			],
		},
	}}
	onCustomToolbarButtonTapped={(event) => {
    	Alert.alert('PSPDFKit', `Custom button tapped: ${JSON.stringify(event)}`);
	}}
	ref="pdfView"
	fragmentTag="PDF1"
/>

The customized toolbar will look like the following image, showing the custom button.

iOS	Android

When the custom button is tapped, the onCustomToolbarButtonTapped callback will be called with the id you supplied during creation. The stock PSPDFKit buttons will execute their default actions without triggering the onCustomToolbarButtonTapped callback.