SDK

Low-Code

Workflow

DWS API

Customizing the toolbar in our Flutter viewer

The main toolbar in Nutrient is designed to be flexible and configurable. This guide details how to customize the main toolbar.

Nutrient provides several preconfigured buttons that can be used for actions such as annotation editing, sharing a document, searching, opening the bookmarks view, etc. These buttons can be configured to be shown or hidden on the main toolbar, according to your use case. The way to customize these buttons is slightly different on Android, iOS, and Web.

Below are examples showing how to customize the main toolbar.

Android and iOS

await PspdfkitWidget(documentPath: document.path, configuration: PdfConfiguration(

    // Common options:
    enableAnnotationEditing: true, // Annotation item on the main toolbar.
    toolbarTitle: 'Custom Title',
    iOSAllowToolbarTitleChange: false,

    // iOS-specific options:
    iOSRightBarButtonItems: [ // List of buttons to show on the right side of the main toolbar.
        'thumbnailsButtonItem',
        'activityButtonItem',
        'annotationButtonItem',
        'searchButtonItem'
    ],
    iOSLeftBarButtonItems: [ // List of buttons to show on the left side of the main toolbar. (Only one item supported.)
        'settingsButtonItem'
    ],

    // Android-specific options:
    androidShowSearchAction: true, // Search action on the main toolbar.
    androidShowThumbnailGridAction: true, // Document editor action on the main toolbar.
    androidShowShareAction: true, // Share action on the main toolbar.
    androidShowPrintAction: true, // Print item on the main toolbar and inside the sharing sheet.
    androidEnableDocumentEditor: true, // Enable document editing in thumbnail view.
));

The image below shows how the toolbar looks after customization.

Android
iOS

Custom main toolbar items

For more advanced customization, you can add custom toolbar items to create your own unique toolbar experience. The customToolbarItems parameter allows you to define your own toolbar buttons with custom icons, positioning, and tap handling:

import 'package:pspdfkit_flutter/pspdfkit.dart';
import 'dart:io' show Platform;
import 'package:flutter/material.dart';

PspdfkitWidget(
  documentPath: 'path/to/document.pdf',
  customToolbarItems: [
    // Back button (left side on iOS).
    CustomToolbarItem(
      identifier: 'action_back',
      title: 'Back',
      iconName: Platform.isIOS ? 'chevron.left' : 'arrow_back',
      position: ToolbarPosition.iosLeft,
     isAndroidBackButton: true,
    ),
    // Highlight button (main toolbar).
    CustomToolbarItem(
      identifier: 'action_highlight',
      title: 'Highlight',
      iconName: Platform.isIOS ? 'highlighter' : 'highlight_icon',
      iconColor: Colors.amber,  // Using Flutter Colors
      position: ToolbarPosition.primary,
    ),
    // Share button (may be in overflow menu on Android).
    CustomToolbarItem(
      identifier: 'action_share',
      title: 'Share',
      iconName: Platform.isIOS ? 'square.and.arrow.up' : 'share',
      position: ToolbarPosition.secondary,
    ),
  ],
  onCustomToolbarItemTapped: (identifier) {
    switch (identifier) {
      case 'action_back':
        Navigator.of(context).pop();
        break;
      case 'action_highlight':
        // Show highlight options or activate highlighting mode.
        _pspdfkitWidgetController?.enterAnnotationCreationMode(
          AnnotationType.highlight
        );
        break;
      case 'action_share':
        // Share document.
        _shareDocument();
        break;
    }
  },
)

Toolbar item positioning

The CustomToolbarItem class provides a position parameter that controls where your toolbar item appears:

Position Value Behavior
primary ToolbarPosition.primary Main toolbar (Android) / Right side (iOS)
secondary ToolbarPosition.secondary Overflow menu (Android) / Right side (iOS)
iosLeft ToolbarPosition.iosLeft Left side of navigation bar (iOS)

Adding custom icons

