Cache Network Media #

The ultimate Flutter plugin for caching network images, SVGs, and Lottie animations with persistent disk storage and offline support.

Why Cache Network Media? #

Tired of your app downloading the same images repeatedly? Want seamless offline support for your media assets? Cache Network Media provides a unified, efficient solution for caching all your network media in Flutter.

✨ Key Benefits #

Feature Comparison #

Supported Media Types #

Feature Matrix #

Installation #

Add to your pubspec.yaml:

dependencies:
  cache_network_media: ^0.0.3

Then run:

flutter pub get

Quick Start #

Cache Network Images #

CacheNetworkMediaWidget.img(
  url: 'https://example.com/image.png',
  width: 200,
  height: 200,
  fit: BoxFit.cover,
  placeholder: CircularProgressIndicator(),
  onTap: () => print('Image tapped!'),
)

Cache SVG Graphics #

CacheNetworkMediaWidget.svg(
  url: 'https://example.com/icon.svg',
  width: 100,
  height: 100,
  color: Colors.blue,
  onTap: () => print('SVG tapped!'),
)

Cache Lottie Animations #

CacheNetworkMediaWidget.lottie(
  url: 'https://example.com/animation.json',
  width: 300,
  height: 300,
  repeat: true,
  animate: true,
  onTap: () => print('Animation tapped!'),
)

Advanced Usage #

Custom Cache Directory #

Take full control over where your cached files are stored. This is useful for:

• Organizing cached files by feature or user
• Managing cache size by clearing specific directories
• Sharing cache between different parts of your app
• Debugging by easily locating cached files

import 'dart:io';

// Use a custom directory for caching
final customDir = Directory('/path/to/your/cache');

CacheNetworkMediaWidget.img(
  url: 'https://example.com/image.png',
  cacheDirectory: customDir,
)

Error Handling #

Handle network failures gracefully:

CacheNetworkMediaWidget.img(
  url: 'https://example.com/image.png',
  placeholder: CircularProgressIndicator(),
  errorBuilder: (context, error, stackTrace) {
    return Column(
      children: [
        Icon(Icons.error, color: Colors.red),
        Text('Failed to load image'),
      ],
    );
  },
)

Image with Color Blending #

CacheNetworkMediaWidget.img(
  url: 'https://example.com/image.png',
  color: Colors.blue,
  colorBlendMode: BlendMode.multiply,
  filterQuality: FilterQuality.high,
)

SVG with Theme Support #

CacheNetworkMediaWidget.svg(
  url: 'https://example.com/icon.svg',
  colorFilter: ColorFilter.mode(Colors.red, BlendMode.srcIn),
  theme: SvgTheme(currentColor: Colors.blue),
  semanticsLabel: 'App logo',
)

Lottie with Animation Control #

CacheNetworkMediaWidget.lottie(
  url: 'https://example.com/animation.json',
  repeat: false,           // Play once
  reverse: true,           // Play in reverse
  animate: true,           // Auto-start
  frameRate: 60.0,         // Custom FPS
  addRepaintBoundary: true, // Performance optimization
)

API Reference #

Common Parameters (All Media Types) #

Image-Specific Parameters #

SVG-Specific Parameters #

Lottie-Specific Parameters #

How Caching Works #

┌─────────────────────────────────────────────────────────────┐
│                    Cache Flow Diagram                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Request URL ──► Check Cache ──► Cache Hit? ──► Yes ──►   │
│        │                              │          Return     │
│        │                              │          Cached     │
│        │                              ▼                     │
│        │                             No                     │
│        │                              │                     │
│        │                              ▼                     │
│        │                      Download from                 │
│        │                         Network                    │
│        │                              │                     │
│        │                              ▼                     │
│        │                      Save to Cache                 │
│        │                              │                     │
│        │                              ▼                     │
│        └─────────────────────► Return Media                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Cache Storage #

Platform Support #

Performance Tips #

1. Use appropriate image sizes - Don't load 4K images for thumbnails
2. Leverage custom cache directories - Organize cache by feature for easier management
3. Set dimensions when known - Provide width and height to avoid layout shifts
4. Use addRepaintBoundary - Enabled by default for Lottie, improves performance
5. Handle errors gracefully - Always provide an errorBuilder for production apps

Migration Guide #

From cached_network_image #

// Before (cached_network_image)
CachedNetworkImage(
  imageUrl: 'https://example.com/image.png',
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
)

// After (cache_network_media)
CacheNetworkMediaWidget.img(
  url: 'https://example.com/image.png',
  placeholder: CircularProgressIndicator(),
  errorBuilder: (context, error, stackTrace) => Icon(Icons.error),
)

Documentation #

• API Reference
• Architecture Details
• Contributing Guidelines
• Changelog

Contributing #

We welcome contributions! Please read our Contributing Guidelines before submitting a PR.

# Clone the repository
git clone https://github.com/D-extremity/cache_network_media.git

# Install dependencies
flutter pub get

# Run tests
flutter test

# Check formatting
dart format --set-exit-if-changed .

# Run analyzer
flutter analyze

License #

MIT License - see LICENSE for details.

Author #

Created with ❤️ by @D-extremity

Support #

If this package helped you, please:

• ⭐ Star the GitHub repository
• 👍 Like on pub.flutter-io.cn
• 🐛 Report issues on GitHub Issues

Cache Network Media - Making network media caching simple since 2025