CustomImage

A highly customizable image widget with support for both network and local assets, featuring advanced styling and interaction options.

Features

  • Dual Image Source Support:
    • Network images (with caching)
    • Local asset images
  • Visual Customization:
    • Adjustable dimensions
    • Custom borders and radius
    • Box shadows
    • Color filters and blending
    • Multiple fit modes
  • Loading & Error States:
    • Custom placeholders
    • Error widgets
    • Smooth fade-in animations
  • Interaction:
    • Tap/double-tap/long-press handlers
    • Overlay widgets
  • Performance:
    • Cached network images
    • Quality controls
    • Gapless playback

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  apptomate_custom_image: ^0.0.3

Basic Usage

// Network image
CustomImage(
  imageUrl: 'https://example.com/image.jpg',
  height: 200,
  width: 200,
  isNetworkImage: true,
)

// Asset image
CustomImage(
  imageUrl: 'assets/images/local.png',
  height: 150,
  width: 150,
  isNetworkImage: false,
)

Complete Examples

1. Profile Image with Interaction

CustomImage(
  imageUrl: 'https://example.com/profile.jpg',
  height: 120,
  width: 120,
  borderRadius: 60,
  fit: BoxFit.cover,
  placeholder: CircularProgressIndicator(),
  onTap: () => print('Image tapped'),
  boxShadow: [
    BoxShadow(color: Colors.black26, blurRadius: 10),
  ],
)

2. Card Image with Overlay

CustomImage(
  imageUrl: 'assets/images/card_bg.png',
  height: 180,
  width: double.infinity,
  overlayWidget: Container(
    color: Colors.black.withOpacity(0.4),
    child: Center(
      child: Text('Featured', 
        style: TextStyle(color: Colors.white, fontSize: 24)),
  ),
)

3. Advanced Network Image

CustomImage(
  imageUrl: 'https://example.com/large-image.jpg',
  height: 300,
  width: 300,
  colorFilter: ColorFilter.mode(
    Colors.blue.withOpacity(0.2),
    BlendMode.darken),
  fadeInDuration: Duration(seconds: 1),
  filterQuality: FilterQuality.high,
  errorWidget: Column(
    mainAxisAlignment: MainAxisAlignment.center,
    children: [
      Icon(Icons.wifi_off, size: 40),
      Text('Image unavailable'),
    ],
  ),
)

Parameter Reference

Core Properties

Parameter Type Required Description
imageUrl String Yes Image URL/path
height double Yes Image height
width double Yes Image width

Display Options

Parameter Type Default Description
isNetworkImage bool true Whether image is from network
fit BoxFit cover How to inscribe the image
borderRadius double 8.0 Corner radius
border BoxBorder? null Border styling
alignment Alignment center Image alignment
repeat ImageRepeat noRepeat Image repetition
filterQuality FilterQuality medium Rendering quality

Style Options

Parameter Type Description
boxShadow List<BoxShadow>? Shadow effects
color Color? Image tint color
colorBlendMode BlendMode? Blend mode for color
colorFilter ColorFilter? Color filter to apply

Animation & Loading

Parameter Type Default Description
fadeInDuration Duration 300ms Fade-in duration
fadeInCurve Curve easeIn Fade-in curve
placeholder Widget? null Loading widget
errorWidget Widget? null Error display widget
gaplessPlayback bool false Keep old image when changing

Interaction

Parameter Type Description
onTap VoidCallback? Tap handler
onDoubleTap VoidCallback? Double-tap handler
onLongPress VoidCallback? Long-press handler
overlayWidget Widget? Widget to overlay on image

Best Practices

  1. Performance:

    • Use appropriate image sizes
    • Set filterQuality based on need
    • Utilize caching for network images

  2. Error Handling:

    • Always provide error widgets
    • Consider placeholder skeletons

  3. Accessibility:

    • Add semantic labels for interactive images
    • Ensure sufficient contrast for overlays

  4. Consistency:

    • Standardize border radii across app
    • Maintain consistent shadow styles

Libraries

apptomate_custom_image