flutter_image_cache_placeholder 1.0.0

A high-performance progressive image loading widget for Flutter that combines CachedNetworkImage, BlurHash, dominant colors, and smooth fade transitions.

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.

---

License

MIT © 2026 Maximil Christian.