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

💻 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.dev!