Flutter PDF bookmark SDK

Bookmarks provide a convenient way of marking where you last stopped in your PDF documents. The PDF specification doesn’t contain a standardized way to store bookmarks in PDF documents, so for this reason, Nutrient stores bookmarks as part of the XMP metadata in a way that’s compatible with Nutrient on all platforms, as well as with Apple Preview.

Working with bookmarks

For most use cases, you don’t need to interact with the bookmarks model yourself, as Nutrient provides a user interface (UI) for users to add, remove, and sort bookmarks depending on the configuration in use. It then automatically stores them in the PDF document they belong to. However, when you want to provide either your own UI or your own bookmarks store, you need to access the model Nutrient provides for you.

The bookmarks model consists of the Bookmark class, which contains information about its name and what action to perform when a user selects it. You can access bookmarks through the PdfDocument instance, which provides methods to retrieve, add, remove, and update bookmarks.

Accessing bookmarks

To access bookmarks, use the getBookmarks() method on a PdfDocument instance. This returns a list of all bookmarks in the document:

void onDocumentLoaded(PdfDocument document) async {
  // Get all bookmarks in the document.
  final bookmarks = await document.getBookmarks();

  for (final bookmark in bookmarks) {
    print('Bookmark: ${bookmark.name}, Page: ${bookmark.pageIndex}');
  }
}

To check if a specific page has bookmarks, or to retrieve bookmarks for a particular page, use the following code:

void checkPageBookmarks(PdfDocument document, int pageIndex) async {
  // Check if page has any bookmarks.
  final hasBookmark = await document.hasBookmarkForPage(pageIndex);

  if (hasBookmark) {
    // Get all bookmarks for this page.
    final pageBookmarks = await document.getBookmarksForPage(pageIndex);
    print('Found ${pageBookmarks.length} bookmarks on page $pageIndex');
  }
}

Adding bookmarks

To add a bookmark, use the addBookmark() method on PdfDocument. The easiest way to create a bookmark is using BookmarkFactory.forPage():

import 'package:nutrient_flutter/nutrient_flutter.dart';

void addBookmarkToPage(PdfDocument document, int pageIndex) async {
  // Create a bookmark for a specific page.
  final bookmark = BookmarkFactory.forPage(
    pageIndex: pageIndex, // Zero-based page index.
    name: 'Chapter 1',
  );

  // Add the bookmark to the document.
  final createdBookmark = await document.addBookmark(bookmark);
  print('Created bookmark with ID: ${createdBookmark.pdfBookmarkId}');
}

The BookmarkFactory.forPage() method creates a bookmark with a GoToAction that navigates to the specified page. If no name is provided, a default name based on the page number is used.

Removing bookmarks

To remove a bookmark, use the removeBookmark() method:

void removeBookmarkFromPage(PdfDocument document, int pageIndex) async {
  // Get bookmarks for the page.
  final pageBookmarks = await document.getBookmarksForPage(pageIndex);

  if (pageBookmarks.isNotEmpty) {
    // Remove the first bookmark on this page.
    final removed = await document.removeBookmark(pageBookmarks.first);
    if (removed) {
      print('Bookmark removed successfully');
    }
  }
}

Updating bookmarks

To update a bookmark, use the updateBookmark() method. Create a modified copy of an existing bookmark using copyWith():

void renameBookmark(PdfDocument document, Bookmark bookmark) async {
  // Create a copy with a new name.
  final updatedBookmark = bookmark.copyWith(name: 'New Chapter Name');

  // Update the bookmark in the document.
  final success = await document.updateBookmark(updatedBookmark);
  if (success) {
    print('Bookmark updated successfully');
  }
}

Bookmark properties

The Bookmark class has the following properties:

pdfBookmarkId — The unique identifier assigned when the bookmark is persisted. This may be null for newly created bookmarks.
name — The display name shown in the UI.
actionJson — The action JSON string defining what happens when the bookmark is activated.

Access the page index of a bookmark using the pageIndex extension getter:

final bookmark = BookmarkFactory.forPage(pageIndex: 4, name: 'My Bookmark');
print('Bookmark points to page: ${bookmark.pageIndex}'); // Prints: 4

Persisting bookmarks

When using NutrientView, bookmark changes are automatically saved with the document. For headless document operations, you need to explicitly save the document:

void saveBookmarks(String documentPath) async {
  // Open the document.
  final document = await Nutrient.openDocument(documentPath);

  // Add a bookmark.
  final bookmark = BookmarkFactory.forPage(pageIndex: 0, name: 'Start');
  await document.addBookmark(bookmark);

  // Save the document to persist the bookmark.
  await document.save();

  // Close the document.
  await document.close();
}

iOS bookmark indicator

On iOS, Nutrient provides a visual bookmark indicator on page views. Configure its visibility and interaction behavior using PdfConfiguration:

NutrientView(
  documentPath: documentPath,
  configuration: PdfConfiguration(
    // Control when the bookmark indicator is shown.
    iOSBookmarkIndicatorMode: IOSBookmarkIndicatorMode.onWhenBookmarked,
    // Allow users to tap the indicator to toggle bookmarks.
    iOSBookmarkIndicatorInteractionEnabled: true,
  ),
  onDocumentLoaded: (document) {
    print('Document loaded');
  },
);

The available indicator modes are:

Mode	Description
`off`	Never show the bookmark indicator.
`alwaysOn`	Always show the bookmark indicator on page views.
`onWhenBookmarked`	Only display the indicator when the page is bookmarked.

Android bookmarks UI

On Android, enable or disable the bookmarks action in the toolbar:

NutrientView(
  documentPath: documentPath,
  configuration: PdfConfiguration(
    // Show the bookmarks button in the toolbar.
    androidShowBookmarksAction: true,
  ),
);

Platform support

Bookmark functionality is available on all platforms supported by Nutrient Flutter SDK:

Feature	Android	iOS	Web
Add bookmarks	Yes	Yes	Yes
Remove bookmarks	Yes	Yes	Yes
Update bookmarks	Yes	Yes	Yes
Get all bookmarks	Yes	Yes	Yes
Get bookmarks for page	Yes	Yes	Yes
Check if page is bookmarked	Yes	Yes	Yes
Bookmark indicator UI	No	Yes	No