Flutter PDF bookmark SDK

Bookmarks mark important places in a PDF document, such as the page where a user stopped reading. The PDF specification doesn’t define a standard way to store bookmarks in PDF documents. Nutrient stores bookmarks in XMP metadata so Nutrient can read them across platforms and Apple Preview can read them too.

Working with bookmarks

For most use cases, you don’t need to interact with the bookmarks model directly. Nutrient provides a user interface (UI) for users to add, remove, and sort bookmarks based on your configuration. Nutrient then stores those bookmarks in the PDF document.

Use the bookmarks model when you need one of the following options:

• Provide your own bookmarks UI.
• Store bookmarks outside the default document storage.
• Manage bookmarks programmatically.

The bookmarks model uses the Bookmark(opens in a new tab) class, which stores the bookmark name and the action Nutrient performs when a user selects the bookmark. Access bookmarks through the document’s bookmark manager(opens in a new tab), document.bookmarks, which provides methods to retrieve, add, remove, and update bookmarks.

You can access the document from either of these places:

• controller.document in a viewer.
• Nutrient.openDocument() for headless processing.

Accessing bookmarks

Use getBookmarks() on the bookmark manager to retrieve all bookmarks in the document:

// Get all bookmarks in the document.
final bookmarks = await controller.document.bookmarks.getBookmarks();

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

To check whether a specific page has bookmarks or to retrieve bookmarks for a page, use this code:

// Check if page has any bookmarks.
final hasBookmark =
    await controller.document.bookmarks.hasBookmarkForPage(pageIndex);

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

Adding bookmarks

Use addBookmark() to add a bookmark. Create a page bookmark with BookmarkFactory.forPage():

import 'package:nutrient_flutter/bindings.dart';

// 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 controller.document.bookmarks.addBookmark(bookmark);
print('Created bookmark with ID: ${createdBookmark.pdfBookmarkId}');

BookmarkFactory.forPage() creates a bookmark with a GoToAction that navigates to the specified page. If you don’t provide a name, Nutrient uses a default name based on the page number.

Removing bookmarks

Use removeBookmark() to remove a bookmark:

// Get bookmarks for the page.
final pageBookmarks =
    await controller.document.bookmarks.getBookmarksForPage(pageIndex);

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

Updating bookmarks

Use updateBookmark() to update a bookmark. Create a modified copy of an existing bookmark with copyWith():

// Create a copy with a new name.
final updatedBookmark = bookmark.copyWith(name: 'New Chapter Name');

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

Bookmark properties

The Bookmark class has these properties:

• pdfBookmarkId — The unique identifier assigned when Nutrient persists the bookmark. This value may be null for newly created bookmarks.
• name — The display name shown in the UI.
• actionJson — The action JSON string that defines what happens when a user activates the bookmark.

Use the pageIndex extension getter to access the page index of a bookmark:

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

Persisting bookmarks

When you use NutrientDocumentView, Nutrient saves bookmark changes with the document. For headless document operations, save the document explicitly:

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.bookmarks.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 with IOSViewConfiguration(opens in a new tab):

NutrientDocumentView(
  documentPath: documentPath,
  configuration: const NutrientViewConfiguration(
    iosConfig: IOSViewConfiguration(
      // Control when the bookmark indicator is shown.
      bookmarkIndicatorMode: IOSBookmarkIndicatorMode.onWhenBookmarked,
      // Allow users to tap the indicator to toggle bookmarks.
      bookmarkIndicatorInteractionEnabled: true,
    ),
  ),
)

The indicator supports these modes:

Android bookmarks UI

On Android, enable or disable the bookmarks action in the toolbar with AndroidViewConfiguration(opens in a new tab):

NutrientDocumentView(
  documentPath: documentPath,
  configuration: const NutrientViewConfiguration(
    androidConfig: AndroidViewConfiguration(
      // Show the bookmarks button in the toolbar.
      showBookmarksAction: true,
    ),
  ),
)

Platform support

Nutrient Flutter SDK supports bookmark functionality on these platforms: