What is Image Picker in Flutter?
Image Picker is a Flutter plugin used to select images or videos from the device gallery or capture new ones using the camera. It is commonly used for features such as profile pictures, media attachments, or content uploads.
The most widely used implementation is provided by the image_picker package, which offers a simple API and official support for mobile and web platforms.
How does it work?
The plugin functions as a bridge between the Dart runtime and the operating system's native intent system or media controllers.
- On Android, it launches an
Intent that delegates the task to a camera app or gallery selector chosen by the user. - On iOS, it presents the native
UIImagePickerController or PHPickerViewController over the Flutter view.
Once a user selects or captures media, the native layer writes the data to a temporary file in the app's cache directory and passes the file path back to Dart via a Platform Channel. This means the file exists locally on the device immediately after selection, but since it is stored in a temporary location, developers must persist it or upload it before the OS cleans up the cache.
Example of an Image Picker in Flutter
A basic example of picking a single image from the gallery:
final picker = ImagePicker();
Future<XFile?> pickImage() async {
return await picker.pickImage(
source: ImageSource.gallery,
);
}
The returned file can then be displayed in the UI, uploaded to a backend, or processed further.
Flutter multi image picker
Image Picker supports selecting multiple images using pickMultiImage.
final picker = ImagePicker();
Future<List<XFile>> pickMultipleImages() async {
return await picker.pickMultiImage();
}
This is commonly used for features like multi-image uploads or gallery selection. Support is stable on Android, iOS, and web, but exact behavior depends on platform capabilities.
Android state loss and retrieveLostData
On Android, opening the camera may cause the system to temporarily destroy the application’s MainActivity to free memory. This is especially common on older or low-memory devices. If this happens, the selected image can be lost when the user returns to the app, even though the photo was successfully taken.
To handle this correctly, Image Picker provides the retrieveLostData method, which allows recovering the image after the activity is recreated. Failing to handle this case results in an implementation that works only on the happy path and breaks for a subset of Android users.
Image Picker on iOS
On iOS, Image Picker requires explicit permission configuration. You must add usage descriptions to Info.plist for photo library and camera access. Without these entries, the picker will fail at runtime. iOS enforces strict privacy rules, making correct permission configuration mandatory even for simple image selection scenarios.
Image Picker on web in Flutter
On web, Image Picker opens a browser file selection dialog.
Important characteristics include:
- No guaranteed access to the device camera.
- Files returned as browser-backed
XFile objects. - No persistent local file paths like on mobile platforms.
Web support is reliable but more limited compared to Android and iOS.
Image compression and resizing
Image Picker provides built-in parameters for basic image optimization.
Options such as maxWidth, maxHeight, and imageQuality allow reducing image size before uploading it to a server. This is often sufficient to reduce file size from several megabytes to a few hundred kilobytes. Using these options is the simplest way to optimize uploads without introducing additional image processing libraries.
Common Image Picker pitfalls
Most problems originate from platform configuration or lifecycle handling rather than the Flutter API itself.
- Missing permissions on iOS or Android.
- Unhandled Android activity destruction.
- Incorrect assumptions about file paths on web.
- Not handling null results when the user cancels selection.
Best practices for using Image Picker in Flutter
- When using the Image Picker in production applications, it is important to treat it as an input mechanism rather than a full media management solution. Its primary role is to allow users to select or capture images, not to organize, edit, or store large media libraries.
- On Android, developers must handle the possibility of activity destruction, which can occur during backgrounding or configuration changes. Using
retrieveLostData ensures that selected images are recovered if the app is terminated or the activity is recreated while the picker was open. This prevents user frustration and data loss in real-world scenarios. - Permissions should be explicitly configured on both Android and iOS. Relying solely on runtime permission requests can result in inconsistent behavior. Always declare the required permissions in the native configuration files (
AndroidManifest.xml and Info.plist) and provide clear explanations to users. - Optimizing images before using them in the app is crucial for performance and bandwidth efficiency. Use the built-in compression options or resize images to appropriate dimensions before upload or processing. This reduces memory usage, speeds up network operations, and improves UI responsiveness.
- Error handling and cancellation management are also essential. Users may cancel the picker or encounter hardware or permission issues. Always handle these cases gracefully to avoid crashes or broken workflows.
- Finally, keep in mind that the Image Picker is not designed for advanced tasks like image editing, filtering, or long-term storage. For those needs, integrate dedicated libraries or backend services instead. By following these best practices, developers ensure that image selection remains reliable, performant, and user-friendly across platforms.
