cached_network_image_ce 4.12.0

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

4.12.0 - 2026-09-08

• Feature: Added animate to CachedNetworkImage and CachedNetworkImageProvider (default true). With animate: false a multi-frame image such as a GIF shows its first frame and stops there, without decoding the rest. animate is part of the provider key, so toggling it at runtime resolves a different image stream: the widget paints nothing while that stream resolves, and which frame it starts on depends on what the ImageCache still holds. Wrap the widget in a TickerMode to pause and resume an animation in place. Requested in issue #21.
• Fix: CachedNetworkImage.evictFromCache now forwards cacheKey to the provider it evicts and clears both the animate: true and animate: false entries, so the in-memory ImageCache eviction is no longer a silent no-op for images rendered with a cacheKey or with animate: false.

4.11.1 - 2026-09-08

• Fix: Images turned black on web after the widget was scrolled out of view and back. MultiImageStreamCompleter re-decoded the codec on every 0→1 listener transition; for a single-frame image on CanvasKit that produces a second lazy ui.Image sharing one <img> element, and emitting it disposes the previous image, which clears that element's src. The already decoded frame is now handed to the returning listener instead. Animated images still resume decoding. Reported by @tranhuudang (issue #67).
• Fix: The completer handed the codec's own ui.Image to ImageInfo instead of a clone and never disposed _nextFrame, so every decode that was abandoned (listener dropped mid-decode) or superseded leaked a ui.Image. Frames are now cloned into ImageInfo and the decoded frame is disposed once handed over, matching the framework's MultiFrameImageStreamCompleter. That is also the ownership bug behind the black image above: setImage disposing the previous ImageInfo no longer releases a handle the codec's decoded frame still owns.
• Fix: A frame could be emitted under a codec that had already replaced the one it was decoded from. _decodeNextFrameAndSchedule now captures its codec and discards the frame if the codec changed during the await, instead of evaluating frameCount against the new codec — which could terminate a running animation and mis-count the new codec's frames.
• Fix: Adding a listener while a decode was already in flight started a second, concurrent decode of the same codec, so two frames could be emitted and dispose each other's image. addListener no longer starts a decode while one is pending.
• Fix: A null-check crash when a replacement codec arrived between an animated frame being decoded and its scheduled app-frame callback running, or when a listener removed and re-added itself from the setImage callback. Both released the pending frame while _handleAppFrame was still reading it. The callback now takes the frame before notifying listeners and returns quietly if the frame it was scheduled for is already gone, and decoding a codec that already has a frame in flight is a no-op.
• Fix: Replaced codecs are now disposed instead of dropped, so a cache hit followed by a network refresh no longer retains the outgoing decoder for the life of the completer. A codec replaced while one of its frames is still decoding is disposed by that decode when it returns, since disposing it earlier would fail the pending getNextFrame().

4.11.0 - 2026-09-01

• Feature: Added CachedNetworkImage.preCache() static method for downloading and caching images without rendering them. Useful for warming the cache before navigation. Supports optional cacheKey, headers, custom cacheManager, disk-resize parameters (maxWidthDiskCache, maxHeightDiskCache), and an optional timeout. Throws a StateError instead of silently returning a stale file when refreshing an expired cache entry fails, and an ArgumentError (not just an assert) when resize parameters are used with a CacheManager that isn't an ImageCacheManager.

4.10.1 - 2026-08-26

• Fix: PathNotFoundException when the background cleanup sweep deleted a cached file after getFileFromCache had already handed out its FileInfo but before the image was read. The sweep starts unawaited during initialization, so on cold start every first-frame load raced it. A cached file that disappears mid-read now falls back to a fresh download instead of throwing. Applies to the resize path too, which reads the separately-evictable original entry.
• Fix: getImageFile removed its in-flight resize entry only after its stream completed, so abandoning that stream left every later call for the same key waiting on a stream that had already finished, and no image was ever delivered.
• Fix: putFile now awaits its Hive metadata write instead of returning while the write is still unsequenced.
• Behaviour change: The cleanup sweep skips entries served within the last 30 seconds, so an image still being loaded is not evicted out from under its reader. Skipped entries lose their place in the eviction order but not the size budget, so maxNrOfCacheObjects is still honoured.

