NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev
Image & video picker with permissions, camera/gallery source sheet, cropping (incl. circle) on every platform, size/type validation, and no READ_MEDIA permission.
Latest stable
2.0.0
Last release 27 days ago
26 Oct 2026
Ships unpredictably
gaps range from 8 days to 9 months
Nearly every release is documented
notes for 17 of 17 stable releases
Nothing withdrawn
no release was ever pulled
1 years old
17 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
New pickers, an adaptive source sheet, validation, cropping on every platform, and WASM compatibility.
New pickers, an adaptive source sheet, validation, cropping on every platform, and WASM compatibility.
Breaking (small): PickError gains fileTooLarge and
unsupportedType, and MediaType gains any — exhaustive switch
statements over them need the new cases. Multi picks now return
PickError.canceled when nothing is picked, and wantToCrop now opens a
crop editor on desktop instead of returning the original image.
New features:
sourceSheet: SourceSheetOptions(...) to any pick
method to let users choose "Take photo" or "Choose from gallery" — a
Cupertino action sheet on iOS/macOS, a Material bottom sheet elsewhere.
An optional "Remove" option sets removeRequested on the result.
showSourceSheet() returns the choice on its own.pickMultiVideo(), pickMedia() (image or video) and
pickMultipleMedia() (images and videos together).PickOptions.cropShape: CropShape.circle, on every
platform.PickOptions.maxFileSizeBytes and
PickOptions.allowedMimeTypes (wildcards like image/*). Single picks
return PickError.fileTooLarge / PickError.unsupportedType; multi picks
keep valid items and list the others in PickResultMultiple.rejected.PickOptions.preferredCameraDevice (e.g. front
camera) and PickOptions.maxVideoDuration.PickedMedia: name, sizeInBytes, isImage, isVideo and
readAsBytes(), which also works on Web where path is a blob URL.PickOptions.labels (PickerLabels) covers the crop
editor, native cropper toolbar title and limited-access sheet.recoverLostData() recovers a pick lost when Android destroyed the
activity (e.g. while the camera was open).CameraDevice is re-exported, like ImageSource.Changes and fixes:
crop_your_image) with
aspect-ratio presets and lockCropAspectRatio support. Android and iOS
keep the native cropper. Previously, wantToCrop on desktop silently
returned the original image with PickError.cropCanceled.<script>/<link> tags in
web/index.html are no longer needed and can be removed.image_cropper is no longer imported on web; it
pulled dart:io into the web import graph.image_cropper constraint widened to >=12.2.1 <14.0.0 (13.x supported
without raising the minimum Flutter version).PlatformException from image_picker) are now
caught and returned as PickError.io instead of being thrown. They are
logged with PickOptions.logTag, which was previously unused.pickMultiImage no longer falls back to the limited-access grid when
image_picker throws (that grid needs Photos permission the package no
longer requests on Android, and isn't available on Windows/Linux); it
returns PickError.io. It now also forwards maxWidth/maxHeight, and
returns PickError.canceled when nothing is picked. A maxImages of 0 or
less is treated as "no limit" instead of throwing ArgumentError.PickedMedia.mimeType is now filled in (platform-reported, or derived
from the file extension), and width/height are set for picked images.imageQuality as its output quality (it was
always 100, so cropped files could be larger than uncropped ones) and
keeps PNGs as PNG.setState() called after dispose() when the
sheet closes while loading or after "Open Settings"; the selection badge
now uses the theme's primary color (or primaryColor); the Done button
shows the selection count; album loading errors no longer crash the sheet.example/tool/screenshots_test.dart), corrected the
platform matrix (limited-access UX is iOS-only; cropping is everywhere) and
documented the remaining public API. README images are no longer shipped
in the package archive.primaryColor / themeBrightness aren't set (it used to fall back to a
fixed blue, light-mode toolbar), and its toolbar icons are colored for
contrast with the toolbar itself, so they stay readable in dark mode.Your coding agent can read these notes before it upgrades. Set up the MCP server →
Google Play Photo and Video Permissions policy compliance.
Google Play Photo and Video Permissions policy compliance.
image_picker), which
grants per-item access without READ_MEDIA_IMAGES / READ_MEDIA_VIDEO /
READ_EXTERNAL_STORAGE. Requesting the permission anyway forced host apps
to declare it in their manifest — which Google Play now rejects for apps
with one-time or infrequent media use. Host apps can (and should) remove
those permissions from their AndroidManifest.xml.useAndroidPhotoPicker = true on image_picker's Android platform
implementation), falling back to the legacy GET_CONTENT picker on
devices without it. Note this flag is global to image_picker, so other
gallery picks in the host app made through image_picker will also use
the photo picker.CAMERA (and RECORD_AUDIO for video) as
before. iOS, web, and desktop behavior is unchanged.device_info_plus dependency (no longer needed); added
image_picker_android and image_picker_platform_interface.Fixed several try/catch blocks in adaptive_media_picker_impl.dart and image_cropper_impl.dart that returned a Future without await, which meant the ca
Bug fix.
try/catch blocks in adaptive_media_picker_impl.dart and
image_cropper_impl.dart that returned a Future without await, which
meant the catch couldn't actually catch errors thrown by that future —
they'd propagate as unhandled Future rejections instead.Configurable default crop aspect ratio.
Configurable default crop aspect ratio.
PickOptions.cropAspectRatio (CropAspectRatioOption?) to set the
ratio the cropper opens with (square, ratio3x2, ratio4x3, ratio5x4,
ratio7x5, ratio16x9, or original). Defaults to null, which preserves
the previous behavior (square initial ratio on Android, free-form on
iOS/Web).PickOptions.lockCropAspectRatio to lock the crop box to
cropAspectRatio on Android/iOS (no effect on Web — the image_cropper
web backend can't lock the ratio, only hint at an initial one).Removed photo_manager imports from web/WASM-reachable code (limited_access_picker_stub.dart and adaptive_media_picker_impl.dart). The stub's LimitedAc
WASM compatibility fix.
photo_manager imports from web/WASM-reachable code
(limited_access_picker_stub.dart and adaptive_media_picker_impl.dart).
The stub's LimitedAccessPicker.show now returns Future<List<dynamic>?>
instead of naming AssetEntity, which transitively pulled dart:io into
web builds and made pub.dev flag the package as not WASM-compatible. The
native (dart:io) implementation is unchanged and still returns
List<AssetEntity>.Raised minimum SDKs to Dart 3.10 / Flutter 3.38.1 — required by image_picker 1.2.3 and device_info_plus 13. The previous constraints (Dart 3.4 / Flutt
SDK constraint fix.
image_picker 1.2.3 and device_info_plus 13. The previous constraints
(Dart 3.4 / Flutter 3.13) could not actually resolve the 1.0.0
dependencies..fvmrc pin) so
dependency resolution succeeds on CIDeprecated PickOptions.showOpenSettingsDialog (no longer read)
First stable release: dependency upgrades, accurate permission states, and WASM compatibility.
smart_permission from ^0.0.3 to ^1.0.1image_cropper from ^11.0.0 to ^12.2.1device_info_plus from ^12.2.0 to ^13.2.0photo_manager from ^3.7.1 to ^3.12.0image_picker from ^1.2.1 to ^1.2.3compileSdk = 37 (required by
permission_handler 13 via smart_permission); see READMEsmart_permission's result API: limited access and
permanently-denied states are now reported accurately by the OS instead of
being inferred from the device's photo library contents. Full-access users
now get the native picker instead of the in-package limited-access sheet.PermissionResolution.permanentlyDenied is now populated correctlysmart_permission; the package no longer shows
its own duplicate settings dialog. PickOptions.settingsDialogTitle,
settingsDialogMessage, settingsButtonLabel, and cancelButtonLabel
are forwarded to those dialogs.PickOptions.showOpenSettingsDialog (no longer read)READ_MEDIA_VIDEO (previously
also prompted for images)PickError.permissionDenied; permission failures no longer surface
as PickError.unknownPickResultMultiple now exposes error (parity with PickResultSingle)PickError.cropCanceled (previously always null)dart.library.js_interop instead of
dart.library.html for WebAssembly (WASM) compatibilityPermission handling migration and dependency updates.
Permission handling migration and dependency updates.
permission_handler with smart_permission packagePermissionManager.ensureMediaPermission now requires BuildContext? parameterdevice_info_plus from ^12.1.0 to ^12.2.0image_picker from ^1.2.0 to ^1.2.1permission_handler: ^12.0.1 with smart_permission: ^0.0.3smart_permission API for better permission handling UXpost_install configuration for Camera, Microphone, and Photos permissionsDart formatting only (no functional changes).
Dart formatting only (no functional changes).
dart format with default settings across lib/, example/, and test/Web image cropper bug fixes and improvements.
Web image cropper bug fixes and improvements.
Theming support and example toggle.
Theming support and example toggle.
PickOptions.themeBrightness and PickOptions.primaryColor to control UI theme for the limited-access sheet and cropperPickOptionsAndroidUiSettings colors now derive from theme (toolbar, controls, dim layer, grid/frame)Non-breaking DX improvements: typed errors and richer result metadata.
Non-breaking DX improvements: typed errors and richer result metadata.
PickResultSingle now exposes metadata: PickMetadata with:
cropApplied, originalSize, and finalSize (when measurable)error: PickError? to disambiguate empty results:
canceled (user canceled), cropCanceled, io, unknownPickOptions.logTag (optional) for easier internal tracing in debug logsoriginalSize and finalSize for single-image picks (incl. cropped)PickError.canceled when selection dialogs return null/emptyPickError.cropCanceled when crop UI is dismissed without savingCropping feature finalized with platform guards, stubs, and docs updates:
Cropping feature finalized with platform guards, stubs, and docs updates:
PickOptions.wantToCrop)
UCropActivity is declared in app manifest (documented)image_cropper (cropperjs) with dialog style and fixed size; requires including CSS/JS in index.htmlPlatformImageCropper with conditional imports for mobile/web and a desktop stubImageCropper usage from the picker; unified call sitesNo functional or breaking changes
Analyzer and formatting cleanups; no API changes:
lib/adaptive_media_picker.dartdart format across the repository (lib and example) for pub.dev checksCleaned exports in adaptive_media_picker.dart (no breaking changes)
Docs and README polish; tests and formatting:
adaptive_media_picker.dart (no breaking changes)dart format on lib to satisfy pub.dev checksRefactor, clearer API, and docs/readiness improvements:
Refactor, clearer API, and docs/readiness improvements:
PickResultSingle { item, permissionResolution }PickResultMultiple { items, permissionResolution }pickImage (single image), pickVideo (single video), pickMultiImage (multi images)PickOptions simplified:
allowMultiple and mediaTypemaxImages now applies only to images and is enforced cross-platformsrc/core/ (models), src/platform/ (permission manager), src/ui/ (limited picker)dart:io from library codeAdaptive media picker with unified API across platforms (Android, iOS, Web, Desktop).
Initial release
permission_handler, including:
photo_manager.image_picker with desktop/web camera fallback to gallery.ImageSource for consumer convenience.One column per month.