MultiImage Flutter Package #

A Flutter widget for displaying multiple images with a responsive layout and an interactive full-screen gallery. This package simplifies the process of showcasing images in various configurations, handling loading states, errors, and user interactions seamlessly.

Screenshots

Features #

• Dynamic Image Layouts: Automatically adjusts the layout based on the number of images:
  • 1 image: Full-width display.
  • 2 images: Side-by-side display.
  • 3 images: One full-width image on top, two side-by-side below.
  • 4+ images: One full-width image on top, two side-by-side below, with an overlay indicating additional images.
• Full-Screen Gallery: Tap any image to open a full-screen gallery with swipe navigation.
• Loading Animation: Displays a shimmer effect while images are loading.
• Error Handling: Shows a customizable fallback widget if an image fails to load.
• Customizable Styling:
  • Border radius for images.
  • Custom gap spacing between images.
  • Configurable colors and icons for the gallery and fallback widget.
  • Custom text style and color for the "more images" indicator.
• Responsive Design: Adapts to different screen sizes with a maximum height constraint.
• Interactive Navigation: Includes a back button and dot indicators in the gallery view.

Installation #

Add the following to your pubspec.yaml:

dependencies:
  multi_image: ^1.0.0

Run flutter pub get to install the package.

Usage #

1. Import the Package:

   import 'package:multi_image/multi_image.dart';
   

2. Add the MultiImage Widget: Use the MultiImage widget in your Flutter app to display a list of image URLs. Provide the required parameters and customize optional ones as needed.

   MultiImage(
     context: context,
     imageUrls: [
       'https://example.com/image1.jpg',
       'https://example.com/image2.jpg',
       'https://example.com/image3.jpg',
     ],
     maxHeight: 400,
     radius: 16,
     gapSpacing: 6,
     openGalleryBackground: Colors.black87,
     fallbackColor: Colors.grey[300],
     moreIndicatorTextStyle: TextStyle(
       color: Colors.white,
       fontSize: 24,
       fontWeight: FontWeight.bold,
     ),
     moreIndicatorColor: Colors.black54,
     dotColor: Colors.white,
   )
   

3. Required Dependencies: Ensure you have the following dependencies in your pubspec.yaml for the widget to work correctly:

   dependencies:
     shimmer: ^3.0.0
   

Parameters #

How It Works #

1. Image Layout:

   • The widget determines the number of images in imageUrls and arranges them accordingly.
   • For 0 images, it returns an empty SizedBox.
   • For 1 image, it displays a single full-width image.
   • For 2 images, it shows them side-by-side.
   • For 3 images, it places one image on top and two below.
   • For 4 or more images, it displays one image on top, two below, and an overlay with a "+N" indicator for additional images.

2. Image Loading:

   • While an image is loading, a shimmer effect (using the shimmer package) is displayed as a placeholder.
   • If an image fails to load, the FallBackImage widget is shown, which can be customized with fallbackImage or fallbackColor.

3. Gallery Interaction:

   • Tapping an image opens the OpenGalleryScreen, a full-screen gallery where users can swipe through images.
   • The gallery includes a back button (customizable via openGalleryBackButtonIcon) and dot indicators (customizable via dotColor).
   • The gallery background color can be set with openGalleryBackground.

4. Customization:

   • Adjust the border radius of images with radius.
   • Control the spacing between images with gapSpacing.
   • Customize the appearance of the "+N" indicator for 4+ images using moreIndicatorColor and moreIndicatorTextStyle.

Example #

import 'package:flutter/material.dart';
import 'package:multi_image/multi_image.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('MultiImage Example')),
        body: Padding(
          padding: const EdgeInsets.all(8.0),
          child: MultiImage(
            context: context,
            imageUrls: [
              'https://example.com/image1.jpg',
              'https://example.com/image2.jpg',
              'https://example.com/image3.jpg',
              'https://example.com/image4.jpg',
            ],
            maxHeight: 400,
            radius: 10,
            gapSpacing: 5,
            openGalleryBackground: Colors.black87,
            fallbackColor: Colors.grey[200],
            moreIndicatorTextStyle: TextStyle(
              color: Colors.white,
              fontSize: 22,
              fontWeight: FontWeight.bold,
            ),
          ),
        ),
      ),
    );
  }
}

Notes #

• Ensure a stable internet connection for loading images from URLs.
• The shimmer package is required for the loading animation.
• The OpenGalleryScreen and FallBackImage widgets are part of the package and handle the gallery and fallback logic, respectively.
• For custom fallback images, provide a Widget to fallbackImage (e.g., an Image or Icon).

License #

This package is licensed under the MIT License. See the LICENSE file for details.