ImageCache class

Class for caching images.

Implements a least-recently-used cache of up to 1000 images, and up to 100 MB. The maximum size can be adjusted using maximumSize and maximumSizeBytes.

The cache also holds a list of "live" references. An image is considered live if its ImageStreamCompleter's listener count has never dropped to zero after adding at least one listener. The cache uses ImageStreamCompleter.addOnLastListenerRemovedCallback to determine when this has happened.

The putIfAbsent method is the main entry-point to the cache API. It returns the previously cached ImageStreamCompleter for the given key, if available; if not, it calls the given callback to obtain it first. In either case, the key is moved to the "most recently used" position.

A caller can determine whether an image is already in the cache by using containsKey, which will return true if the image is tracked by the cache in a pending or completed state. More fine grained information is available by using the statusForKey method.

Generally this class is not used directly. The ImageProvider class and its subclasses automatically handle the caching of images.

A shared instance of this cache is retained by PaintingBinding and can be obtained via the imageCache top-level property in the painting library.

This sample shows how to supply your own caching logic and replace the global imageCache variable.
/// This is the custom implementation of [ImageCache] where we can override
/// the logic.
class MyImageCache extends ImageCache {
  void clear() {
    print("Clearing cache!");

class MyWidgetsBinding extends WidgetsFlutterBinding {
  ImageCache createImageCache() => MyImageCache();

void main() {
  // The constructor sets global variables.

class MyApp extends StatelessWidget {
  Widget build(BuildContext context) {
    return Container();




currentSize int
The current number of cached entries.
currentSizeBytes int
The current size of cached entries in bytes.
hashCode int
The hash code for this object. [...]
read-only, inherited
liveImageCount int
The number of live images being held by the ImageCache. [...]
maximumSize int
Maximum number of entries to store in the cache. [...]
read / write
maximumSizeBytes int
Maximum size of entries to store in the cache in bytes. [...]
read / write
pendingImageCount int
The number of images being tracked as pending in the ImageCache. [...]
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited


clear() → void
Evicts all pending and keepAlive entries from the cache. [...]
clearLiveImages() → void
Clears any live references to images in this cache. [...]
containsKey(Object key) bool
Returns whether this key has been previously added by putIfAbsent.
evict(Object key, {bool includeLive: true}) bool
Evicts a single entry from the cache, returning true if successful. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
putIfAbsent(Object key, ImageStreamCompleter loader(), {ImageErrorListener onError}) ImageStreamCompleter
Returns the previously cached ImageStream for the given key, if available; if not, calls the given callback to obtain it first. In either case, the key is moved to the "most recently used" position. [...]
statusForKey(Object key) ImageCacheStatus
The ImageCacheStatus information for the given key.
toString() String
Returns a string representation of this object.


operator ==(Object other) bool
The equality operator. [...]