app_image_widgets #

All-in-one image widget for Flutter. One widget, every source, every format.

• 🌐 Network images with caching (7-day, 300 files), automatic retry, auth headers and relative-URL resolution
• 📦 Asset, 📁 file and 🧠 memory (Uint8List) images
• 🖼️ Formats: PNG, JPEG/JPG, WebP, GIF, BMP (Flutter native)
• ⏳ Loaders: shimmer, circular, skeleton, none, or your own widget
• 🧍 Placeholders: person (avatars), image icon, custom widget, custom asset
• ⭕ Shapes: circle, rounded, rectangle — with optional border
• 🔍 Tap-to-open full-screen viewer with pinch zoom and smart double-tap zoom
• 🛡️ Every code path has error handling — a broken image never crashes your UI

Quick start #

dependencies:
  app_image_widgets: ^1.0.0

import 'package:app_image_widgets/app_image_widgets.dart';

// Network (cached + retried)
AppImage(url: 'https://example.com/photo.webp')

// Relative URL — resolved against your configured base URL
AppImage(url: '/storage/avatar.png')

// Asset / file / memory
AppImage(path: 'assets/images/logo.png')
AppImage(filePath: pickedFile.path)
AppImage(bytes: myUint8List)

// Circle avatar with person placeholder
AppImage(
  url: user.photoUrl,
  width: 72,
  height: 72,
  shape: AppImageShape.circle,
  placeholderType: AppImagePlaceholderType.person,
  loaderType: AppImageLoaderType.shimmer,
)

// Zoomable banner
AppImage(
  url: post.bannerUrl,
  height: 200,
  enableZoom: true,
  shape: AppImageShape.rounded,
)

Global configuration (optional, once in main()) #

AppImageConfig.baseUrl = 'https://api.your-domain.com';
AppImageConfig.maxRetries = 3;
AppImageConfig.retryDelay = const Duration(seconds: 2);
AppImageConfig.defaultPlaceholderAsset = 'assets/images/placeholder.png';
AppImageConfig.optimizeNetworkImages = true; // appends ?width=&height= if your server resizes
AppImageConfig.enableLogs = true;            // debug-only logging

Parameters #

Source priority #

If you pass several sources, the first non-empty one wins: bytes → filePath → url → path.

Error handling #

Every source has an errorBuilder, network images retry with eviction + backoff, and the final fallback is always your chosen placeholder — broken images degrade gracefully instead of throwing.

Testing #

flutter pub get
flutter analyze
flutter test                       # unit + widget tests
cd example && flutter test ../integration_test/app_image_integration_test.dart -d <device-id>

Web notes #

• filePath is not supported on web (it logs and shows the placeholder).
• Network caching falls back to the browser's cache behavior.