flutter_image_cache_placeholder

A high-performance progressive image loading widget for Flutter. It combines cached_network_image, flutter_blurhash, dominant colors, and smooth cross-fades into a single widget with zero setup required.

Features

📱 All-in-One API: Easily fetch from Network, Assets, or Memory byte arrays.
💾 Smart Network Caching: Built-in support for caching image assets locally using cached_network_image.
🎨 Multi-Stage Progressive Loading: Fades smoothly through multiple loading levels:
1. Dominant Color (Instant solid fallback)
2. BlurHash (Decoded visual representation)
3. Low-Resolution Preview (Small thumbnail load)
4. High-Resolution Main Image (Sharp final output)
🌀 Zero Configuration: Sensible default presets so you only need to write two lines of code out of the box.
⚙️ Highly Customizable: Custom dimensions, border radius, animations, fit/alignment models, HTTP headers, cache keys, and error placeholders.

Installation

Add the package to your pubspec.yaml:

dependencies:
  flutter_image_cache_placeholder:
    path: ../flutter-image-cache-placeholder # Or package name once published

Usage

1. Simple Example (Network with BlurHash)

import 'package:flutter_image_cache_placeholder/flutter_image_cache_placeholder.dart';

ImageCachePlaceholder(
  imageUrl: post.imageUrl,
  blurHash: post.blurHash,
)

2. Full Progressive Loading (Dominant Color -> BlurHash -> Low-Res -> High-Res)

By specifying lowResImageUrl or lowResAssetPath, the widget will load the lightweight preview image first and smoothly transition to the high-resolution source.

ImageCachePlaceholder(
  imageUrl: 'https://example.com/high-res-image.jpg',
  lowResImageUrl: 'https://example.com/low-res-thumbnail.jpg',
  blurHash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj',
  dominantColor: Color(0xFF2C3E50),
  width: double.infinity,
  height: 250,
  fit: BoxFit.cover,
  fadeDuration: Duration(milliseconds: 500),
  borderRadius: BorderRadius.circular(16),
)

3. Asset and Memory Loading

You can pass assetPath or bytes as the main image source:

// Load an Asset
ImageCachePlaceholder(
  assetPath: 'assets/images/gallery_item.png',
  blurHash: 'L6PZfXYe00IX.JbH.7x[00t7_4Rj',
  width: 200,
  height: 200,
  borderRadius: BorderRadius.circular(8),
)

// Load from Memory
ImageCachePlaceholder(
  bytes: imageBytes,
  blurHash: 'L6PZfXYe00IX.JbH.7x[00t7_4Rj',
  width: 150,
  height: 150,
)

Customization API

Attribute	Type	Default	Description
`imageUrl`	`String?`	`null`	Target high-res image URL.
`assetPath`	`String?`	`null`	Target asset image path.
`bytes`	`Uint8List?`	`null`	Target memory image byte data.
`lowResImageUrl`	`String?`	`null`	Low-resolution preview network URL.
`lowResAssetPath`	`String?`	`null`	Low-resolution preview asset path.
`blurHash`	`String?`	`null`	BlurHash placeholder string.
`dominantColor`	`Color?`	`Color(0xFFF3F4F6)`	Solid container background color.
`width` / `height`	`double?`	`null`	Layout size constraints.
`fit`	`BoxFit`	`BoxFit.cover`	How the image fits into its layout constraints.
`alignment`	`Alignment`	`Alignment.center`	Image placement alignment.
`fadeDuration`	`Duration`	`400ms`	Transition animation duration.
`borderRadius`	`BorderRadius?`	`null`	Optional border clipping.
`errorWidget`	`Widget?`	`null`	Fallback widget shown when loading fails.
`customPlaceholder`	`Widget?`	`null`	Overwrites dominant color and blurhash with a custom widget.
`headers`	`Map<String, String>?`	`null`	Custom HTTP headers.
`cacheKey`	`String?`	`null`	Custom key used for image caching.