reported by @aycasecr — thanks! (PR #62)

4.10.0 - 2026-07-30

• Performance: DefaultCacheManager now reuses a single HTTP client across downloads instead of creating and closing one per request, so connections can be kept alive between images.
• Fix: A connection timeout now aborts the in-flight request instead of leaving it running in the background.
• Fix: dispose() closes the reused client. Downloads started after disposal create their own client, which is closed once its last response is released.
• Behaviour change: dispose() called while a download is in flight now aborts that download; previously each download owned its client and could outlive dispose().
• Behaviour change: An onResponse interceptor that replaces the response must not derive the replacement body from the original response's stream — the original body is now canceled as soon as it is replaced, to release its connection.

contributed by @Chlx42 — thanks! (PR #58)

4.9.1 - 2026-07-23

• Fix: Codec decode failures (e.g. JXL, or AVIF/HEIC on platforms without native support) now route to unsupportedImageBuilder instead of errorBuilder. Previously only pre-detected formats (SVG) were routed this way via UnsupportedImageFormatException; any other codec decode failure fell through as a generic, untyped error.

4.9.0 - 2026-06-19

• Feature: Added metadataDirectoryProvider to DefaultCacheManager so Hive metadata can be stored separately from cached image files on IO platforms.
• Fix: Isolate the orphan-file cleanup sweep per metadata directory, so two DefaultCacheManager instances sharing a cacheDirectoryProvider but different metadataDirectoryProvider no longer delete each other's files. dispose() now awaits any in-flight sweep instead of racing it.

4.8.0 - 2026-06-16

• Feature: Added LRU cache cleanup support to DefaultCacheManager.
  • New CleanupStrategy abstraction controls eviction order when the cache exceeds maxNrOfCacheObjects.
  • TtlCleanupStrategy — evicts soonest-to-expire entries first. Matches prior behaviour and remains the default.
  • LruCleanupStrategy — evicts least-recently-used entries first, based on a new touchedAt timestamp updated on every cache hit.
  • CacheEntryMetadata gains a nullable touchedAt field; legacy entries without it fall back to validTill via effectiveTouchedAt.
  • Pass a strategy via the new cleanupStrategy parameter on DefaultCacheManager, or implement CleanupStrategy for a custom eviction policy.

4.7.0 - 2026-06-10

• Feature: Added HTTP and cache interceptor support to DefaultCacheManager.
  • HttpInterceptor — intercept, mutate, or short-circuit HTTP requests, responses, and errors before they reach the cache layer.
  • CacheInterceptor — intercept cache hit, miss, and store events. Reject a hit to force re-download; resolve a miss to inject a synthetic file; reject a store to skip writing metadata to Hive.
  • Pass interceptors via the new httpInterceptors and cacheInterceptors parameters on DefaultCacheManager.
  • CacheInterceptor and its handler types are only available on native IO targets; a no-op stub is exported for web.
  • Full test coverage for all interceptor chain paths.

4.6.4 - 2026-03-24

• Fix: Resolve HiveError crashes caused by URL string keys exceeding 255 characters. Long cache keys are now automatically hashed using SHA-256 to remain under Hive's 255-character length limit.

4.6.3 - 2026-03-15

• Fix: Handle exceptions when closing the Hive cache box and Hive instance during dispose(). (PR #17)
  • PathNotFoundException (e.g. when the cache directory was deleted before dispose) is now silently swallowed so callers can dispose without wrapping in try-catch.
• Feat: Ensure the cache directory exists before any file read/write operation. (PR #17)
  • Prevents PathNotFoundException on first use when the OS or test harness removes the temp directory between initialisation and the first cache put/get.
• Added regression tests for cache-directory resilience and for safe disposal after emptyCache(). (PR #17)

4.6.2 - 2026-03-04

• Fix: Handle Hive box corruption gracefully during cache initialization.
  • When openBox encounters a corrupted box with unknown typeIds (e.g., from removed adapters), catch HiveError, safely delete the box, and retry initialization.
  • Cleans up orphaned cache files after box recovery to prevent stale data.
  • Regression tests added for box corruption recovery on both IO and web platforms.
  • Issue #12: Fixes production crash "HiveError: Cannot read, unknown typeId" reported via Firebase Crashlytics.

4.6.1 - 2026-03-04

• Fix: Re-export ConnectionParameters from the main cached_network_image_ce barrel file so it is accessible without a separate cached_network_image_platform_interface_ce import.
• Fix: Added missing connectionParameters parameter to the stub DefaultCacheManager for unsupported platforms.
• Added example demonstrating DefaultCacheManager with ConnectionParameters.

4.6.0 - 2026-03-03

• Feature: Added optional HTTP timeout support via ConnectionParameters on DefaultCacheManager.
  • connectionTimeout limits time waiting for response headers.
  • requestTimeout applies an inactivity timeout while streaming response bytes.
  • Existing behavior is preserved when connectionParameters is not provided.
• Added tests for timeout behavior and client cleanup on timeout.

4.5.0 - 2026-03-02

• Feature: Added web platform support. The package can now be used in Flutter web apps.
  • Web caching uses Hive CE backed by IndexedDB — no new dependencies needed.
  • Image bytes and metadata are stored in Hive boxes on web instead of the file system.
  • Disk-based image resizing is skipped on web (originals are cached as-is).
  • The DefaultCacheManager is now conditionally imported per platform (IO/web).

4.4.0 - 2026-02-27

• Feature: Skip placeholder and fade animations when images are loaded from disk cache. Cached images now appear instantly without unnecessary visual flicker.
• Added disablePlaceholderOnCacheHit parameter (default true) to opt out of this behavior.
• CachedNetworkImage is now a StatefulWidget to support async cache pre-checking.

4.3.0 - 2026-02-26

• Feature/Deprecation: Added errorBuilder to CachedNetworkImage and CachedImageWidget, which aligns with Flutter's standard ImageErrorWidgetBuilder. The old errorWidget property is now deprecated.
• Fix: Resolved a memory leak where errorListener would prevent CachedNetworkImage from being garbage collected. Uses addEphemeralErrorListener on Flutter >= 3.16.

4.2.0 - 2026-02-23

• Feature: Added SVG support via new unsupportedImageBuilder callback
  • New UnsupportedImageFormatException thrown when image format is not supported by Flutter's standard codec
  • New ImageFormatDetector utility with content sniffing for SVG detection
  • Images are still cached normally; only rendering path differs
  • Example app updated with SVG demo using flutter_svg
  • 24 new tests added (18 format detection + 6 widget integration)
  • See README for usage example

4.1.1 - 2026-02-20

• Fix: Removed global Hive.init() usage from DefaultCacheManager to avoid conflicts with host app Hive initialization
• Fix: Added initialization synchronization in DefaultCacheManager to prevent parallel cold-start race conditions
• Fix: Switched cache metadata box opening to explicit openBox(path: ...) on a private Hive instance for reliable isolation
• Feature: Added optional cacheDirectoryProvider parameter to DefaultCacheManager so apps can control cache storage location
• Tests: Added regression tests for Hive init conflicts, concurrent initialization races, and cache directory resilience scenarios

4.1.0 - 2026-02-19

• Feature: Added httpClientFactory parameter to DefaultCacheManager for HTTP client dependency injection, enabling easy mocking in tests
• Refactor: Replaced raw Map<String, dynamic> with typed CacheEntryMetadata class for all cache metadata operations
• Tests: Comprehensive test coverage (131 tests, 86% coverage)
  • DefaultCacheManager: HTTP download success/errors, progress reporting, header forwarding, cache hit/miss/stale behavior, cleanup logic (31 tests)
  • Leak tests: StreamController closure, http.Client cleanup, file sink closure, ImageLoader chunkEvents, MultiImageStreamCompleter disposal, Hive box lifecycle (19 tests)
  • ImageLoader, CachedNetworkImageProvider, CacheEntryMetadata coverage
• Fix: Resolved analyzer warnings across all packages

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, 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:

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.

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

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".
• 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.

0.0.2 10 December 2017

Added an ImageProvider and improved documentation

0.0.1 2 December 2017

Initial release, should be polished