← Abdelrahman Saed · All case studies

flutter_cached_pdfview

An open-source cached PDF viewer for Flutter, adopted across thousands of apps

Creator & maintainer · 2020 — Present · iOS · Android

  • 130+ — GitHub stars
  • 500+ — pub.dev likes
  • 43K+ — Downloads
  • 100+ — Forks
  • 6 yrs — Maintained
  • MIT — Licensed

The Problem

Displaying remote PDFs in a mobile app sounds trivial until you ship it. The common approaches each fall short:

  • Re-downloading on every open. Naively loading a PDF from a URL fetches the whole file again each time — slow for the user and wasteful of bandwidth and data plans.
  • No offline story. Once the network drops, documents a user already opened are simply gone.
  • Platform fragmentation. iOS and Android render PDFs through entirely different native components, so a consistent, performant viewer means bridging both.
  • Boilerplate everywhere. Loading states, error handling, and cache management get re-implemented in every app that needs a PDF.

I kept solving the same problem across projects, so I built it once, properly, and open-sourced it.

The Solution

flutter_cached_pdfview renders remote PDFs natively while caching each downloaded file on-device — so a document opens instantly and works offline on every load after the first.

It wraps the native flutter_pdfview renderer with flutter_cache_manager, and exposes one small, declarative API over three sources — URL, asset, and file path — with progress placeholders, error widgets, and password-protected and gesture-zoom support built in:

// First open downloads + caches; every later open is served from disk.
const PDF().cachedFromUrl(
  'https://example.com/doc.pdf',
  placeholder: (progress) => Center(
    child: CircularProgressIndicator(value: progress / 100),
  ),
  errorWidget: (error) => const Center(child: Text('Failed to load PDF')),
);

The goal was to make the right behavior — cached, offline-capable, native rendering — the default, in a few lines, on both platforms.

Architecture

The package is a thin, deliberate composition rather than a reinvention:

  • Native rendering, not a Dart PDF engine. It delegates pixel-level rendering to the platform components through flutter_pdfview, so documents look and scroll the way users expect on each OS, and the package stays small.
  • Caching via flutter_cache_manager. Remote files are downloaded once and stored in a managed on-device cache; later reads resolve straight to a local file, which is what makes repeat opens instant and offline-safe.
  • A source abstraction. cachedFromUrl, fromAsset, and fromPath unify remote, bundled, and local documents behind one widget, so callers swap sources without touching their UI.
  • Lifecycle hooks as first-class API. placeholder (download progress) and errorWidget are part of the public surface, so loading and failure states are handled by design rather than bolted on.

It supports Android API 20+ and iOS 11+, ships under the MIT license, and has stayed maintained since 2020.

Performance

The entire point of the package is performance and resilience under real-world conditions:

  • Instant repeat opens. The first load downloads and caches the file; every subsequent open is served from disk, eliminating the network round-trip and the re-download.
  • Bandwidth saved. Documents are fetched once, not once per view — meaningful for users on metered or slow connections.
  • Offline by consequence. Because reads resolve to the on-device cache, previously opened PDFs keep working with no connection at all.
  • Small footprint. Leaning on the native renderers keeps the package lightweight and avoids shipping a heavyweight PDF engine inside every app that depends on it.

Results

The package became one of the go-to PDF solutions in the Flutter ecosystem:

  • 130+ GitHub stars, 500+ pub.dev likes, and 43,000+ downloads.
  • 100+ forks and contributions from the community.
  • Maintained continuously since 2020, kept current with modern Flutter (null-safety, super.key, current cache-manager APIs).
  • Adopted in production document readers, e-book apps, and EdTech products — including the PDF experiences I shipped at iStoria.

A small library with an outsized footprint: a focused tool that solved a recurring problem well enough that thousands of other apps now rely on it. The companion guide below walks through using it end-to-end.

Tags: Flutter · Dart · Open Source · PDF · Plugin

Related reading: Building a Cached PDF Viewer in Flutter