📸 Gallery Media Picker - Flutter Package #

A powerful and customizable Flutter package for selecting images and videos from the device gallery with an Instagram style interface and fast thumbnail rendering. Built on top of photo_manager, this package delivers smooth performance, flexible UI customization, and a clean user experience.

This work is an improved fork of the original gallery_media_picker. Built on top of photo_manager. The Plus version adds bug fixes, quality improvements, usability enhancements, and more flexible control.

💫 Support the Project #

If you find this package helpful, please consider giving it a ⭐ on GitHub and liking it on pub.dev!

Your support helps improve and maintain this project! ❤️

✨ Features #

• 📷 Pick single or multiple images / videos / GIF
• 🖼️ Scrollable grid with infinite loading
• 🔎 Album selector (dropdown style)
• 🎛️ Highly customizable UI
• ✅ Built for Android & iOS
• 🔍 Support for GIF and video duration tags

🚀 Getting Started #

1. Install #

dependencies:
  gallery_media_picker_plus: ^<latest_version>

2. Permissions Setup #

Although photo_manager handles media access and platform integration, it is strongly recommended to use permission_handler to request permissions explicitly. This ensures better user experience, avoids permission-related issues, and complies with app store policies.

Android

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>

On older Android versions (API < 33), you may need:

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

iOS

In your Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to select media.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow to access to your gallery</string>

Recommended Permission Request (with permission_handler)

import 'package:permission_handler/permission_handler.dart';

Future<void> requestPermissions() async {
  final status = await Permission.photos.request();
  if (!status.isGranted) {
    // Optionally show a dialog or redirect to app settings
  }
}

⚠️ Call this function before using GalleryMediaPicker.

3. Basic Usage #

GalleryMediaPicker(
  pathList: (List<PickedAssetModel> paths) {
    // Handle selected media
  },
  appBarLeadingWidget: Icon(Icons.close),
  mediaPickerParams: MediaPickerParamsModel(
    appBarHeight: 50,
    maxPickImages: 2,
    crossAxisCount: 3,
    childAspectRatio: .5,
    singlePick: false,
    appBarColor: Colors.black,
    gridViewBgColor: Colors.red,
    albumTextColor: Colors.white,
    gridPadding: EdgeInsets.zero,
    thumbnailBgColor: Colors.cyan,
    thumbnailBoxFix: BoxFit.cover,
    selectedAlbumIcon: Icons.check,
    selectedCheckColor: Colors.black,
    albumSelectIconColor: Colors.blue,
    selectedCheckBgColor: Colors.blue,
    selectedAlbumBgColor: Colors.black,
    albumDropDownBgColor: Colors.green,
    albumSelectTextColor: Colors.orange,
    selectedAssetBgColor: Colors.orange,
    selectedAlbumTextColor: Colors.white,
    mediaType: GalleryMediaType.all,
    gridViewController: ScrollController(),
    thumbnailQuality: ThumbnailQuality.medium,
    gridViewPhysics: const BouncingScrollPhysics(),
  ),
),

🧩 MediaPickerParamsModel – Full Parameter Guide #

pathList Callback #

This callback is triggered whenever the user selects or deselects media items.

It returns a list of PickedAssetModel objects representing the currently selected files (images, GIF or videos), which you can store, preview, or process as needed.

appBarLeadingWidget #

Optional widget to be displayed at the leading position of the album selector (top row). Use this to insert a custom control like a back button, close icon, or any widget you'd like to show at the start of the toolbar.

mediaPickerParams #

Each parameter lets you fine-tune the look and feel of the media picker.

🧠 Enum: ThumbnailQuality #

📹 Screenshots / Demo #

Personalization #

Dark Setting

Light Setting

Custom Setting

No leading widget

Album Selection #

Pick single file #

Pick multiple files #

Select media type #

Only videos

Only images and GIF

Quality comparison #

Low

Medium

High

💬 Contributing #

Contributions are welcome. If you find bugs or have feature suggestions, feel free to open an issue or submit a pull request in this repository.

📄 License #

MIT License — see the LICENSE file for details.