Flutter’s powerful UI toolkit empowers developers to create seamless cross-platform applications—but when it comes to accessing local files, FilePicker stands out as the go-to solution. This in-depth guide explores everything you need to know to fully master FilePicker in Flutter, from setup and usage to real-world examples and best practices. Whether you’re building for Android, iOS, or desktop, this article will help you navigate file picking with confidence.
Introduction to FilePicker in Flutter
In Flutter development, file handling is essential for apps that upload images, documents, or other media. The FilePicker plugin offers a straightforward way to open a file explorer, allowing users to choose files from their local device. It supports multiple file types, file filtering, and even platform-specific customizations. This guide will help you make the most of this versatile package.
Why Use FilePicker Instead of ImagePicker?
While Flutter’s ImagePicker is great for photos and camera input, it’s limited to media files. FilePicker, on the other hand, is broader in scope. It lets users choose PDFs, DOCX files, ZIP archives, videos, and more. This makes it ideal for applications requiring document uploads, file previews, or content sharing beyond images.
Installing the FilePicker Package
To get started, open your pubspec.yaml and add the following dependency:
yaml
CopyEdit
file_picker: ^6.1.1
Then run flutter pub get to install it. This ensures your Flutter project includes the latest version of the FilePicker plugin.
Platform Setup for Android and iOS
For Android, modify your AndroidManifest.xml to include file access permissions:
xml
CopyEdit
<uses-permission android:name=”android.permission.READ_EXTERNAL_STORAGE”/>
<uses-permission android:name=”android.permission.WRITE_EXTERNAL_STORAGE”/>
On iOS, make sure to update your Info.plist with:
xml
CopyEdit
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to pick files from your device.</string>
Without these configurations, your file picking process may fail due to platform restrictions.
Basic Usage of FilePicker
Here’s a simple way to pick a single file using the plugin:
dart
CopyEdit
FilePickerResult? result = await FilePicker.platform.pickFiles();
if (result != null) {
PlatformFile file = result.files.first;
print(‘File name: ${file.name}’);
print(‘File path: ${file.path}’);
}
This code opens the native file picker and retrieves the selected file’s metadata including its name, size, and local path.
Picking Multiple Files at Once
You can allow users to select multiple files like this:
dart
CopyEdit
FilePickerResult? result = await FilePicker.platform.pickFiles(allowMultiple: true);
if (result != null) {
result.files.forEach((file) {
print(‘Picked file: ${file.name}’);
});
}
This is useful for file-sharing or batch-upload apps, allowing greater flexibility in user interaction.
Filtering File Types
Sometimes, you only want specific file formats, like PDFs or DOCX files. Use the type parameter:
dart
CopyEdit
FilePickerResult? result = await FilePicker.platform.pickFiles(
type: FileType.custom,
allowedExtensions: [‘pdf’, ‘docx’],
);
This ensures that users can only select files with the specified extensions, improving UX and reducing backend validation needs.
Saving and Reading Files After Picking
Once a file is picked, you often need to store or preview it. Use Dart’s File class to access file content:
dart
CopyEdit
File file = File(result.files.single.path!);
String contents = await file.readAsString();
print(contents);
This comes in handy for reading text documents or manipulating user-submitted data.
Uploading Picked Files to a Server
To upload a picked file to a backend, integrate http or dio package. Here’s a simple example using http:
dart
CopyEdit
var request = http.MultipartRequest(‘POST’, Uri.parse(‘YOUR_API_ENDPOINT’));
request.files.add(await http.MultipartFile.fromPath(‘file’, file.path!));
var response = await request.send();
if (response.statusCode == 200) {
print(“File uploaded successfully!”);
}
Remember to include proper headers and authentication if your API requires it.
Handling Null Responses Gracefully
Not every user will select a file. A robust app checks for cancellations:
dart
CopyEdit
if (result == null) {
print(‘User cancelled the picker.’);
}
Failing to check can lead to null exceptions or app crashes, especially during asynchronous operations.
Supporting Web and Desktop Platforms
FilePicker also supports web and desktop. When building for web, you don’t need extra permissions. On desktop (Windows/macOS/Linux), it uses native file dialogs. However, ensure your Flutter app is set up for desktop development and has required SDKs installed.
Limitations and Things to Watch Out For
While FilePicker is powerful, it’s not without quirks. For example, some Android versions may have limited file access if scoped storage is not handled properly. Always test on real devices and handle exceptions using try/catch blocks to ensure smoother experiences across platforms.
Alternative Plugins and When to Use Them
While FilePicker is versatile, other plugins like image_picker, file_selector, and flutter_document_picker exist. Use image_picker for camera/gallery apps and file_selector for apps where tighter integration with the desktop is needed. However, FilePicker remains the most flexible cross-platform solution overall.
Improving User Experience
To create a polished UX, combine FilePicker with loading indicators, progress bars, and file previews. Use packages like flutter_spinkit or percent_indicator to enhance your UI during uploads or processing time.
Best Practices for FilePicker in Production
Always sanitize file paths, check file sizes, and verify MIME types before sending files to a server. Implement permission checks where needed, and don’t forget to clean up temporary files after usage to optimize storage on the user’s device.
Future of File Handling in Flutter
As Flutter continues to evolve, we expect even tighter integrations with system-level features like drag-and-drop or native file explorers. The community is also contributing heavily to better desktop and web support, meaning file handling will only get easier and more powerful over time.
Final Thoughts
Incorporating FilePicker in Flutter is one of the most effective ways to add file selection features to your app. With a few lines of code, you can unlock multi-platform file interaction that’s essential for modern productivity, educational, and enterprise apps. With careful setup and a focus on UX, FilePicker transforms your app into a truly functional powerhouse.
