Guides

Page Thumbnails

ComPDF Flutter SDK supports rendering PDF pages as thumbnails for preview, navigation, document directory, page selector, and custom PDF management UIs.

Two approaches are available:

• Use CPDFPageThumbnailProvider as an ImageProvider in Flutter's Image widget.
• Use CPDFPageThumbnail for a ready-to-use widget with placeholder and error builders.

If you already have a CPDFDocument instance, use it as the thumbnail source to avoid reopening the file.

Quick Start

The following example renders the first page of an opened document as a thumbnail.

final CPDFDocument document = await CPDFDocument.createInstance();
await document.open('/path/to/sample.pdf');

CPDFPageThumbnail.document(
  document: document,
  pageIndex: 0,
  options: const CPDFPageThumbnailOptions(width: 240),
)

API Overview

Class	Purpose
CPDFPageThumbnailProvider	ImageProvider for Flutter's Image widget
CPDFPageThumbnail	Ready-to-use thumbnail widget with placeholder and error builders
CPDFPageThumbnailOptions	Rendering options: size, background, compression, caching
CPDFPageThumbnailService	Cache management and metrics
CPDFPageThumbnailCachePolicy	Cache strategy: memory, disk, both, or none

Using CPDFPageThumbnailProvider

CPDFPageThumbnailProvider is an ImageProvider. Pass it directly to Flutter's Image widget.

import 'package:compdfkit_flutter/compdfkit.dart';
import 'package:flutter/material.dart';

class ThumbnailView extends StatelessWidget {
  const ThumbnailView({
    super.key,
    required this.document,
    required this.pageIndex,
  });

  final CPDFDocument document;
  final int pageIndex;

  @override
  Widget build(BuildContext context) {
    return Image(
      image: CPDFPageThumbnailProvider.document(
        document: document,
        pageIndex: pageIndex,
        options: const CPDFPageThumbnailOptions(
          width: 300,
          compression: CPDFPageCompression.jpeg,
        ),
      ),
      fit: BoxFit.contain,
      errorBuilder: (context, error, stackTrace) {
        return const Icon(Icons.broken_image_outlined);
      },
    );
  }
}

Using CPDFPageThumbnail

CPDFPageThumbnail wraps CPDFPageThumbnailProvider with a placeholder and error builder for convenience.

CPDFPageThumbnail.document(
  document: document,
  pageIndex: 0,
  options: const CPDFPageThumbnailOptions(width: 300),
  fit: BoxFit.contain,
  placeholderBuilder: (context) {
    return const Center(child: CircularProgressIndicator());
  },
  errorBuilder: (context, error, stackTrace) {
    return const Icon(Icons.broken_image_outlined);
  },
)

Using a File Path

If you do not have a CPDFDocument instance yet, create a thumbnail from a local PDF file path.

Image(
  image: CPDFPageThumbnailProvider.file(
    filePath: '/path/to/sample.pdf',
    pageIndex: 0,
    password: '',
    options: const CPDFPageThumbnailOptions(width: 240),
  ),
)

When a document is already open in your app, prefer the document source.

Rendering Options

Use CPDFPageThumbnailOptions to control thumbnail size, background, image format, and caching.

const options = CPDFPageThumbnailOptions(
  width: 600,
  backgroundColor: Colors.white,
  drawAnnot: true,
  drawForm: true,
  compression: CPDFPageCompression.jpeg,
  jpegQuality: 85,
  cachePolicy: CPDFPageThumbnailCachePolicy.memoryAndDisk,
);

Parameter	Description
width / height	Thumbnail target size in pixels; if only one dimension is set, the other is calculated from the page aspect ratio
scale	Scale factor applied to the original page size when width and height are unset
backgroundColor	Page background color
drawAnnot	Whether to render annotations on the thumbnail
drawForm	Whether to render form widgets on the thumbnail
compression	Image format; supports png and jpeg
jpegQuality	JPEG quality, from 1 to 100
cachePolicy	Thumbnail cache strategy
diskCacheTtl	Disk cache time-to-live
maxPixelCount	Maximum number of pixels allowed per thumbnail

In a thumbnail list, always set an explicit width or height to avoid excessively large renders.

Caching

Thumbnails are cached by default to reduce re-rendering and improve scrolling performance.

Policy

Policy	Description
memoryOnly	Memory cache only, no disk caching
memoryAndDisk	Default. Memory and disk caching
diskOnly	Disk caching only
noCache	No SDK-level caching

Cache Key

The cache key is derived from the document source, page index, page rotation, render size, background color, annotation/form flags, and image format. When the page is rotated or render parameters change, a new cache entry is used automatically.

Cache Directory

Disk cache is stored under ComPDFKit.getTemporaryDirectory():

<temporaryDirectory>/compdfkit_page_thumbnails/

Cache file names are hashed and do not contain the original page index or image extension. The content is not encrypted.

Clearing Cache

await CPDFPageThumbnailService.shared.clearCache();

Refreshing After Document Changes

If the document content changes without a file modification time update (for example, edits made in memory), use cacheVersion to force a refresh.

var cacheVersion = 0;

final provider = CPDFPageThumbnailProvider.document(
  document: document,
  pageIndex: pageIndex,
  cacheVersion: cacheVersion,
);

// Increment the version when the document changes in memory.
cacheVersion++;

When the page rotation changes, the cache automatically distinguishes between different rotation angles.

Error Handling

Thumbnail loading may fail due to an invalid file path, incorrect password, invalid page index, or render error. Always provide an error fallback.

Image(
  image: CPDFPageThumbnailProvider.document(
    document: document,
    pageIndex: pageIndex,
  ),
  errorBuilder: (context, error, stackTrace) {
    return const Icon(Icons.broken_image_outlined);
  },
)

CPDFPageThumbnail also accepts an errorBuilder:

CPDFPageThumbnail.document(
  document: document,
  pageIndex: pageIndex,
  errorBuilder: (context, error, stackTrace) {
    return const Text('Thumbnail failed');
  },
)

Best Practices

• When a document is already open, use CPDFPageThumbnailProvider.document or CPDFPageThumbnail.document.
• In a screen with CPDFReaderWidgetController, use controller.document as the document source.
• Always set a fixed width or height in a thumbnail list.
• Keep the default cache policy (memoryAndDisk) for long lists to avoid repeated rendering.
• Use cacheVersion to refresh thumbnails after document changes that are not saved to disk.
• Always configure errorBuilder so that the UI provides clear visual feedback when loading fails.