flutter_pdfview does not update PDF even if parent Widget is rebuilt

by

Summary

This incident describes a subtle but common Flutter rendering failure: flutter_pdfview does not refresh its displayed PDF even when the parent widget rebuilds. The UI appears unchanged after returning from an editing screen, despite setState() being called. The underlying issue is that the PDFView widget internally caches the rendered PDF and does not reinitialize unless its identity changes.

Root Cause

The root cause is widget identity and internal caching:

  • flutter_pdfview caches the PDF rendering surface.
  • Rebuilding the parent widget does not force the PDFView to reload the file.
  • The widget is considered “the same” because its constructor arguments do not change.
  • Flutter’s diffing algorithm optimizes away unnecessary rebuilds, so the native view is never recreated.

Why This Happens in Real Systems

This pattern is extremely common in hybrid or native-backed widgets:

  • Platform views (Android/iOS native views embedded in Flutter) often maintain internal state.
  • Flutter rebuilds the widget tree, but platform views do not automatically refresh unless their parameters change.
  • Many plugins assume the file path is static and do not watch for file changes.
  • Without a new key or changed parameter, Flutter treats the widget as unchanged.

Real-World Impact

This leads to several user-facing issues:

  • Users see stale or outdated PDFs after editing.
  • Developers mistakenly believe setState() is broken.
  • UI inconsistencies appear when navigating between screens.
  • Debugging becomes difficult because the parent widget does rebuild, but the platform view does not.

Example or Code (if necessary and relevant)

A common fix is to force the PDFView to be treated as a new widget instance by giving it a unique key whenever the PDF changes.

PDFView(
  key: ValueKey(DateTime.now().millisecondsSinceEpoch),
  filePath: updatedPdfPath,
)

Or, more controlled:

PDFView(
  key: ValueKey(updatedPdfPath),
  filePath: updatedPdfPath,
)

How Senior Engineers Fix It

Experienced engineers recognize platform-view caching patterns and apply one of these strategies:

  • Use a ValueKey tied to the file path or a version counter to force widget recreation.
  • Regenerate the PDF file path (e.g., write to a new temp file).
  • Wrap the PDFView in a FutureBuilder that waits for the edited file to be ready.
  • Replace the plugin with one that supports hot reload of content.
  • Invalidate caches explicitly if the plugin exposes such an API.

The key insight: you must change something that affects widget identity.

Why Juniors Miss It

Junior developers often assume:

  • setState() always forces a full rebuild.
  • Rebuilding the parent widget automatically rebuilds child platform views.
  • Plugins behave like pure Flutter widgets.
  • File changes on disk automatically propagate to UI components.

They miss the deeper architectural detail: platform views are not rebuilt unless Flutter believes the widget has changed, and Flutter only checks constructor arguments and keys—not the underlying file contents.

Leave a Comment