file_picker 12.0.0

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 API section of the File Picker Wiki or 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
     • WindowsOptions / FilePickerWindowsOptions
     • LinuxOptions / FilePickerLinuxOptions
     • WebOptions / FilePickerWebOptions

Documentation

See the File Picker Wiki for details on installation, setup, and usage.

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'],
);

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
}