# cached_network_image_ce 4.0.1

Community Edition Flutter library to load and cache network images. Can also be used with placeholder and error widgets.




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'cached_network_image_ce:4.0.1'
```
Published: 2026-02-19T10:19:04.924300Z
Expected archive SHA-256: bede5b1e74e8c99be0ee867e9e35d5fc632b09b6cf18ab74a94f6e0b2e8351a8

Available in cache; verification: upstream_checksum
## Direct dependencies
- cached_network_image_platform_interface_ce: ^5.0.1
- cached_network_image_web_ce: ^2.0.1
- file: >=7.0.0 <8.0.0
- flutter: map[sdk:flutter]
- hive_ce: ^2.0.0
- http: ^1.6.0
- octo_image: ^2.1.0
- path: ^1.8.0
- path_provider: ^2.0.0

## Package README (untrusted upstream documentation)
# Cached Network Image — Community Edition

[![pub package](https://img.shields.io/pub/v/cached_network_image_ce.svg)](https://pub.dev/packages/cached_network_image_ce)
[![License: MIT](https://img.shields.io/badge/license-MIT-purple.svg)](https://opensource.org/licenses/MIT)

A Flutter library to show images from the internet and keep them in the cache directory.

**This is the actively maintained, high-performance community fork of [`cached_network_image`](https://pub.dev/packages/cached_network_image).**

---

## 📖 The Story: Why this fork?

The original `cached_network_image` package by Baseflow is a titan in the Flutter ecosystem, used by millions. However, it has been **effectively unmaintained since August 2024**, leaving over 300 issues unresolved, including critical memory leaks and scroll performance bugs.

As the Flutter ecosystem evolved, the original architecture began to show its age. It relied on `sqflite` for cache management—a heavy, SQL-based solution that requires platform channels to communicate with native code. For a simple task like "checking if an image exists," this overhead caused UI jank in heavy lists.

**We created the Community Edition (`_ce`) to fix this.**

We didn't just fork it to merge dependabot PRs. We re-engineered the caching layer.

### ⚡ The Architectural Shift: SQLite vs. Hive

We replaced the heavy `sqflite` dependency with **[`hive_ce`](https://pub.dev/packages/hive_ce)**.

* **Old Way (`sqflite`):** serialized data → Platform Channel → Java/Obj-C → SQLite → Disk. (Slow, blocking).
* **New Way (`hive_ce`):** Dart Memory → Direct Disk Access. (Instant, non-blocking).

The result? **Zero-jank scrolling.**

### 🚀 Benchmarks

We benchmarked the cache metadata operations (checking, writing, and deleting cache entries) on an iPhone Simulator. The results speak for themselves:

| Operation | Payload Size | Original (`sqflite`) | **CE (`hive_ce`)** | **Improvement** |
| :--- | :--- | :--- | :--- | :--- |
| **Read (Hit Check)** | 10 KB | 16 ms | **2 ms** | ⚡ **8.00x Faster** |
| **Write (New Image)** | 10 KB | 116 ms | **29 ms** | 🚀 **4.00x Faster** |
| **Delete (Cleanup)** | 10 KB | 55 ms | **19 ms** | 🧹 **2.89x Faster** |
| **Read (Large)** | 1 MB | 8 ms | **1 ms** | ⚡ **8.00x Faster** |

*Note: "Read" is the most critical operation for scrolling performance, as every list item checks the cache before rendering.*

---

## 🛠 Features

* **Drop-in Replacement:** 99% API compatible with the original package.
* **High Performance:** Powered by `hive_ce` for instant cache lookups.
* **Actively Maintained:** Regular updates, bug fixes, and community-driven roadmap.
* **Web Support:** Minimal support for web (currently works like standard `Image.network`).

## 📦 Installation

Add `cached_network_image_ce` to your `pubspec.yaml`:

```yaml
dependencies:
  cached_network_image_ce: ^4.0.1
```

## 💻 How to use

The API is identical to the original package. You can use `CachedNetworkImage` directly or via `ImageProvider`.
Both `CachedNetworkImage` and `CachedNetworkImageProvider` have minimal support for web (currently without caching).

### Basic Usage with Placeholder

```dart
import 'package:cached_network_image_ce/cached_network_image.dart';

