gallery_media_picker 0.2.0

A fully customizable and modern Flutter media picker inspired by Instagram. Supports image/video selection, multi-pick, album browsing, and high-performance grid previews using the photo_manager library.

📸 Gallery Media Picker - Flutter Package

A powerful and customizable Flutter package that allows users to select multiple media files (images or videos) directly from the device's gallery, featuring an Instagram-style interface and performance-optimized thumbnail rendering.

Built on top of photo_manager, gallery_media_picker is ideal for apps requiring fast media access, beautiful UX, and fine-grained configuration.

Claro, aquí tienes un mensaje corto y amigable que puedes usar para invitar a las personas a apoyar el proyecto en GitHub y pub.dev, junto con los badges correspondientes:

---

💫 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: ^<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
    media.setPickedFiles(paths);
  },
  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
mediaType	Type of media to display (all/images/videos)	GalleryMediaType	GalleryMediaType.all

🧠 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

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

Pull requests are welcome! If you find bugs or have suggestions, feel free to open an issue.

---

📄 License

MIT License — see the LICENSE file for details.

---