To use custom icons with your toolbar items, you’ll need to implement them differently on Android and iOS.

Android

  1. Add icon files (vector drawables recommended) to your drawable resources:

    android/app/src/main/res/drawable/my_icon.xml  // Vector drawable.
android/app/src/main/res/drawable/my_icon.png  // Or bitmap image.

  2. Reference them in code using the file name without an extension:

    iconName: 'my_icon'

iOS

  1. Use SF Symbols (recommended) by providing the symbol name:

    iconName: 'bookmark.fill'  // SF Symbol name.

  2. Or use custom images from your asset catalog:

    • Add images to Assets.xcassets in Xcode.

    • Set Render As to Template Image for tinting.

    • Reference the image set name — iconName: 'custom_icon'.

Handling click events

Implement the onCustomToolbarItemTapped callback to respond to user interactions with your custom toolbar items:

onCustomToolbarItemTapped: (identifier) {
  switch (identifier) {
    case 'action_highlight':
      // Activate highlighting annotation mode.
      _pspdfkitWidgetController?.enterAnnotationCreationMode(
        AnnotationType.highlight
      );
      break;
    case 'action_share':
      // Implement document sharing.
      _shareDocument();
      break;
    case 'action_save':
      // Manually save document.
      _pdfDocument.save();
      break;
    // Handle other identifiers...
  }
},

Tips for custom toolbar items

  • Use unique, descriptive identifiers for each CustomToolbarItem.

  • Test icon appearance on both platforms. Vector drawables (Android) and SF Symbols (iOS) are preferred.

  • Use the iconColor parameter with Flutter’s Color type (e.g. Colors.red or Color(0xFFFF0000)).

  • For iOS custom images, ensure they’re set as Template Image in the asset catalog to allow tinting.

  • Always handle all defined identifiers in your onCustomToolbarItemTapped callback.

Web

The toolbar can be customized using the PdfWebConfiguration object, which is set as the webConfiguration property of the PdfConfiguration object. The toolbarItems property of PdfWebConfiguration is a list of PspdfkitWebToolbarItem objects.

To modify the toolbar, you can use Pspdfkit.defaultWebToolbarItems to fetch the default toolbar items. You can then add, remove, or reorder these items based on your requirements.

For grouping items together, create a PspdfkitWebToolbarItem with the type set to PspdfkitWebToolbarItemType.responsiveGroup, and provide an id. Subsequent items can then be added to this group by setting the responsiveGroup property to the id of the group item:

// First, get `defaultToolbarItems` for Web.
// `defaultToolbarItems` is a list of `PspdfkitWebToolbarItem` objects.
// You can modify this list to customize the toolbar. Remove, add, or reorder the items as needed.
final defaultWebToolbarItems = Pspdfkit.defaultWebToolbarItems;

/// Add a custom button to the toolbar.
await PspdfkitWidget(documentPath: "document/path.pdf", configuration: PdfConfiguration(
    webConfiguration: PdfWebConfiguration(
        toolbarItems: [
            PspdfkitWebToolbarItem(
                type: PspdfkitWebToolbarItemType.custom,
                title: 'Custom ToolbarItem',
                onPress: (event) {
                    ScaffoldMessenger.of(context).showSnackBar(
                        const SnackBar(
                            content: Text(
                                'Hello from custom button!')));
                }),
            PspdfkitWebToolbarItem(
                type:
                    PspdfkitWebToolbarItemType.responsiveGroup,
                title: 'Responsive Group',
                id: 'my-responsive-group',
                mediaQueries: ['(max-width: 600px)'],
            ),
            PspdfkitWebToolbarItem(
                type: PspdfkitWebToolbarItemType.ink,
                responsiveGroup: 'my-responsive-group',
            ),
            PspdfkitWebToolbarItem(
                type: PspdfkitWebToolbarItemType.inkEraser,
                responsiveGroup: 'my-responsive-group',
            ),
        ]
    )
));

This image below shows how the toolbar looks after customization.

Web