CachedNetworkImage: key concepts and the ImageProvider widget

What is CachedNetworkImage?

CachedNetworkImage is a Flutter widget from the eponymous pub.dev package that provides network image loading with automatic caching. It is a wrapper around the standard Image.network, adding file caching, progress indicators and custom error handling.

Internally, CachedNetworkImage uses flutter_cache_manager — a cache manager with an SQLite database for tracking files. On the first request, the image is downloaded from the network, saved to disk, and on subsequent requests it is served from cache taking into account TTL (default 7 days). In-memory caching is managed by Flutter’s standard ImageCache.

The package has over 4,000 likes on pub.dev and is used in thousands of Flutter projects. CachedNetworkImage supports all Flutter platforms: Android, iOS, Web, macOS, Windows and Linux. Thanks to a unified API, developers get cross-platform image loading without platform-specific code.

How Image Caching Works in Flutter

Flutter uses a two-level caching system: ImageCache (memory) and flutter_cache_manager (disk + SQLite). ImageCache is a global cache of decoded images with limits on count (default 1000) and size (default 100 MB). flutter_cache_manager manages files on disk and their metadata.

Lookup Sequence

When CachedNetworkImage receives an image request, it first checks Flutter’s ImageCache — if the image is already decoded in memory, it is displayed instantly. On a cache miss, the disk is checked via flutter_cache_manager: an SQLite query checks if the file exists in cache and whether its TTL has expired. If the file is current — it is read from disk, decoded and displayed. If the file is missing or TTL has expired — an HTTP request is made.

• ImageCache — global Flutter cache, 1000 items / 100 MB by default
• flutter_cache_manager — SQLite + file system, TTL 7 days
• HTTP download — performed via the http package or custom HttpClient

Cache Cleanup

DefaultCacheManager provides emptyCache() (full cleanup), cleanCache() (remove only expired) and clearCacheWithAge() with a custom date. ImageCache is cleared automatically on memory pressure or manually via imageCache.clear().

CachedNetworkImage Widget Architecture

CachedNetworkImage is built on standard Flutter widget composition. The internal implementation uses ImageProvider for asynchronous loading and StatefulWidget for lifecycle management.

Key Parameters

imageUrl — required parameter, the image URL (String or Uri). placeholder — widget displayed during loading. errorWidget — widget on loading error. progressIndicatorBuilder — builder that receives context, URL and DownloadProgress with totalSize and downloadedSize fields.

ImageProvider

CachedNetworkImageProvider — an ImageProvider implementation that returns CachedNetworkStreamImage, which manages downloading and caching. The provider integrates with Flutter’s ImageCache and supports all standard ImageProvider capabilities: scaling, centering and repetition.

Configuring flutter_cache_manager

flutter_cache_manager is the library underlying CachedNetworkImage’s caching. It provides DefaultCacheManager with a configured SQLite database, TTL and file limit. If needed, a custom CacheManager can be created with unique parameters.

A custom CacheManager is created by inheriting from CacheManager with method overrides. This is useful when images need to be stored in a separate directory or a different HTTP client is required. The manager instance is then passed to the cacheManager parameter of CachedNetworkImage.

DefaultCacheManager’s SQLite database is located in the application’s temporaryDirectory at the path `{key}/CacheObjects.db`. It contains the cacheObjects table with fields: key (URL), relativePath, url, creationDate, eTag, httpHeaders. When cleaning up expired entries, an SQL query with a condition on maxAgeCacheObject is used.

CachedNetworkImage Usage Examples in Dart

CachedNetworkImage provides two main loading approaches: the CachedNetworkImage widget and the CachedNetworkImageProvider for custom scenarios.

Basic Loading with Placeholder

CachedNetworkImage — the primary approach. Simply pass imageUrl and placeholder. The widget automatically displays the placeholder until loading completes and replaces it with the image.

CachedNetworkImage(
    imageUrl: "https://example.com/photo.jpg",
    placeholder: (context, url) => CircularProgressIndicator(),
    errorWidget: (context, url, error) => Icon(Icons.error),
    width: 200,
    height: 200,
    fit: BoxFit.cover,
)

