flutter_pdfview #

Native PDF View for iOS and Android

Use this package as a library #

1. Depend on it #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_pdfview: ^1.4.5

Trying the 1.5.0 beta

1.5.0-beta.10 continues the Kotlin/Swift line by letting password-protected documents be unlocked from the app (#274), on top of the luminance-preserving PdfColorMode dark theming in beta.9 (#215, #138). Pre-releases are not picked up by a ^ constraint, so pin it explicitly:

dependencies:
  flutter_pdfview: 1.5.0-beta.10

Feedback is welcome in #351.

2. Install it #

You can install packages from the command line:

with Flutter:

$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it #

Now in your Dart code, you can use:

import 'package:flutter_pdfview/flutter_pdfview.dart';

Options #

Notes:

• colorMode themes page content and the gutter on both platforms. Values: PdfColorMode.light, PdfColorMode.dark, PdfColorMode.system (default). system follows the app Theme brightness (or platform brightness when no Theme is present) and is resolved in Dart before being sent to the native view. Dark mode uses a luminance-preserving inversion (hue kept; photos do not become pure negatives). Live updates apply without remounting the platform view.
• nightMode is deprecated. Prefer colorMode. When colorMode is left at system and nightMode: true, the resolved mode is dark. An explicit colorMode always wins.
• backgroundColor can be updated at runtime together with colorMode. Setting it back to null after a non-null value leaves the previous color on screen.
• password can be changed after the first build: the document is reopened in place, so the platform view is not recreated. See Password-protected documents.
• showScrollIndicators is ignored on iOS while horizontal page-flipping is active (pageFling: true together with swipeHorizontal: true).
• autoSpacing only adds gaps between pages. It does not change initial zoom or fitPolicy (fixed in #150).
• thumbnailRatio must be in (0, 1]. Higher values look sharper while tiles load but use more memory.
• pageAlignment controls where a document that is shorter than the viewport sits. The default PageAlignment.center matches historical AndroidPdfViewer / PDFKit behavior. Use PageAlignment.top so free space is below the page (typical for single-page PDFs — #250, #272):

PDFView(
  filePath: path,
  pageAlignment: PageAlignment.top,
  backgroundColor: Colors.grey.shade200,
)

Render quality (#158) #

iOS (PDFKit) draws PDF content as vectors at the screen scale. Text and line art should stay sharp when zooming. This plugin sets the platform view’s contentScaleFactor / layer contentsScale to the native display scale so Flutter embedding never leaves the layer at 1×.

Android (AndroidPdfViewer + Pdfium) rasterizes each page into bitmap tiles:

On high-DPI devices the plugin also raises AndroidPdfViewer’s page-part cache slightly (still capped) so fewer tiles fall out of cache after zoom — the common “only part of the page is clear” report.

Hard limits (not a bug in this plugin):

• Tile spatial resolution matches the view size in pixels, not print DPI. Small text on a phone-sized view will never look like a desktop PDF reader without a different engine (supersampling / MuPDF / Android PdfRenderer at higher scale). That would multiply memory and is intentionally not enabled by default.
• AndroidPdfViewer’s tile size / cache are process-wide statics; thumbnailRatio from the first (or latest) view construction wins for the process.

For the sharpest Android preview without a huge memory hit:

PDFView(
  filePath: path,
  useBestQuality: true,          // default
  enableAntialiasing: true,    // default
  enableRenderDuringScale: true, // default
  thumbnailRatio: 1.0,           // full-page preview at 1:1 (more RAM)
)

Detecting taps (onTap) #

For a reliable single-tap callback, use the first-class onTap parameter. It is delivered from the native PDF control on both platforms:

PDFView(
  filePath: path,
  onTap: () {
    // e.g. toggle chrome / app bar
  },
)

Do not rely on gestureRecognizers with a TapGestureRecognizer for taps. Flutter’s platform-view gesture arena often never delivers onTap for embedded native views (#133). Keep gestureRecognizers for parent-scroll conflicts (below).

AcroForm / fillable form fields #

This plugin is a viewer, not a form editor. Platform behavior:

Implication: if a PDF’s form field has a missing, empty, or broken /AP entry, Android can omit that field even when Adobe shows it. A common producer-side failure mode (seen with PDFBox + incremental saves / digital signing) is an object-number collision where the field’s /AP indirect reference is later reused for an XRef stream — the field value is still in the file, but the appearance object is no longer valid. See #303.

Producer workarounds (fix generators such as Apache PDFBox):

1. After setting values, generate valid appearance streams (PDFBox: setValue / appearance generation; avoid leaving fields without a usable /AP).
2. Prefer a full rewrite save when possible; after incremental updates (especially signing), re-check that each field’s /AP still resolves to a Form XObject, not an XRef or other object.
3. Flatten fields when interactivity is not required (PDAcroForm.flatten()), so values become normal page content.
4. Optionally set /NeedAppearances true on the AcroForm dictionary — some viewers honor it; Pdfium generally still requires a real appearance stream for reliable display.

There is no plugin API that can repair malformed form appearances without embedding a full PDF rewrite stack (out of scope for this viewer).

Password-protected documents #

Pass the password up front with password when you already know it. When you do not, onPasswordRequired tells you that the document is encrypted — either because no password was supplied (PDFPasswordFailure.missing) or because the one you supplied did not open it (PDFPasswordFailure.incorrect) — so you can prompt the user and try again (#274):

PDFView(
  filePath: path,
  password: _password,
  onPasswordRequired: (PDFPasswordFailure failure) async {
    final String? entered = await showPasswordDialog(
      context,
      retry: failure == PDFPasswordFailure.incorrect,
    );
    if (entered != null) {
      // Either rebuild with the new password ...
      setState(() => _password = entered);
      // ... or hand it straight to the controller:
      // await controller.unlock(entered);
    }
  },
)

Both routes reopen the document inside the existing platform view, so a wrong password can be retried as often as needed without rebuilding the viewer. onError still fires alongside onPasswordRequired, so viewers written before this callback existed keep working.

Using PDFView inside a scrollable widget #

When a PDFView is embedded in a scrollable parent (SingleChildScrollView, ListView, PageView, ...), the parent can claim drag gestures before they reach the native view, so swiping inside the PDF does not work — most notably on iOS (#265). Pass an EagerGestureRecognizer to let the PDF view consume gestures within its bounds:

import 'package:flutter/foundation.dart';
import 'package:flutter/gestures.dart';

PDFView(
  filePath: path,
  gestureRecognizers: {
    Factory<OneSequenceGestureRecognizer>(() => EagerGestureRecognizer()),
  },
)

BackdropFilter / ColorFiltered over PDFView (iOS) #

PDFView is a platform view (UiKitView on iOS, hybrid composition on Android). Flutter composites native views outside the normal Flutter layer tree, so some widgets that sample or recolor the scene do not apply to the PDF pixels — especially on iOS.

This is not a bug in flutter_pdfview. Flutter documents it under iOS platform view composition limitations: ShaderMask and ColorFiltered are unsupported; BackdropFilter works only within the constraints of the iOS Platform View Backdrop Filter design.

Workarounds

1. Color inversion / dark pages — Prefer the plugin API instead of wrapping the view in ColorFiltered:

   • Both platforms: colorMode: PdfColorMode.dark (or PdfColorMode.system to follow the app Theme). Luminance-preserving invert keeps photos recognizable.
   • Legacy: nightMode: true still maps to dark when colorMode is left at system (deprecated).

2. Blur / glass under a sheet — Place the BackdropFilter so it samples Flutter-drawn content (not only the hole where the native PDF sits), use a semi-transparent barrierColor / scrim, or capture a static preview with PDFViewController.getScreenshot and blur that Image with Flutter widgets.

3. Static filtered preview — For a one-shot recolor (e.g. thumbnail), take a screenshot and wrap the resulting image:

final path = await controller.getScreenshot('preview.png');
// Then:
ColorFiltered(
  colorFilter: const ColorFilter.mode(Colors.grey, BlendMode.saturation),
  child: Image.file(File(path)),
);

Wrapping PDFView itself in ColorFiltered will keep painting a solid tint under the native view on iOS while leaving the PDF contents unchanged (#213).

Controller Options #

Example #

PDFView(
  filePath: path,
  enableSwipe: true,
  swipeHorizontal: true,
  autoSpacing: false,
  pageFling: false,
  showScrollIndicators: true,
  colorMode: PdfColorMode.system, // follows Theme brightness
  backgroundColor: Theme.of(context).colorScheme.surface,
  onRender: (_pages) {
    setState(() {
      pages = _pages;
      isReady = true;
    });
  },
  onError: (error) {
    print(error.toString());
  },
  onPageError: (page, error) {
    print('$page: ${error.toString()}');
  },
  onViewCreated: (PDFViewController pdfViewController) {
    _controller.complete(pdfViewController);
  },
  onPageChanged: (int page, int total) {
    print('page change: $page/$total');
  },
  onLoadComplete: (int? pages) {
    print('# of pages: $pages');
  },
  onDraw: (double xOffset, double yOffset, double scale) {
    print('onDraw');
  },
),

Dependencies #

Android #

AndroidPdfViewer

iOS (only support> 12.0) #

PDFKit

Future plans #

• Replace barteksc/AndroidPdfViewer with MuPDF or Android Native PDF Renderer.
• Improve documentation
• Support other platforms such as MacOS, Windows, Linux and Web
• Add search functionality
• Improve performance on zooming, page changing
• Improve image quality
• Write more test

Support #

Star History #

Developer #

• endigo