file_picker

What's Changed

• Running dart format . in the repository by @vicajilau in #1982
• feat: migrate iOS and macOS to shared Darwin sources by @vicajilau in #1983
• fix(darwin): avoid false FlutterMacOS SourceKit errors by @vicajilau in #1984
• fix(android): normalize duplicate saveFile names to preserve extension by @vicajilau in #1985
• fix(android): normalize duplicate save names and avoid nested collision suffixes by @vicajilau in #1986
• Fix web default for pickFiles withData by @vicajilau in #1988
• fix(android): update gradle wrapper to 8.7 to fix AGP 8.5.1 minimum requirement error by @vicajilau in #1991
• Implement Storage Access Framework (SAF) with persistable URI grants by @vicajilau in #1989
• chore(windows): migrate win32 to 6.0.1 by @vicajilau in #1981
• chore: update version to 12.0.0-beta.1 in pubspec.yaml by @vicajilau in #1999
• chore: update changelog to reflect beta version 12.0.0-beta.1 by @vicajilau in #2000
• fix(android): handle OutOfMemoryError gracefully on large withData selections (#1997) by @vicajilau in #2001
• fix: improve image selection logic and update build dependencies by @daniJimen in #2004
• Update dependency versions for 12.0.0-beta.2 by @vicajilau in #2006
• fix(android): support AGP 9+ and android.builtInKotlin property for plugin registration (#2002) by @daniJimen in #2010
• Update version to 12.0.0-beta.3 and fix Android plugin registration by @vicajilau in #2011
• fix(android): update error code to explorer_not_found when file explorer is missing (#1850) by @daniJimen in #2008
• feat: add support for custom dialog titles in pickFileAndDirectoryPaths (#1911) by @daniJimen in #2009
• Feature/fix add loading into save (#1918) by @daniJimen in #2007
• fix(android): fix FileType.any subdirectory visibility by @vicajilau in #2016
• feat: implement pickFile() API and improve PlatformFile documentation (#1469) by @vicajilau in #2017
• fix(darwin): add missing FlutterFramework dependency to Package.swift by @vicajilau in #2025
• fix(android): remove explicit KGP dependency to resolve warnings under AGP 9.0+ by @vicajilau in #2026
• Feature/migrate goovy to kts by @daniJimen in #2028
• feat: summarize file bytes in debug output by @vicajilau in #2029
• Fix saveFile bytes handling on Android and iOS by @vicajilau in #2038
• Fix iOS picker stuck state on fast swipe dismiss by @vicajilau in #2040
• [All platforms][IOS] - feature: Refactor code in example & ios image order by @daniJimen in #2047
• [IOS] feature: IOS prevent freece UI by @daniJimen in #2048
• Fix web readAsBytes fallback for blob URLs by @vicajilau in #2042
• [Android] - Feature: add coroutine to save file process by @daniJimen in #2045
• Export 'src/platform/file_picker_platform_interface.dart' by @zmuranaka in #2064
• Fix readAsBytes fallback for path-based files by @vicajilau in #2057
• Use hardcoded hex values for request codes in FilePickerDelegate by @daniJimen in #2071
• Update ffi, win32, and flutter_lints dependencies by @daniJimen in #2072
•  [WEB] - Fix PlatformFile.xFile getter on web when bytes are null by @daniJimen in #2075
• fix(android): decode images with inSampleSize in compressImage by @marceloleda in #2083
• feat(windows): add parentWindowHandle parameter to override window handle lookup by @aexei in #2079
• Export IllegalCharacterInFileNameException Fixes #2076 by @hasanmhallak in #2077
• fix(macos): pass dialogTitle in getDirectoryPath (#2087) by @vicajilau in #2088
• File picker platform interface setup by @navaronbracke in #2094
• feat(android): extract file_picker_android package by @vicajilau in #2098
• feat(darwin): extract file_picker_darwin package for iOS and macOS by @vicajilau in #2099
• feat(linux): extract Linux implementation into file_picker_linux package by @vicajilau in #2100
• feat(windows): extract Windows implementation into file_picker_windows package by @vicajilau in #2102
• feat(web): extract file_picker_web package by @vicajilau in #2103
• fix(file_picker_android): remove Apache Tika dependency for MIME type detection by @ryanaidilp in #2105
• fix(android): remove Apache Tika dependency for MIME type detection by @ryanaidilp in #2104
• docs: attribute Tika removal to the 11.0.3 hotfix by @ryanaidilp in #2106
• refactor: remove obsolete root platform code and legacy sources (Step 1/3) by @vicajilau in #2108
• fix: platform implementation fixes for Android, Darwin SPM, Linux, and Windows (Step 2/3) by @vicajilau in #2109
• refactor: update root file_picker package and example app for federated architecture by @vicajilau in #2110
• docs: complete Dartdoc parameter documentation and align API delegation by @vicajilau in #2111
• Refactor federated plugin by @vicajilau in #2112
• chore: add workspace topics, per-package licenses, unified publish workflow, and dependabot config by @vicajilau in #2113
• chore(deps): bump the actions group with 3 updates by @dependabot[bot] in #2114
• chore(deps): bump dorny/paths-filter from 3 to 4 in the actions group by @dependabot[bot] in #2118
• feat: support accept_label for linux by @Decodetalkers in #2120
• chore(example): tidy analysis_options.yaml excludes by @vicajilau in #2122
• refactor: rename file_picker_android to android_file_picker by @vicajilau in #2121
• chore: bump version to 12.0.0 and update CHANGELOG for release by @vicajilau in #2123
• Refactor package name to windows_file_picker by @vicajilau in #2124

New Contributors

• @zmuranaka made their first contribution in #2064
• @marceloleda made their first contribution in #2083
• @aexei made their first contribution in #2079
• @hasanmhallak made their first contribution in #2077
• @ryanaidilp made their first contribution in #2105
• @dependabot[bot] made their first contribution in #2114

Full Changelog: v11.0.2...v12.0.0

Breaking Changes

• Minimum Requirements: Raised minimum supported versions to Flutter 3.38 / Dart 3.10.
• iOS Target: Raised minimum supported iOS deployment target to 14.0. Removed DKImagePickerController / DKPhotoGallery dependency chain.
• API Modifications:
  • saveFile(): fileName and bytes are now required parameters across all platforms.
  • pickFiles(): allowMultiple now defaults to true. Use pickFile() for single file selection (allowMultiple is deprecated).
  • Deprecated withData, withReadStream, and readSequential on pickFiles()/pickFile() in favor of PlatformFile.readAsBytes() and PlatformFile.readAsByteStream().
  • Deprecated top-level lockParentWindow and cancelUploadOnWindowBlur parameters in favor of platform-specific option classes (WindowsOptions, LinuxOptions, WebOptions).

Architecture

• Federated Plugin: Refactored file_picker into a federated architecture with dedicated platform implementation packages (file_picker_platform_interface, android_file_picker, file_picker_darwin, file_picker_linux, windows_file_picker, and file_picker_web).

Features & Enhancements

• New API: Added pickFile() static method as a convenience wrapper for single file selection.
• Platform Options: Introduced WindowsOptions, LinuxOptions (with acceptLabel and parentWindow), and WebOptions.
• Android: Added support for Storage Access Framework (SAF) Persistable URI Grants (AndroidSAFOptions, AndroidSAFHandle, AndroidPlatformFile). Optimized image compression to prevent OutOfMemoryError.
• iOS & macOS: Unified native implementations into shared Darwin sources. Selection order is now preserved when picking multiple files on iOS.
• Exception Handling: Exported IllegalCharacterInFileNameException in file_picker.dart.

Merge pull request #2075 from daniJimen/feature/fix_web_issue_with_xfile

 [WEB] - Fix `PlatformFile.xFile` getter on web when bytes are null

Web

• Ensures XFile.fromData is only used on the web if bytes is not null, preventing potential null check errors.

What's Changed

• Export 'src/platform/file_picker_platform_interface.dart' by @zmuranaka in #2064
• Fix readAsBytes fallback for path-based files by @vicajilau in #2057
• Use hardcoded hex values for request codes in FilePickerDelegate by @daniJimen in #2071
• Update ffi, win32, and flutter_lints dependencies by @daniJimen in #2072

New Contributors

• @zmuranaka made their first contribution in #2064

Full Changelog: v12.0.0-beta.5...v12.0.0-beta.6

General

• Improved PlatformFile.readAsBytes() so picked files can be read even when withData was not used and the file only has a local path or a stream source.
• FileType.custom now shares a consistent allowedExtensions validation across platforms, throwing ArgumentError when filters are missing or used with a non-custom file type.
• The ffi, win32, and flutter_lints dependencies have been updated.

Android

• Prevents unresolved references when extracting hashCode under a forced JVM version. #2070

What's Changed

• Fix saveFile bytes handling on Android and iOS by @vicajilau in #2038
• Fix iOS picker stuck state on fast swipe dismiss by @vicajilau in #2040
• [All platforms][IOS] - feature: Refactor code in example & ios image order by @daniJimen in #2047
• [IOS] feature: IOS prevent freece UI by @daniJimen in #2048
• Fix web readAsBytes fallback for blob URLs by @vicajilau in #2042
• [Android] - Feature: add coroutine to save file process by @daniJimen in #2045

Full Changelog: v12.0.0-beta.4...v12.0.0-beta.5

Android

• saveFile now writes file data using Kotlin Coroutines (CoroutineScope(Dispatchers.IO).launch), keeping all I/O off the main thread and preventing UI freezes.

iOS

• Fixed a race condition when dismissing the file picker with a fast swipe, preventing the picker from getting stuck in a multiple_request state until app restart. #2021
• iOS now preserves the selection order when picking multiple files: the list of returned files will match the order in which the user selected them.
• saveFile now performs file writing on a background thread (DispatchQueue.global), preventing UI freezes when saving large files.

Web

• Fixed PlatformFile.readAsBytes() so files picked on Web can recover data from blob: and data: URLs when withData was not used.
• Added Web fallback to stream file bytes from blob:/data: URLs: when the ReadableStream API is supported.

What's Changed

• fix(android): fix FileType.any subdirectory visibility by @vicajilau in #2016
• feat: implement pickFile() API and improve PlatformFile documentation (#1469) by @vicajilau in #2017
• fix(darwin): add missing FlutterFramework dependency to Package.swift by @vicajilau in #2025
• fix(android): remove explicit KGP dependency to resolve warnings under AGP 9.0+ by @vicajilau in #2026
• Feature/migrate goovy to kts by @daniJimen in #2028
• feat: summarize file bytes in debug output by @vicajilau in #2029

Full Changelog: v12.0.0-beta.3...v12.0.0-beta.4

General

• Added pickFile() static method as a convenience wrapper for single file selection, returning PlatformFile? directly. #1469
• BREAKING CHANGE: Refactored saveFile() to make fileName and bytes required parameters across all platforms for a more consistent API. Improved the method's documentation for better clarity.
• Improved documentation for PlatformFile properties (path, bytes, readStream) to clarify nullability and usage across platforms. #1469
• BREAKING CHANGE: The allowMultiple parameter on pickFiles() now defaults to true. Use pickFile() for single-file selection. (allowMultiple is deprecated and will be removed in a future release.)
• Deprecated withData, withReadStream, and readSequential on pickFiles()/pickFile(). Users should call PlatformFile.readAsBytes() or PlatformFile.readAsByteStream() to load file data on demand. These parameters will be removed in a future release.
• Improved PlatformFile.toString() output to display byte length instead of full content.

Android

• Fixed an issue where FileType.any would prevent subdirectories from being listed in the system file explorer by ensuring EXTRA_MIME_TYPES is correctly passed as an array. #2013
• Removed explicit Kotlin Gradle Plugin (KGP) application and dependencies from build files to resolve warnings under AGP 9.0+.
• Updated Android build tooling and dependencies: Android Gradle Plugin bumped to 8.5.2, androidx.core:core and androidx.core:core-ktx updated to 1.18.0, androidx.lifecycle:lifecycle-runtime updated to 2.10.0, and org.apache.tika:tika-core updated to 3.3.0.
• Migrated Android build files from Groovy to Kotlin DSL (build.gradle.kts, settings.gradle.kts).
• Added Android AGP compatibility CI workflow.

Darwin

• Added missing FlutterFramework dependency to Package.swift for Swift Package Manager (SPM) compatibility.

What's Changed

• fix(android): support AGP 9+ and android.builtInKotlin property for plugin registration (#2002) by @daniJimen in #2010
• Update version to 12.0.0-beta.3 and fix Android plugin registration by @vicajilau in #2011
• fix(android): update error code to explorer_not_found when file explorer is missing (#1850) by @daniJimen in #2008
• feat: add support for custom dialog titles in pickFileAndDirectoryPaths (#1911) by @daniJimen in #2009
• Feature/fix add loading into save (#1918) by @daniJimen in #2007

Full Changelog: v12.0.0-beta.2...v12.0.0-beta.3

General

• Added onFileLoading callback to saveFile and implemented status tracking via an event channel. saveFile now reports loading status (for example FilePickerStatus.loading and FilePickerStatus.done).
• Offloaded file saving (writing bytes) to a background isolate to avoid blocking the UI when saving large files.
• Ensured the event subscription used for loading status is always cancelled in a finally block to prevent leaks and spurious events.

Android

• Fixed Android plugin registration when using AGP 9+ with android.builtInKotlin=false, while preserving support for older AGP setups.

What's Changed

• fix(android): handle OutOfMemoryError gracefully on large withData selections (#1997) by @vicajilau in #2001
• fix: improve image selection logic and update build dependencies by @daniJimen in #2004
• Update dependency versions for 12.0.0-beta.2 by @vicajilau in #2006

Full Changelog: v12.0.0-beta.1...v12.0.0-beta.2

General

• Updated dependencies: flutter_plugin_android_lifecycle to 2.0.34, path to 1.9.1, win32 to 6.2.0, cross_file to 0.3.5+2, web to 1.1.1, and dbus to 0.7.12.

Android

• Added a controlled out_of_memory error when picking large files with withData, avoiding Android crashes and recommending withReadStream as a safer alternative for large or multiple selections. #1997 Breaking Change: FileType.image now opens the native image gallery instead of the document picker, ignoring allowedExtensions on Android. #2004

What's Changed

• Running dart format . in the repository by @vicajilau in #1982
• feat: migrate iOS and macOS to shared Darwin sources by @vicajilau in #1983
• fix(darwin): avoid false FlutterMacOS SourceKit errors by @vicajilau in #1984
• fix(android): normalize duplicate saveFile names to preserve extension by @vicajilau in #1985
• fix(android): normalize duplicate save names and avoid nested collision suffixes by @vicajilau in #1986
• Fix web default for pickFiles withData by @vicajilau in #1988
• fix(android): update gradle wrapper to 8.7 to fix AGP 8.5.1 minimum requirement error by @vicajilau in #1991
• Implement Storage Access Framework (SAF) with persistable URI grants by @vicajilau in #1989
• chore(windows): migrate win32 to 6.0.1 by @vicajilau in #1981
• chore: update version to 12.0.0-beta.1 in pubspec.yaml by @vicajilau in #1999
• chore: update changelog to reflect beta version 12.0.0-beta.1 by @vicajilau in #2000

Full Changelog: v11.0.2...v12.0.0-beta.1

General

• Raised the minimum supported Flutter/Dart version to Flutter 3.38 / Dart 3.10 across all platforms. #1980

Windows

• Migrated win32 dependency to 6.0.0 and updated the Windows file picker implementation to match the new Win32/COM APIs. #1980

Darwin

• Migrated the iOS and macOS native implementations to shared Darwin sources.
• BREAKING CHANGE: The minimum supported iOS deployment target is now 14.0.
• Removed the DKImagePickerController / DKPhotoGallery dependency chain from the Darwin iOS path.

Android

• Implemented support for Android Storage Access Framework (SAF) Persistable URI Grants, allowing long-term access to files and directories across device reboots. #1825 #721
• Added AndroidSAFOptions and AndroidSAFHandle to configure and manage persistent permissions.
• Introduced AndroidPlatformFile as a subclass of PlatformFile to encapsulate SAF-specific metadata.
• Updated the Android Gradle Wrapper to 8.7 to ensure compatibility with Android Gradle Plugin (AGP) 8.5.1.
• Improved saveFile naming behavior when a duplicate file exists, normalizing duplicate names to keep the extension suffix (for example, file (1).bak instead of file.bak (1)). #1947

Web

• Fixed pickFiles() default withData behavior in the public API to correctly default to true on web when not explicitly provided. #1987

Tika added ~300 KB to the Android binary just to detect a MIME type in
saveFile(). MIME types are now resolved from the file name extension
via MimeTypeMap, with URLConnection.guessContentTypeFromStream as a
content-sniffing fallback when no usable extension is available.

Fixes #2101

Android

• Removed the Apache Tika dependency (~300 KB) used for MIME type detection in saveFile(). MIME types are now resolved from the file name extension via MimeTypeMap, with URLConnection.guessContentTypeFromStream as a content-sniffing fallback when no extension is available. #2101

What's Changed

• fix: Applied the v11 changes that were missing from the document and corrected various typos by @jooy2 in #1977
• fix(linux): resolve Cannot add to a fixed-length list (#1976) by @vicajilau in #1978
• fix(android): mitigate CWE-22 path traversal vulnerability in FileUtils by @vicajilau in #1979

New Contributors

• @jooy2 made their first contribution in #1977

Full Changelog: v11.0.1...v11.0.2

Android

• Fixed a Path Traversal vulnerability (CWE-22) when resolving file paths from external content providers. #1967

Linux

• Fixed "Cannot add to a fixed-length list" crash when opening or saving files with an initial directory on Linux. #1976

Android

• Fixed backward compatibility with Android Gradle Plugin (AGP) versions below 9.0. #1973

General

• BREAKING CHANGE: Refactored FilePicker class to use static methods instead of an instance-based approach. Users should now call FilePicker.pickFiles(), FilePicker.getDirectoryPath(), and FilePicker.saveFile() directly.
• Added cancelUploadOnWindowBlur to the public pickFiles API (Web only). #1961
• Reordered and cleaned up exports in file_picker.dart.

Web

• Added WASM support for the web file picker. #1950

Android

• Fixed an issue where file type selection (audio, video, media) was not being considered correctly on Android. #1959
• Updated Android package to support AGP 9. #1942

Desktop (macOS)

• Added a new method, skipEntitlementsChecks(), to allow users to bypass entitlements checks on macOS when using the plugin without Sandbox enabled. #1845

Linux

• Fixed a crash when initialDirectory contains special characters #1963

General

• Reverted breaking changes accidentally introduced in 10.3.9 to maintain Semantic Versioning compliance.

Android

• Updated Tika library to resolve vulnerability CVE-2025-66516 and CVE-2025-54988 (Critical XXE vulnerability).

Android

• Updated Apache Tika to 3.2.3 to address CVE-2025-66516 and CVE-2025-54988 (Critical XXE vulnerability).
• Support Gradle 9

iOS

• Rename FileUtils to FilePickerUtils #1921

Android

• Restores the ms[df] URI handling logic in FileUtils.kt to fix file selection returning null on some devices.

Android

• Fixed an issue where file type filtering was not being applied correctly, now only displaying files that match the selected MIME types. #1906

Android

• Added support for 16 KB page sizes. #1888

Android

• Updated compileSdk to use flutter.compileSdkVersion. #1842

Linux

• Fixed an issue where initialDirectory was not working. #1878

Linux

• Fixed an issue filtering files by extension on Linux. #1870 @Decodetalkers

General

• Fixed onFileLoading handler to process status changes only when data is a bool.

Desktop

• Support xdg desktop portal filechooser on linux. #1827 @Decodetalkers

Android

• Fixed an issue where CSV files were not properly filtered during file selection. #1849 @SoftWyer

Web

• Introduced bool flag to control upload behavior on window blur. #1833 @mugglmenzel

Android

• Fixed an issue where custom MIME types were failing to load picking files on Chromebook. #1858 @vicajilau

General

• Fixed build failures on Flutter 3.24 caused by changes to address Win32 deprecation warnings on Windows. #1855 @vicajilau

Android

• Fixed an issue where some files would incorrectly append a .txt extension when saving files on Android. @vicajilau

Android

• Fixed an issue where the image upload would not display the loading indicator.

Desktop

• Added support for webp images on Desktop platforms. #1491

Android

• Fixed an issue where saving files was failing with some MimeTypes #1789, #1818, #1819 and #1820

Android

• Fixed an issue when a folder is selected on an external storage #1801

Android

• Fixed an issue when a folder is selected #1802

Web

• Fixed a memory leak on the web.

Android

• Fixed an issue when you try to select more than one file#1796
• Fixed the app not filter correctly for the selected file types #1792

iOS

• Fixed an app crash when calling .saveFile twice and cancelling the native save operation via the UI #1626 @Leapward-Koex
• Fixed a .saveFile future never completing when .saveFile is called twice without waiting for the first completion. @Leapward-Koex

Android

• Fixed an issue where paths were loaded with duplicated endings. #1767

Android

• Fixed an issue loading files. #1777

Android

• Improved mimetype detection. @vicajilau

Android

• Migrated Android code base from Java to Kotlin.
• Fixed an issue where compressed images were always saved as JPEG files. #1738@vicajilau
• Fixed an issue where files without extension were not saved properly. @vicajilau

iOS

• Fixed an issue where compressionQuality on iOS was not loaded properly. #1761

Desktop (macOS)

• Introduced a new method, pickFileAndDirectoryPaths(), which displays a dialog enabling users to select both files and directories simultaneously. The method returns their absolute paths. Only available for macOS.

General

• BREAKING CHANGE: The compressionQuality property in the pickFiles method now defaults to 0.
• BREAKING CHANGE: The allowCompression property has been deprecated in favor of compressionQuality, and now defaults to false.

Android

• Fixed a permission denied exception on Android 11 or lower when compressionQuality is not 0. (#1742). @vicajilau
• Fixed an issue where images were duplicated to the "Pictures" folder on Android. (#1743) @vicajilau

Desktop (macOS)

• Fixed an issue when the active viewController is not a FlutterViewController.

Desktop (macOS)

• Updated the file picker to check for missing entitlements, instead of failing silently. @vicajilau.

Desktop (macOS)

• Present file picker panel as a sheet modal to the Flutter application window. #1734

Desktop (macOS, Windows, Linux)

• Fixes an inconsistency for saveFile that did not save the file, when bytes are provided on desktop platforms. @vicajilau.

Web

• Added an implementation for saveFile() on the web. @vicajilau.

Android

• Added ProGuard consumer rules to automatically exclude androidx.lifecycle.DefaultLifecycleObserver from obfuscation.

Android

• Fixes: File streams not getting closed.

Windows

• Move getDirectoryPath() to its own isolate to avoid COM initialization conflicts with other plugins #1713 @tguerin.

Web

• BREAKING CHANGE: pickFiles() now loads files as blobs. See the note in the updated wiki

Android

• Updated example project Android sources. @vicajilau

General

• Added compatibility with Flutter 3.29. @vicajilau.

Desktop (Windows)

• Fixes the issue under Windows that could be raised when another plugin uses CoInitializeEx and the File Explorer windows doesn't popup. #1708

Android

• Fixes allowCompression not working on Android. 1633

Android

• Fix: Handle Null Byte Array in saveFile Method #1662 @vicajilau.

General

• Updates flutter_plugin_android_lifecycle, ffi, path, win32, cross_file and web dependencies @vicajilau.
• Updates CI/CD with new dependencies @vicajilau.

Android

• Fix pickFiles for Android with launchMode=singleInstance #1700, #1404

iOS

• Fix 1367

Desktop (macOS) && iOS

• Adds support for Swift Package Manager for compatibility with new projects #1582

Desktop (macOS)

• Reimplement macOS file picker using method channels (fixes #1492, #1445, #1674, #1685)
• BREAKING CHANGE: pickFiles() now requires the com.apple.security.files.user-selected.read-only entitlement on macOS. Without this entitlement, the file picker will not open, and the method will return null. See the note in the updated wiki

iOS

• Fix Image Picker to Handle Partial Failures Gracefully #1554

Android

• Fix Android compile error #1643

Android

• Fix #872 by removing unnecessary external storage permission

iOS

• Fixes a crash when sometimes user swipe the modal down and call it again. 1357