📸 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.

Parameter	Description	Type	Default
appBarHeight	Height of the top AppBar	double	50.0
appBarColor	Background color of the AppBar	Color	Colors.black
albumTextColor	Text color of the selected album	Color	Colors.white
albumDropDownBgColor	Background color of album dropdown	Color	Colors.green
albumSelectIconColor	Icon color in dropdown	Color	Colors.blue
albumSelectTextColor	Text color in dropdown list	Color	Colors.orange
selectedAlbumTextColor	Color of selected album title	Color	Colors.white
selectedAlbumIcon	Icon shown when album is selected	IconData	Icons.check
selectedAlbumBgColor	Background of selected album	Color	Colors.black
selectedAssetBgColor	Background color for selected media	Color	Colors.orange
selectedCheckColor	Checkmark color for selected assets	Color	Colors.black
selectedCheckBgColor	Checkmark background circle color	Color	Colors.blue
gridViewBgColor	GridView background color	Color	Colors.red
gridPadding	Grid padding	EdgeInsets	EdgeInsets.zero
crossAxisCount	Number of columns	int	3
childAspectRatio	Ratio of width to height	double	.5
thumbnailBoxFix	Fit mode for thumbnails	BoxFit	BoxFit.cover
thumbnailBgColor	Thumbnail container color	Color	Colors.cyan
thumbnailQuality	Enum for quality: low, medium, high	ThumbnailQuality	ThumbnailQuality.medium
gridViewController	ScrollController for the GridView	ScrollController	ScrollController()
gridViewPhysics	Scroll behavior	ScrollPhysics	BouncingScrollPhysics()
maxPickImages	Max number of assets to select	int	5
singlePick	Whether only one image can be picked	bool	false
fetchThumbnail	Whether thumbnails should be fetched	bool	true
mediaType	Type of media to display (all/images/videos)	GalleryMediaType	GalleryMediaType.all
loadingIndicatorWidget	Custom widget to show while media is loading	Widget	CircularProgressIndicator()
emptyAssetText	Widget displayed when an album has no media	Widget	Text('No media found')

🧠 Enum: ThumbnailQuality

Value	Description	Pixel size
low	Fastest loading, lowest detail	100x100
medium	Good balance	200x200
high	Best quality, slower load	350x350

---

📹 Screenshots / Demo

Personalization

Album Selection

Pick single file

Pick multiple files

Select media type

Quality comparison

---

💬 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.

---