skills/flutter/references/widgets-images.md

name	description
widgets-images	Flutter Image widget, AssetImage, NetworkImage, ImageProvider, and image loading

Image Widgets

Flutter provides widgets for displaying images from various sources.

Image Widget

Display images from different sources.

// Asset image
Image.asset(
  'assets/images/logo.png',
  width: 100,
  height: 100,
  fit: BoxFit.cover,
)

// Network image
Image.network(
  'https://example.com/image.jpg',
  width: 200,
  height: 200,
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;
    return CircularProgressIndicator(
      value: loadingProgress.expectedTotalBytes != null
          ? loadingProgress.cumulativeBytesLoaded / loadingProgress.expectedTotalBytes!
          : null,
    );
  },
  errorBuilder: (context, error, stackTrace) {
    return Icon(Icons.error);
  },
)

// File image
Image.file(
  File('/path/to/image.jpg'),
  width: 100,
  height: 100,
)

// Memory image
Image.memory(
  Uint8List.fromList(imageBytes),
  width: 100,
  height: 100,
)

Image Properties

Image.asset(
  'assets/images/logo.png',
  width: 200,
  height: 200,
  fit: BoxFit.cover, // cover, contain, fill, fitWidth, fitHeight, none, scaleDown
  alignment: Alignment.center,
  repeat: ImageRepeat.noRepeat, // noRepeat, repeat, repeatX, repeatY
  matchTextDirection: false,
  gaplessPlayback: false, // Keep showing old image while loading new one
  filterQuality: FilterQuality.low, // low, medium, high, none
  isAntiAlias: true,
  frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
    if (wasSynchronouslyLoaded) return child;
    return AnimatedOpacity(
      opacity: frame == null ? 0 : 1,
      duration: const Duration(milliseconds: 200),
      child: child,
    );
  },
)

ImageProvider

Use ImageProvider for advanced image loading.

AssetImage

Image(
  image: AssetImage('assets/images/logo.png'),
  width: 100,
  height: 100,
)

// With package
AssetImage('assets/logo.png', package: 'my_package')

NetworkImage

Image(
  image: NetworkImage('https://example.com/image.jpg'),
  width: 100,
  height: 100,
)

// With headers
NetworkImage(
  'https://example.com/image.jpg',
  headers: {'Authorization': 'Bearer token'},
)

FileImage

Image(
  image: FileImage(File('/path/to/image.jpg')),
  width: 100,
  height: 100,
)

MemoryImage

Image(
  image: MemoryImage(Uint8List.fromList(imageBytes)),
  width: 100,
  height: 100,
)

FadeInImage

Image with fade-in animation.

FadeInImage.assetNetwork(
  placeholder: 'assets/placeholder.png',
  image: 'https://example.com/image.jpg',
  width: 200,
  height: 200,
  fadeInDuration: const Duration(milliseconds: 300),
  fadeOutDuration: const Duration(milliseconds: 100),
)

FadeInImage.memoryNetwork(
  placeholder: kTransparentImage, // From transparent_image package
  image: 'https://example.com/image.jpg',
)

Image Caching

Precache images for better performance.

// Precache asset image
precacheImage(
  AssetImage('assets/images/logo.png'),
  context,
);

// Precache network image
precacheImage(
  NetworkImage('https://example.com/image.jpg'),
  context,
).then((_) {
  // Image is cached
});

// Check cache status
final status = await imageProvider.obtainCacheStatus(
  configuration: createLocalImageConfiguration(context),
);
print('Cache status: ${status.status}'); // pending, live, keepAlive

Image Error Handling

Image.network(
  'https://example.com/image.jpg',
  errorBuilder: (context, error, stackTrace) {
    return Container(
      width: 100,
      height: 100,
      color: Colors.grey[300],
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Icon(Icons.error, color: Colors.red),
          Text('Failed to load', style: TextStyle(fontSize: 10)),
        ],
      ),
    );
  },
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;
    return Center(
      child: CircularProgressIndicator(
        value: loadingProgress.expectedTotalBytes != null
            ? loadingProgress.cumulativeBytesLoaded / loadingProgress.expectedTotalBytes!
            : null,
      ),
    );
  },
)

ImageIcon

Use images as icons.

ImageIcon(
  AssetImage('assets/icons/custom_icon.png'),
  size: 48,
  color: Colors.blue,
)

ImageIcon(
  NetworkImage('https://example.com/icon.png'),
  size: 48,
)

Key Points

• Use Image.asset() for local assets
• Use Image.network() for network images
• Use Image.file() for file system images
• Use Image.memory() for in-memory images
• Use FadeInImage for smooth loading transitions
• Precache images for better performance
• Always provide error builders for network images
• Use BoxFit to control how images fill their bounds
• Configure image cache size in ImageCache if needed