Search packages, repositories and app categories

ducafecatFlutter ecosystem guide
Package detailsv4.0.6

cached_network_image

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

AndroidiOSWebmacOSWindowsLinux
pub.dev API documentation Source code
30-day downloads
3.7M
Likes
7K
Pub points
150

Install package

flutter pub add cached_network_image

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

A Flutter package for efficiently loading and caching network images with support for placeholders and error widgets. It reduces redundant downloads by storing images locally, improving app performance and reducing bandwidth usage. Ideal for apps displaying大量 images from remote sources, such as social media feeds or product catalogs. The library handles image loading asynchronously and provides customizable UI for loading states and failures.

Use cases

  • Displaying dynamic image content in apps
  • Loading images from remote servers efficiently
  • Showing placeholder images during loading
  • Handling image load failures gracefully
  • Reducing data usage through local caching
  • Building image-heavy user interfaces

Key features

  • Automatic image caching
  • Customizable placeholder and error widgets
  • Support for all major platforms
  • Efficient memory and disk management
  • Asynchronous image loading
  • Configurable cache size and duration

Suitable for

  • Apps with frequent image fetching
  • Developers prioritizing performance and UX
  • Projects requiring offline image access
  • Social media and e-commerce applications
  • Apps targeting multiple platforms

Considerations

  • Requires proper cache management to avoid storage issues
  • May need tuning for large image sets
  • Platform-specific behavior may vary slightly
  • Initial setup requires understanding of caching strategies
  • Not ideal for very small, static image collections

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

Cached network image

pub package codecov Build Status

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

Sponsors


Try the Flutter Chat Tutorial 💬

How to use

The CachedNetworkImage can be used directly or through the ImageProvider. Both the CachedNetworkImage as CachedNetworkImageProvider have minimal support for web. It currently doesn't include caching.

With a placeholder:

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

Or with a progress indicator:

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

Image(image: CachedNetworkImageProvider(url))

When you want to have both the placeholder functionality and want to get the imageprovider to use in another widget you can provide an imageBuilder:

CachedNetworkImage(
  imageUrl: "http://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),
),

How it works

The cached network images stores and retrieves files using the flutter_cache_manager.

FAQ

My app crashes when the image loading failed. (I know, this is not really a question.)

Does it really crash though? The debugger might pause, as the Dart VM doesn't recognize it as a caught exception; the console might print errors; even your crash reporting tool might report it (I know, that really sucks). However, does it really crash? Probably everything is just running fine. If you really get an app crashes you are fine to report an issue, but do that with a small example so we can reproduce that crash.

See for example this or this answer on previous posted issues.

Categories

Cache & Temporary StorageImage

Dependencies

Dependency list 5 items

Source repository

Projects using this package