Customizing the toolbar in our React Native viewer

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

Default toolbar

The default toolbar contains the following tools.

iOSAndroid

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 NutrientView. 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:

<NutrientView
  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.

iOSAndroid

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 NutrientView 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.

iOSAndroid

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:

Toolbar Button ItemiOSAndroidDescription
settingsButtonItem✅✅Shows settings button item.
annotationButtonItem✅✅Shows annotation button item.
thumbnailsButtonItem✅✅Shows thumbnails button item.
readerViewButtonItem✅✅Shows reader view button item.
searchButtonItem✅✅Shows search button item.
bookmarkButtonItem✅✅Shows bookmark button item.
printButtonItem✅✅Shows print button item.
annotationListButtonItem❌✅Shows annotation list button item.
outlineButtonItem✅✅Shows outline button item.
shareButtonItem❌✅Shows share button item.
closeButtonItem✅❌Shows close button item.
documentEditorButtonItem✅❌Shows document editor button item.
openInButtonItem✅❌Shows open in button item.
emailButtonItem✅❌Shows email button item.
messageButtonItem✅❌Shows message button item.
brightnessButtonItem✅❌Shows brightness button item.
activityButtonItem✅❌Shows activity button item.

For more details and sample code, see the ToolbarCustomization.tsx example(opens in a new tab) 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>
<NutrientView
  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.

iOSAndroid

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.