flutter_book_reader 1.1.0

A customizable Flutter reader widget for novels and ebooks: lazy chapter loading, paginated and continuous-scroll modes, themes, and pluggable data sources & progress storage.

📖 flutter_book_reader

English | 中文

A polished, production-ready novel & ebook reader for Flutter — the kind of reading experience your users expect from a top-tier reading app, in a single widget.

🔗 Try the live demo → (runs in your browser)

Point BookReader at your own data and you instantly get real pagination, finger-following page-curl animations, chapter navigation, themes, and reading-progress persistence. Everything is driven by small, replaceable abstractions, so your content can come from an API, a database, local files, or anywhere else — without touching the reader's internals.

Why flutter_book_reader?

• 🪄 It feels like a real book. A realistic simulation page-curl that follows your finger, plus cover, slide, vertical-scroll, and no-animation modes.
• 📐 Real pagination, not a scroll hack. Paragraph-aware layout measured with TextPainter, with proper first-line indent and justification.
• 🔌 Bring your own everything. Data and progress storage are plain abstractions — network, DB, cloud sync, offline files all just work.
• 🎨 Beautiful out of the box. Six paper themes, one-tap day/night, adjustable font size / line height / spacing, and full-screen immersive reading.
• 🧪 Built to last. A widget-free logic core that's fully unit-tested, with a clean, documented architecture.

Features

• Five page modes — a realistic simulation page-curl that follows your finger (corner dog-ear, or a vertical curl when you swipe from the middle), cover (incoming page slides over the current one), smooth horizontal paging (seamless, flicker-free chapter crossing), continuous vertical scroll (auto-loads the next / previous chapter), and no-animation.
• Full-screen immersive reading — hides the status & system navigation bars while reading (no content shift when the menu opens), restored on exit; plus a one-tap day / night toggle.
• Real pagination via TextPainter, paragraph-aware: reader-owned first-line indent (works together with justification), paragraph spacing, and justification. Reading position is preserved across font-size / line-height / system-text-scale changes.
• Lazy chapter loading with neighbor prefetch, a bounded LRU cache, and loading & error / retry states.
• Pluggable data source (BookSource) and progress storage (ReaderProgressStore) — bring your own network / DB / cloud implementation.
• Debounced progress saving with a flush when the app goes to background.
• Theming & typography — six built-in paper themes, per-theme accent color, and runtime controls for font size / line height / brightness.
• Localizable UI strings (ReaderLabels) and basic accessibility semantics.

Install

dependencies:
  flutter_book_reader: ^1.1.0

import 'package:flutter_book_reader/flutter_book_reader.dart';

Quick start

BookReader(
  source: MyBookSource(),               // your data
  progressStore: MyProgressStore(),     // optional, defaults to no-op
  onChapterChanged: (int index) => debugPrint('chapter $index'),
  onPositionChanged: (ReadingPosition pos) => save(pos),
)

1. Provide a data source

BookSource is the only thing you must implement. It returns book metadata + a chapter list once, and chapter bodies on demand.

class MyBookSource extends BookSource {
  @override
  Future<BookManifest> loadManifest() async => BookManifest(
        id: 42,
        title: 'The Long Journey',
        author: 'Jane Doe',
        intro: '…',
        coverColor: Colors.blueGrey,
        chapterTitles: <String>['Chapter 1', 'Chapter 2', 'Chapter 3'],
      );

  @override
  Future<String> loadChapterBody(int index) async {
    // Fetch from your API / DB / assets. Paragraphs separated by '\n'.
    return api.fetchChapter(index);
  }
}

2. (Optional) Persist reading progress

class PrefsProgressStore extends ReaderProgressStore {
  @override
  Future<ReadingPosition?> load(Object bookId) async { /* … */ }

  @override
  Future<void> save(Object bookId, ReadingPosition position) async { /* … */ }
}

Built-ins: NoopReaderProgressStore (default) and InMemoryReaderProgressStore.

3. Theming, typography & page mode

final config = ReaderConfig()
  ..setTheme(ReaderTheme.yellow.copyWith(accentColor: const Color(0xFF3366FF)))
  ..setFlipType(FlipType.simulation) // simulation / cover / slideHorizontal / scrollVertical / none
  ..setFirstLineIndent(2)
  ..setParagraphSpacing(8)
  ..setJustify(true);

BookReader(source: MyBookSource(), config: config);

Users can also switch theme, page mode, font size, spacing, and day / night from the in-reader settings menu at runtime.

4. Localize the UI

BookReader(
  source: MyBookSource(),
  labels: const ReaderLabels(
    prevChapter: 'Previous',
    nextChapter: 'Next',
    catalog: 'Contents',
    // …
  ),
)

Architecture

• BookSource / ReaderProgressStore — public extension points (abstractions).
• ReadingController — pure, widget-free logic core, composed from four mixins (content loading / pagination / navigation / vertical flow); fully unit-testable.
• ReaderModeView — view base class; HorizontalReader, VerticalReader, and SimulationReader extend it.
• BookReader — the single entry-point widget.

Example

Try the live demo in your browser, or run it locally. A full example app (bookshelf + reader, data from assets/books.json) lives in example/ and depends on this package via path: ../:

cd example
flutter run

License

MIT — see LICENSE.