file_picker 12.1.2

A package that allows you to use a native file explorer to pick single or multiple absolute file paths, with extension filtering support.

File Picker

A plugin that allows you to use the native file explorer to pick single or multiple files, with extensions filtering support.

Currently supported features

• Uses OS default native pickers
• Supports multiple platforms (Mobile, Web, Desktop)
• Supports WebAssembly (Wasm) compilation
• Pick files using custom format filtering — you can provide a list of file extensions (pdf, svg, zip, etc.)
• Pick files from cloud files (GDrive, Dropbox, iCloud)
• Single or multiple file picks
• Supports retrieving as XFile (cross_file) for easy manipulation with other libraries
• Different default type filtering (media, image, video, audio or any)
• Picking directories
• Picking both files and directories simultaneously
• Read file content easily via file.readAsBytes() or stream via file.readAsByteStream()
• Open a save-file / save-as dialog (a dialog that lets the user specify the drive, directory, and name of a file to save)

If you have any feature that you want to see in this package, please feel free to issue a suggestion. 🎉

Compatibility Chart

API	Android	iOS	Linux	macOS	Windows	Web
clearTemporaryFiles()	✅	✅	❌	❌	❌	❌
getDirectoryPath()	✅	✅	✅	✅	✅	❌
pickFileAndDirectoryPaths()	❌	❌	❌	✅	❌	❌
pickFile()	✅	✅	✅	✅	✅	✅
pickFiles()	✅	✅	✅	✅	✅	✅
saveFile()	✅	✅	✅	✅	✅	✅

See the official API reference on pub.dev for further details.

Darwin implementation notes

The iOS and macOS native implementations live under the shared Darwin source tree (file_picker_darwin). The iOS implementation requires iOS 14.0 or newer because it uses PHPickerViewController and PHPickerResult.

Migrating to v12

Version 12.0 transitions file_picker to a federated plugin architecture.

Key Breaking Changes & Migration Steps

1. FilePicker.pickFiles() Returns List<PlatformFile>:

   • FilePickerResult has been removed in favor of direct lists of PlatformFile.
   • Returns an empty list ([]) if the user canceled the operation.
   • v11: FilePickerResult? result = await FilePicker.pickFiles();
   • v12: List<PlatformFile> files = await FilePicker.pickFiles();

2. Single File Picking:

   • Use FilePicker.pickFile() to pick a single file returning PlatformFile?.

3. Reading Bytes and Streaming:

   • Instead of using withData: true or withReadStream: true flags, use PlatformFile methods directly:
     • Uint8List bytes = await file.readAsBytes();
     • Stream<Uint8List> stream = file.readAsByteStream();

4. Platform Options:

   • Platform-specific parameters are grouped into configuration options, with implementations per platform:
     • AndroidOptions / FilePickerAndroidOptions
     • DarwinOptions
     • WindowsOptions / FilePickerWindowsOptions
     • LinuxOptions / FilePickerLinuxOptions
     • WebOptions / FilePickerWebOptions

Documentation

For platform-specific setup, see the README of the platform package you're targeting (e.g. file_picker_darwin for macOS entitlements, android_file_picker for Android notes). For the full API, see the official API reference on pub.dev.

Usage

Single file

PlatformFile? file = await FilePicker.pickFile();

if (file != null) {
  print(file.name);
  print(await file.length());
} else {
  // User canceled the picker
}

Multiple files

List<PlatformFile> files = await FilePicker.pickFiles();

if (files.isNotEmpty) {
  for (final file in files) {
    print(file.name);
  }
} else {
  // User canceled the picker
}

Multiple files with extension filter

List<PlatformFile> files = await FilePicker.pickFiles(
  type: FileType.custom,
  allowedExtensions: ['jpg', 'pdf', 'doc'],
);

iOS photo-library asset representation

List<PlatformFile> files = await FilePicker.pickFiles(
  type: FileType.video,
  compressionQuality: 0,
  darwinOptions: const DarwinOptions(
    assetRepresentationMode: DarwinAssetRepresentationMode.current,
  ),
);

DarwinAssetRepresentationMode.automatic is the default. Use current to avoid transcoding when possible, or compatible to request a broadly compatible representation. Non-automatic modes require compressionQuality: 0 and only affect media selected from the iOS photo library.

Pick a directory

String? selectedDirectory = await FilePicker.getDirectoryPath();

if (selectedDirectory == null) {
  // User canceled the picker
}

Save-file / save-as dialog

Uri? outputFile = await FilePicker.saveFile(
  dialogTitle: 'Please select an output file:',
  fileName: 'output-file.pdf',
  bytes: pdfBytes,
);

if (outputFile == null) {
  // User canceled the picker
}