CustomImageView

CustomImageView is a single Flutter widget for the image sources most apps use every day: cached raster network images, network SVGs, asset images, asset SVGs, local files, and XFile values from image_picker.

Features

  • Cached raster network images through CachedNetworkImage.
  • Configurable cache keys, cache managers, HTTP headers, memory resize cache, and disk resize cache for network images.
  • Network SVGs through svgUrl.
  • Network SVGs are fetched through flutter_cache_manager so repeated SVG loads reuse the cache.
  • Automatic .svg URL detection when using the existing url parameter.
  • Asset SVGs through svgPath.
  • Automatic .svg asset detection when using imagePath.
  • Local File and XFile rendering, including .svg local paths.
  • In-memory raster and SVG rendering with bytes and svgBytes.
  • Download progress UI with progressIndicatorBuilder.
  • Accessibility controls with semanticsLabel and excludeFromSemantics.
  • Web-safe public library: local file rendering is behind conditional imports, so web builds can still use network, asset, SVG, and XFile path sources.
  • Shared controls for size, fit, alignment, color, color filter, blend mode, margin, radius, border, tap handling, placeholders, and error builders.

Installation

dependencies:
  custom_image_view: ^5.1.1

Then import it:

import 'package:custom_image_view/custom_image_view.dart';

Source Priority

If more than one source is provided, the widget uses the first available source in this order:

Priority Parameter Supports
1 svgUrl Network SVG
2 svgPath Asset SVG, network SVG URL
3 svgBytes In-memory SVG bytes
4 bytes In-memory raster image bytes
5 file Local raster file, local SVG file
6 xFile Picked raster file, picked SVG file
7 url Cached raster network image, network SVG URL
8 imagePath Asset raster image, asset SVG

Caching

Raster network images use CachedNetworkImage. Network SVGs use flutter_cache_manager through the same cacheManager, cacheKey, and httpHeaders parameters.

CustomImageView(
  url: 'https://example.com/profile.png',
  cacheKey: 'user-42-profile',
  httpHeaders: const {
    'Authorization': 'Bearer token',
  },
  memCacheWidth: 300,
  memCacheHeight: 300,
  maxWidthDiskCache: 600,
  maxHeightDiskCache: 600,
  useOldImageOnUrlChange: true,
  progressIndicatorBuilder: (context, url, progress) {
    return CircularProgressIndicator(value: progress.progress);
  },
)

Use a custom cache manager when you need a different stale period or cache size:

CustomImageView(
  url: 'https://example.com/photo.png',
  cacheManager: customCacheManager,
)

Evict a URL from cache when the remote image changes:

await CustomImageView.evictFromCache(
  'https://example.com/profile.png',
  cacheKey: 'user-42-profile',
);

Examples

Cached Network Image

CustomImageView(
  url: 'https://example.com/photo.png',
  height: 120,
  width: 120,
  fit: BoxFit.cover,
  radius: BorderRadius.circular(12),
)

Network SVG

CustomImageView(
  svgUrl: 'https://example.com/icon.svg',
  cacheKey: 'brand-icon',
  height: 48,
  width: 48,
  color: Colors.blue,
)

You can also pass a .svg URL through url:

CustomImageView(
  url: 'https://example.com/icon.svg',
  height: 48,
  width: 48,
)

Asset Image

CustomImageView(
  imagePath: 'assets/images/avatar.png',
  height: 64,
  width: 64,
  fit: BoxFit.cover,
)

Memory Image

CustomImageView(
  bytes: imageBytes,
  height: 100,
  width: 100,
  fit: BoxFit.cover,
)

Memory SVG

CustomImageView(
  svgBytes: svgBytes,
  height: 100,
  width: 100,
  fit: BoxFit.contain,
)

Asset SVG

CustomImageView(
  svgPath: 'assets/icons/logo.svg',
  height: 48,
  width: 48,
  colorFilter: const ColorFilter.mode(
    Colors.black,
    BlendMode.srcIn,
  ),
)

You can also pass a .svg asset through imagePath:

CustomImageView(
  imagePath: 'assets/icons/logo.svg',
  height: 48,
  width: 48,
)

Local File

For mobile and desktop apps:

import 'dart:io';

CustomImageView(
  file: File('/path/to/image.png'),
  height: 100,
  width: 100,
)

XFile From Image Picker

CustomImageView(
  xFile: pickedFile,
  height: 100,
  width: 100,
  fit: BoxFit.cover,
)

Placeholder And Errors

CustomImageView(
  url: 'https://example.com/photo.png',
  placeHolder: (context, url) {
    return const Center(child: CircularProgressIndicator());
  },
  errorWidget: (context, url, error) {
    return const Icon(Icons.broken_image);
  },
)

SVG failures can use svgErrorBuilder. If it is not provided, errorBuilder is used as the SVG fallback.

CustomImageView(
  svgUrl: 'https://example.com/icon.svg',
  svgErrorBuilder: (context, error, stackTrace) {
    return const Icon(Icons.error_outline);
  },
)

Styling And Interaction

CustomImageView(
  url: 'https://example.com/photo.png',
  height: 96,
  width: 96,
  fit: BoxFit.cover,
  alignment: Alignment.center,
  margin: const EdgeInsets.all(8),
  radius: BorderRadius.circular(16),
  border: Border.all(color: Colors.black12),
  semanticsLabel: 'Profile photo',
  onTap: () {
    // Open preview, profile, gallery, etc.
  },
)

Hide decorative images from screen readers:

CustomImageView(
  imagePath: 'assets/pattern.png',
  excludeFromSemantics: true,
)

Example App

This package includes an example app with cached network images, cached network SVGs, asset SVGs, memory images, memory SVGs, progress UI, error UI, and cache eviction.

cd example
flutter run

Notes

  • Use url for raster network images.
  • Use svgUrl for explicit network SVGs.
  • .svg detection ignores query strings, so https://example.com/icon.svg?v=1 is treated as an SVG.
  • file is intended for mobile and desktop. For web image picking, prefer xFile.

Libraries

custom_image_view