PDF Bookshelf Viewer #

A beautiful Flutter package that displays PDFs in a bookshelf-style list with realistic page-turning animations and modern loading capabilities.

✨ Features #

📚 Bookshelf-Style Display #

• Beautiful wooden shelf design with realistic textures
• 3D book appearance with shadows and depth
• Customizable books per shelf
• Auto-generated book colors based on titles

📖 Page-Turning Animation #

• Realistic 3D page flip effect
• Smooth animations with gesture support
• Tap left/right to navigate pages
• Page indicator display

🌐 Multiple PDF Sources #

• Network URLs: Download PDFs from any HTTP/HTTPS URL
• Firebase Storage: Integrate with Firebase Cloud Storage
• App Assets: Bundle PDFs with your app
• Local Files: Load PDFs from device storage

⚡ Modern Features #

• Automatic Caching: Downloaded PDFs are cached for offline access
• Download Progress: Real-time progress indicators
• Error Handling: Graceful error states with retry functionality
• Offline Support: Access cached PDFs without internet
• Cache Management: Clear cache and monitor storage usage

📦 Installation #

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

dependencies:
  pdf_bookshelf_viewer: ^0.1.6

Then run:

flutter pub get

🚀 Quick Start #

Basic Example #

import 'package:flutter/material.dart';
import 'package:pdf_bookshelf_viewer/pdf_bookshelf_viewer.dart';

class MyBookshelf extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final books = [
      PdfBook(
        id: '1',
        title: 'Flutter Guide',
        source: PdfSource.network('https://example.com/flutter.pdf'),
        author: 'John Doe',
      ),
      PdfBook(
        id: '2',
        title: 'Dart Basics',
        source: PdfSource.asset('assets/pdfs/dart.pdf'),
        author: 'Jane Smith',
      ),
    ];

    return Scaffold(
      appBar: AppBar(title: Text('My Bookshelf')),
      body: BookshelfView(
        books: books,
        onBookTap: (book) {
          Navigator.push(
            context,
            MaterialPageRoute(
              builder: (context) => PdfPageFlipViewer(
                pdfSource: book.source,
                title: book.title,
              ),
            ),
          );
        },
      ),
    );
  }
}

📖 Usage Examples #

Loading PDFs from Different Sources #

1. Network URL

PdfBook(
  id: '1',
  title: 'My Document',
  source: PdfSource.network('https://example.com/document.pdf'),
)

2. Network URL with Headers

PdfBook(
  id: '1',
  title: 'Protected Document',
  source: PdfSource.network(
    'https://api.example.com/document.pdf',
    headers: {'Authorization': 'Bearer YOUR_TOKEN'},
  ),
)

3. Firebase Storage

// Make sure to initialize Firebase first
PdfBook(
  id: '1',
  title: 'Firebase PDF',
  source: PdfSource.firebase('pdfs/document.pdf'),
)

// With custom bucket
PdfBook(
  id: '2',
  title: 'Custom Bucket PDF',
  source: PdfSource.firebase(
    'pdfs/document.pdf',
    bucket: 'gs://your-custom-bucket',
  ),
)

4. App Assets

// Add PDF to pubspec.yaml assets first
PdfBook(
  id: '1',
  title: 'Bundled PDF',
  source: PdfSource.asset('assets/pdfs/guide.pdf'),
)

5. Local File

PdfBook(
  id: '1',
  title: 'Local Document',
  source: PdfSource.file('/path/to/local/file.pdf'),
)

Customizing the Bookshelf #

BookshelfView(
  books: books,
  onBookTap: _handleBookTap,
  booksPerShelf: 4,  // Number of books per row
  shelfHeight: 220,   // Height of each shelf
  backgroundColor: Color(0xFFD4A574),  // Custom wood color
  imgBuilder: (book) {
    // Custom image builder logic
    return Image.network(book.coverImage ?? '', fit: BoxFit.cover);
  },
  actionBuilder: (book) {
    // Optional action widget (e.g. Add to Cart button)
    return Align(
      alignment: Alignment.bottomRight,
      child: IconButton(
        icon: Icon(Icons.add_shopping_cart, color: Colors.white),
        onPressed: () => print('Added ${book.title}'),
      ),
    );
  },
)

PDF Viewer Options #

PdfPageFlipViewer(
  pdfSource: PdfSource.network('https://example.com/doc.pdf'),
  title: 'Document Title',
  initialPage: 0,      // Start at first page
  forceRefresh: false, // Set true to ignore cache
)

Cache Management #

final pdfLoader = PdfLoaderService();

// Get cache size
final cacheSize = await pdfLoader.getCacheSize();
print('Cache size: ${cacheSize / (1024 * 1024)} MB');

// Clear all cache
await pdfLoader.clearCache();

// Remove specific PDF from cache
await pdfLoader.removeCachedPdf('https://example.com/document.pdf');

Manual PDF Loading with Progress #

final pdfLoader = PdfLoaderService();

final localPath = await pdfLoader.loadPdf(
  PdfSource.network('https://example.com/large-document.pdf'),
  onProgress: (progress) {
    print('Download progress: ${(progress * 100).toStringAsFixed(0)}%');
  },
  forceRefresh: false, // Use cached version if available
);

print('PDF saved at: $localPath');

Lazy Loading Source #

You can provide books without a source and load it when the user taps on the book:

BookshelfView(
  books: [
    PdfBook(
      id: 'lazy_1',
      title: 'Lazy Book',
      // source is optional
      pageCount: 150,
      dimensions: '20x30 cm',
    ),
  ],
  onObtainSource: (book) async {
    // Fetch source asynchronously
    await Future.delayed(Duration(seconds: 1));
    return PdfSource.network('https://example.com/${book.title}.pdf');
  },
)

🎨 Components #

PdfBook Model #

Represents a PDF book with metadata:

PdfBook(
  id: '1',                // Required
  title: 'Book Title',        // Required
  source: PdfSource.network(...), // Optional
  author: 'Author Name',      // Optional
  coverImage: 'cover.png',    // Optional
  description: 'Description', // Optional
  pageCount: 120,             // Optional
  dimensions: '15 x 22 cm',   // Optional
  weight: '0.5 kg',           // Optional
)

PdfSource #

Defines where to load the PDF from:

• PdfSource.network(url, {headers}) - HTTP/HTTPS URL
• PdfSource.firebase(path, {bucket}) - Firebase Storage
• PdfSource.asset(path) - App assets
• PdfSource.file(path) - Local file system

BookshelfView Widget #

Displays books in a bookshelf layout:

PdfPageFlipViewer Widget #

PDF viewer with page-turning animation:

🔧 Firebase Setup #

To use Firebase Storage:

1. Add Firebase to your Flutter app
2. Initialize Firebase in main.dart:

import 'package:firebase_core/firebase_core.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  runApp(MyApp());
}

3. Configure Firebase Storage rules
4. Use PdfSource.firebase() to load PDFs

📱 Platform Support #

🎯 Requirements #

• Flutter SDK: >=3.0.0
• Dart SDK: >=3.0.0

📸 Screenshots #

Coming soon

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits #

• Uses flutter_pdfview for PDF rendering
• Uses dio for efficient downloads
• Uses firebase_storage for Firebase integration

📚 Example App #

Run the example app to see all features in action:

cd example
flutter run

The example demonstrates:

• Loading PDFs from network URLs
• Firebase Storage integration
• Asset-bundled PDFs
• Cache management
• Error handling and retry
• Download progress indicators

👨‍💻 Author #

Developed by TechSukras

🐛 Issues #

If you encounter any issues, please file them on the GitHub issue tracker.