CachedNetworkImage(
  imageUrl: 'https://via.placeholder.com/350x150',
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
),
```

### With Progress Indicator

```dart
CachedNetworkImage(
  imageUrl: 'https://via.placeholder.com/350x150',
  progressIndicatorBuilder: (context, url, downloadProgress) =>
      CircularProgressIndicator(value: downloadProgress.progress),
  errorWidget: (context, url, error) => Icon(Icons.error),
),
```

### Advanced Usage (ImageBuilder)

Use this when you need an `ImageProvider` for things like `DecorationImage`:

```dart
CachedNetworkImage(
  imageUrl: 'https://via.placeholder.com/200x150',
  imageBuilder: (context, imageProvider) => Container(
    decoration: BoxDecoration(
      image: DecorationImage(
        image: imageProvider,
        fit: BoxFit.cover,
        colorFilter: ColorFilter.mode(Colors.red, BlendMode.colorBurn),
      ),
    ),
  ),
  placeholder: (context, url) => CircularProgressIndicator(),
  errorWidget: (context, url, error) => Icon(Icons.error),
),
```

### Direct ImageProvider Usage

```dart
Image(image: CachedNetworkImageProvider(url))
```

## ❓ FAQ

**Q: Will I lose my users' existing cache if I migrate?**
A: Yes. Because we switched the storage engine from SQLite to Hive, the old cache files will be ignored. Users will re-download images once as they browse. This is a one-time migration cost for a permanent performance gain.

**Q: My app crashes/pauses on errors?**
A: In Debug mode, Flutter may pause on exceptions even if they are caught. This is expected behavior for network errors (404s). In Release mode, these are handled silently by the `errorWidget`.

## 🤝 Contributing

We welcome contributions! If you want to help maintain this essential package, please check the [CONTRIBUTING.md](CONTRIBUTING.md).

## 📄 License

This project is licensed under the MIT License.

## Changelog
## [4.0.1] - 2026-02-19

* Added `repository` field for pub.dev source code display
* Updated README with benchmarks and architectural details
* Updated dependencies to `_ce` suffixed packages

## [3.4.1] - 2024-08-13

* Target js_interop for Wasm support

## [3.4.0] - 2024-04-10

* Change how errors are reported by ImageLoader. Emitting errors as streams instead of re-throwing.
* Improved debug console messages
* Update dependencies
* added static field defaultCacheManager to CachedNetworkImageProvider
* Expose scale of CachedNetworkImageProvider on CachedNetworkImage

## [3.3.1] - 2023-12-31

* Adding an errorListener prevents automatic reporting to global error handler.

## [3.3.0] - 2023-09-25

* Add error to ErrorListener
* Update to Dart 3
* Remove [`load`](https://github.com/flutter/flutter/pull/132679), use `loadImage` instead `loadBuffer`

Minor code clean-ups:

* Add topics in pubspec
* Specify types
* Update example

## [3.2.3] - 2022-11-25

* Correctly dispose image stream handler

## [3.2.2] - 2022-08-31

* loadBuffer is added and used instead of load

## [3.2.1] - 2022-05-16

* Update to Flutter 3

## [3.2.0] - 2021-11-29

* Add option to set the log level of the cache manager, for example:

```dart
CachedNetworkImage.logLevel = CacheManagerLogLevel.debug;
```

* Update cache manager dependency.

## [3.1.0+1] - 2021-11-04

* Update Readme

## [3.1.0] - 2021-07-16

* Separate Web and IO implementations

## [3.0.0] - 2021-03-27

* Migrate to null safety
* Fix "Cannot clone a disposed image" error
* Update dependencies.

## [3.0.0-nullsafety] - 2021-01-02

* Migrate to null safety

## [2.5.1] - 2021-03-09

* Update dependencies

## [2.5.0] - 2020-12-22

* Add support for resizing images in disk cache.

```dart
CachedNetworkImage(
  maxHeightDiskCache: 200,
  imageUrl: 'https://via.placeholder.com/3000x2000',
);
```

## [2.4.1] - 2020-12-01

* Fix a bug that an image is disposed when it shouldn't.

## [2.4.0] - 2020-11-30

* Added support for a cache key which is different from the image url.

## [2.3.3] - 2020-10-16

* Support for flutter_cache_manager 2.x.x.

## [2.3.2] - 2020-09-10

* Fixed placeholders and error widgets, those are not always centered anymore.
* Evict an image from ImageCache if image fails to load.
* Added method to evict an image from memory and disk cache.

## [2.3.1] - 2020-08-25

* Fixed fading when the image has no placeholder or progress indicator.

## [2.3.0] - 2020-08-25

* Improved image loading by using OctoImage. OctoImage uses the native callbacks of the ImageProvider instead of
 loading the file when the ImageWidget is build the first time.
* Set minimal Flutter version to 1.20.0; first compatible stable version.
* Added choice for rendering of images on web. Defaults to standard HTML ImageElement, but gives the option to use a
 custom HTTP Get for headers and skia support.
* Use a MultiImageStreamCompleter for when an image that is available in the cache is updated.

## [2.3.0-rc] - 2020-06-20

* Added choice for rendering of images on web. Defaults to standard HTML ImageElement, but gives the option to use a
 custom HTTP Get for headers and skia support.
* Use a MultiImageStreamCompleter for when an image that is available in the cache is updated.
* Increase minimal version of Flutter to 1.19.0-2.0.pre (currently requires Beta) due to an error listener bug.

## [2.3.0-beta.1] - 2020-05-28

* Improved web support: support for headers and skia.

## [2.3.0-beta] - 2020-05-20

* Rewrote image widget by using OctoImage.

## [2.2.0+1] - 2020-05-05

* Fix ImageProvider not using provided headers.

## [2.2.0] - 2020-04-30

* Upgrades on CachedNetworkImageProvider:
  * Support for download progress.
  * Basic web support (no caching).

## [2.1.0+1] - 2020-04-10

* Update minimal Dart sdk version

## [2.1.0] - 2020-04-10

* Update CacheManager
* Added option for progress indicator

## [2.0.0] - 2019-12-31

* Public release of 2.0 version

## [2.0.0-rc.1] - 2019-11-04

* Revert scaling of image due to issues with BoxFit.

## [2.0.0-rc] - 2019-10-17

* BREAKING CHANGE: Compatibility for [breaking change in Flutter 1.10.15](https://groups.google.com/forum/#!topic/flutter-announce/lUKzLAd8OG8)

## [1.1.3] - 2019-11-04

* Revert scaling of image due to issues with BoxFit.

## [1.1.2+1] - 2019-10-17

* Fix for widgets declared with infinite size.

## [1.1.2] - 2019-10-16

* Add filterQuality property.
* Scale image to size when showing in widget.
* Better error handling.
* Fix for useOldImageOnUrlChange.
* Update cache manager to 1.1.2.

## [1.1.1] - 2019-07-23

* Updated cache manager for error handling fix

## [1.1.0] - 2019-07-13

* Improved performance
* Keep fetched files in sync with filemanager.
* Better error handling.
* Added extra example to show the imageBuilder

## [1.0.0] - 2019-06-27

* Updated dependencies

## [0.8.0] - 2019-05-06

* Fixed compile error on informationCollector by temporarily disabling it.

## [0.7.0] - 2019-03-06

* BREAKING CHANGE: Renamed ErrorWidgetBuilder to LoadingErrorWidgetBuilder
* LoadingErrorWidgetBuilder returns an Object instead of an Exception
* Fixed BoxFit to also work when size is not defined

## [0.6.2] - 2019-02-27

* Added option to blend image with color
* Added option in CacheManager to clear the cache

## [0.6.1] - 2019-02-25 BREAKING CHANGES

* No longer assume infinite size.

## [0.6.0] - 2019-02-18 BREAKING CHANGES

* Breaking changes in API and behaviour
* Very much improved though
* Adapted for new cache manager library
* Completely rewritten image view
* Now using builders for placeholder and error widgets
* Added optional builder to customize the image

## [0.5.1] - 2018-11-19

* Fixed error throwing

## [0.5.0] - 2018-10-13

* Updated cache manager for http 0.12.0

## [0.4.2] - 2018-08-30

* Updated cache manager dependency

## [0.4.1] - 2018-04-27

* Improved error handling when a file could not be loaded.

## [0.4.0] - 2018-04-14

* Added optional headers.
* Changed to Dart 2.0
* Fixed bug when updating widget with new url

## [0.3.0] - 2018-02-09

* Added CachedNetworkImage with placeholder and error widgets.

## [0.2.1] - 2018-01-08

* Moved from OneFrameImageStreamCompleter to MultiFrameImageStreamCompleter.
* Updated CacheManager dependency for critical bug fix.

## [0.2.0] - 2017-12-29

* **Breaking change** Removed CachedNetworkImage. From now on only the ImageProvider is supported. For a placeholder use `FadeInImage`. See also ["Fallback for Network Images"](https://github.com/flutter/flutter/issues/6229).
* Moved CacheManager to a separate library for a more generic purpose.

## [0.1.0] - 2017-12-21

* **Breaking change**. Upgraded to Gradle 4.1 and Android Studio Gradle plugin
  3.0.1. Older Flutter projects need to upgrade their Gradle setup as well in
  order to use this version. Instructions can be found
  [here](https://github.com/flutter/flutter/wiki/Updating-Flutter-projects-to-Gradle-4.1-and-Android-Studio-Gradle-plugin-3.0.1).

## [0.0.2] - 10 December 2017

Added an ImageProvider and improved documentation

## [0.0.1] - 2 December 2017

Initial release, should be polished