placeholder and errorWidget are builder functions that accept context, URL and (for errorWidget) an error object. This approach allows displaying different placeholders depending on the URL or error type.

Loading with Progress

progressIndicatorBuilder — a parameter that allows displaying download progress as a percentage. DownloadProgress contains totalSize (may be -1 if unknown) and downloadedSize.

CachedNetworkImage(
    imageUrl: "https://example.com/large.jpg",
    progressIndicatorBuilder: (context, url, downloadProgress) {
        return Center(
            child: SizedBox(
                width: 50,
                height: 50,
                child: Stack(
                    alignment: Alignment.center,
                    children: [
                        CircularProgressIndicator(
                            value: downloadProgress.progress,
                        ),
                        Text(
                            "\(downloadProgress.downloadedSize ~/ 1024) KB",
                        ),
                    ],
                ),
            ),
        };
    },
    imageBuilder: (context, imageProvider) {
        return Container(
            decoration: BoxDecoration(
                borderRadius: BorderRadius.circular(12),
                image: DecorationImage(
                    image: imageProvider,
                    fit: BoxFit.cover,
                ),
            ),
        };
    },
)

imageBuilder — an optional parameter that allows customizing image display: adding rounded corners, shadows, decorations. The example uses DecorationImage with BorderRadius for rounded corners.

Using CachedNetworkImageProvider

CachedNetworkImageProvider — a provider for Image or DecorationImage without using the CachedNetworkImage widget. Useful when working with BoxDecoration, FadeInImage or custom Image widgets.

Container(
    decoration: BoxDecoration(
        image: DecorationImage(
            image: CachedNetworkImageProvider(
                "https://example.com/bg.jpg",
                maxWidthBytes: 2048,
                maxHeightBytes: 2048,
            ),
            fit: BoxFit.cover,
        ),
    ),
)

ImageBuilder and Custom Handling

The imageBuilder parameter in CachedNetworkImage allows overriding the standard Image widget with a custom implementation. Instead of directly displaying the Image, you can use a Container with decoration, ClipRRect for cropping, or Ink.image for ripple effects. imageBuilder receives context and ImageProvider of the ready image, giving full control over rendering.

Additional parameters: memCacheWidth and memCacheHeight limit the cached image size in RAM, reducing load on Flutter’s ImageCache. cacheKey allows setting a custom cache key instead of the URL, which is useful for images with authorization tokens in the URL (query parameters change with each request but the content remains the same).

CachedNetworkImage vs Standard Image.network

The standard Image.network widget loads the image on every widget rebuild without saving to disk. CachedNetworkImage adds file caching, progress indicators and error handling, but adds a dependency on flutter_cache_manager and SQLite.

For projects where offline capability and bandwidth savings are important, CachedNetworkImage is the clear choice. For simple one-off screens (e.g. onboarding or splash), Image.network requires no additional dependencies.

Setting Up CachedNetworkImage in a Flutter Project

CachedNetworkImage is added as a standard pub.dev dependency. After installation, the widget is ready to use. flutter_cache_manager is included as a transitive dependency.

// pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  cached_network_image: ^3.4.1

By default, DefaultCacheManager is used with settings: TTL = 7 days, max 200 files. To change global parameters, a custom CacheManager instance is created with Config, where maxAgeCacheObject, maxNrOfCacheObjects and repo are overridden.

import 'package:cached_network_image/cached_network_image.dart';
import 'package:flutter_cache_manager/flutter_cache_manager.dart';

final customCacheManager = CacheManager(
  Config(
    "custom_images",
    stalePeriod: Duration(days: 14),
    maxNrOfCacheObjects: 500,
    repo: JsonCacheInfoRepository(
      databaseName: "custom_images_cache.db",
    ),
  ),
);

// Using a custom manager:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes and maxHeightBytes — optional parameters for limiting the cached file size. This is useful for saving disk space when the original image is larger than the required screen size.