📸 Adaptive Media Picker #

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

✨ Why Adaptive Media Picker? #

Most media pickers only open the gallery or camera — but fail when permissions are limited or restricted. adaptive_media_picker is designed to handle every case automatically, making your UX seamless.

💡 What makes it different? #

• ✅ Auto permission handling
• ✅ Built-in limited-access sheet (for iOS & Android)
• ✅ Optional image cropping (Android / iOS / Web)
• ✅ Works seamlessly on Web, Desktop, and Mobile
• ✅ Single unified API for images & videos

✨ Built-in limited access bottom sheet UI (native full-access flow on Android/iOS)

🚀 Features at a Glance #

⚠️ 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 and crop
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),
);

🎨 Theming #

Both the built-in limited-access bottom sheet and the optional cropper can follow your app theme or be overridden via PickOptions:

• Automatic: By default, the package uses Theme.of(context) for surfaces and text.
• Override: Set these optional fields on PickOptions:
  • themeBrightness: Brightness.light or Brightness.dark
  • primaryColor: the primary accent color (e.g. Colors.blue)

Example:

final result = await picker.pickImage(
context: context,
options: const PickOptions(
wantToCrop: true,
themeBrightness: Brightness.dark,
primaryColor: Colors.blue,
),
);

Notes:

• Limited-access bottom sheet inherits your app theme when overrides are not provided.
• Android cropper toolbar, controls, and grid/frame colors derive from themeBrightness and primaryColor.
• Web cropper uses the provided context (dialog/page) and will follow your theme colors; primary accent applies to available UI elements.

📌 Common Use Cases #

• 🖼️ Select & crop a profile picture
• 📸 Capture or choose multiple images for a gallery/post
• 🎥 Pick single video from camera or gallery
• 🔐 Handle limited access permissions gracefully

✂️ Cropping Setup #

Cropping is supported on Android, iOS, and Web.

📱 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

ℹ️ If you enable cropping and build a release APK/AAB (R8/minify), UCrop may reference OkHttp classes. Add these dependencies to your app’s build.gradle(.kts) to avoid missing-class errors (only needed when cropping on Android):

dependencies {
  implementation("com.squareup.okhttp3:okhttp:4.12.0")
  implementation("com.squareup.okio:okio:3.6.0")
}

🍏 iOS #

No additional setup required.

🌐 Web #

Add cropperjs to 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, the picker automatically shows a native-like dialog with options:

• 📁 Manage Selection (iOS only)
• ⚙️ Open Settings (iOS/macOS/Android)
• 🕓 Auto-dismisses after interaction

⚙️ Permissions Setup #

🧱 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>

To ensure your app works smoothly with media picking and cropping on iOS, you'll need to configure the required permissions in your Podfile for Flutter.

Add the following code to the post_install section of your Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)

    target.build_configurations.each do |config|
      # Enable only the permissions you need in your app
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        'PERMISSION_CAMERA=1',
        'PERMISSION_MICROPHONE=1',
        'PERMISSION_PHOTOS=1',
        # Examples of other permissions you might enable:
        # 'PERMISSION_NOTIFICATIONS=1',
        # 'PERMISSION_MEDIA_LIBRARY=1',
        # 'PERMISSION_BLUETOOTH=1',
        # 'PERMISSION_APP_TRACKING_TRANSPARENCY=1',
      ]
    end
  end
end

This will make sure the necessary permissions for Camera, Microphone, and Photos are enabled in your iOS project, allowing the picker to function properly.

💻 macOS #

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

🧩 Desktop platforms use native file dialogs. Camera capture is not supported on desktop.

🧩 API Overview #

📘 Data Models Overview #

🧩 PickOptions #

Configuration options for image/video picking operations.

🖼️ PickedMedia #

Represents a single picked image or video.

🧾 PickResultSingle #

Returned from pickImage() or pickVideo().

💡 Use .isEmpty to check if no item was selected.

🧾 PickResultMultiple #

Returned from pickMultiImage().

💡 Use .isEmpty to check if no images were selected.

🧠 PickMetadata #

Extra info for debugging and analytics.

⚠️ PickError #

Typed error codes for single-pick operations.

🔐 PermissionResolution #

Represents the final permission outcome.

Factories

👤 Author #

Created with ❤️ by Jaimin Kavathia - 💼 LinkedIn

📜 License #

Licensed under the MIT License. Free for personal & commercial use.

⭐ If you like this package, give it a star on GitHub & pub.flutter-io.cn!