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

Parameter	Type	Default	Description
url	String	''	Network URL (absolute or relative to baseUrl)
path	String	''	Asset path
filePath	String	''	Local file path (not on web)
bytes	Uint8List?	–	Raw image bytes
width / height	double?	–	Size
fit	BoxFit?	cover	How the image fills its box
shape	AppImageShape	rectangle	rectangle / rounded / circle
borderRadius	BorderRadius?	12 for rounded	Corner radius
border	BoxBorder?	–	Border around the shaped image
loaderType	AppImageLoaderType	shimmer	none / circular / shimmer / skeleton / custom
customLoader	Widget?	–	Used with LoaderType.custom
placeholderType	AppImagePlaceholderType	image	none / person / image / custom
customPlaceholder	Widget?	–	Used with PlaceholderType.custom
placeholderAsset	String?	–	Asset shown by the image placeholder
errorWidget	Widget?	–	Full override of the error UI
enableZoom	bool	false	Tap opens full-screen pinch/double-tap viewer
heroTag	Object?	–	Hero transition into the viewer
headers	Map<String,String>?	–	HTTP headers (e.g. auth token)
cacheManager	BaseCacheManager?	built-in	Custom cache rules
maxRetries / retryDelay	–	config	Per-widget retry overrides
optimizeUrl + optimizedWidth/Height	–	config	Server-side resize query params
color	Color?	–	Tint color
semanticLabel	String?	–	Accessibility label

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.