📸 Adaptive Media Picker #

🚀 Adaptive, permission-aware media picker for Flutter
Handles limited & full access gracefully, with native-like UX across Android, iOS, Web, and Desktop.

✨ Why Adaptive Media Picker? #

Most media pickers only open the gallery or camera — but don’t handle modern permission flows like limited access on iOS/Android.

This package makes it super easy for developers by:

✅ Automatically handling permissions
✅ Providing a built-in limited-access sheet
✅ Optional image cropping (Android/iOS/Web)
✅ Falling back smartly for unsupported platforms (desktop/web)
✅ Offering one simple API for images & videos

[Pick image] [Pick multiple images] [Pick video]

Built-in Limited Access UI (system-native UI used for full access)

🚀 Features #

• 📷 Pick single image, multiple images, or single video
• ✂️ Crop support for single images (Android, iOS, Web)
• 🔐 Permission-aware (handles full, limited, denied states)
• 🖼️ Built-in limited-access bottom sheet
• 🌍 Works on mobile, web, and desktop
• 🎯 No dart:io → safe for web builds
• 🎥 Fallback to gallery when camera unavailable (e.g., web/desktop)

⚠️ Note: Multiple video selection is not supported by native APIs.

🗂️ Platform Support Matrix #

⚡ Quick Start #

final picker = AdaptiveMediaPicker();

// Pick a single image
final singleImage = await picker.pickImage(
  context: context,
  options: const PickOptions(
    source: ImageSource.gallery,
    imageQuality: 80,
  ),
);

// Pick a single image with cropping (Android/iOS/Web)
final croppedImage = await picker.pickImage(
  context: context,
  options: const PickOptions(
    source: ImageSource.gallery,
    wantToCrop: true,
  ),
);

// Pick multiple images
final multiImages = await picker.pickMultiImage(
  context: context,
  options: const PickOptions(maxImages: 5, source: ImageSource.gallery),
);

// Pick a single video
final singleVideo = await picker.pickVideo(
  context: context,
  options: const PickOptions(source: ImageSource.gallery),
);

📌 Common Use Cases #

✅ Pick profile picture (with optional crop) ✅ Select multiple images for an album/post ✅ Pick a single video from gallery/camera ✅ Handle limited-access gracefully with a built-in bottom sheet

✂️ Cropping Setup #

Cropping works for Android, iOS, and Web only. On desktop platforms cropping is ignored and the original image is returned.

Android #

Add UCropActivity to your AndroidManifest.xml:

<activity
  android:name="com.yalantis.ucrop.UCropActivity"
  android:screenOrientation="portrait"
  android:theme="@style/Theme.AppCompat.Light.NoActionBar"/>

(Android embedding v2 required)

iOS #

No additional configuration needed.

Web #

Add cropperjs to your web/index.html:

<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.css"
/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.2/cropper.min.js"></script>

🔐 Limited Access UX #

When the user grants limited access:

• A dialog is shown with:

  • Manage Selection (iOS only)
  • Open Settings (iOS/macOS/Android)

• If the user interacts, the sheet closes automatically

⚙️ Platform Setup (Permissions) #

Android #

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

iOS #

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access to pick images.</string>
<key>NSCameraUsageDescription</key>
<string>This app needs camera access to take photos and videos.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access when recording videos.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app may save images/videos to your photo library.</string>

macOS #

<key>com.apple.security.files.user-selected.read-only</key>
<true/>

Desktop (Windows, macOS, Linux) → uses native file dialogs. Camera not supported.

🧩 API Overview #

Options #

• maxImages → Limit for multi-image picking
• imageQuality, maxWidth, maxHeight → Resize/compression options
• source → ImageSource.gallery | ImageSource.camera
• wantToCrop → Enable cropping (Android/iOS/Web, single-image only)
• Dialog / settings options → showOpenSettingsDialog, settingsDialogTitle, settingsDialogMessage

Results #

• PickResultSingle { item, permissionResolution }
• PickResultMultiple { items, permissionResolution }

Methods #

• pickImage → Single image (with optional crop)
• pickMultiImage → Multiple images
• pickVideo → Single video

👤 Author #

Created with ❤️ by Jaimin Kavathia Connect on LinkedIn

📜 License #

Licensed under the MIT License → Open Source, Free to Use

⭐ If you like this package, give it a star on GitHub & pub.dev!