Skip to content
philenius edited this page Feb 20, 2022 · 49 revisions

Filters

All the paths can be filtered using one of the following enumerations:

Filter Description
FileType.any Will let you pick all available files. On iOS it opens the Files app.
FileType.custom Will let you pick a path for the extension matching the allowedExtensions provided. Opens Files app on iOS.
FileType.image Will let you pick an image file. Opens gallery (Photos app) on iOS.
FileType.video Will let you pick a video file. Opens gallery (Photos app) on iOS.
FileType.media Will let you pick either video or images. Opens gallery (Photos app) on iOS.
FileType.audio Will let you pick an audio file. Opens music on iOS and device must have Music app installed. Note that DRM protected files won't provide a path, null will be returned instead.

Parameters

There are a few common parameters that all picking methods support, those are listed below:

Parameter Type Description Supported Platforms Default
allowedExtensions List<String>? Accepts a list of allowed extensions to be filtered. Eg. [pdf, jpg] All -
allowCompression bool Defines whether image and/or video files should be compressed automatically by OS when picked. When set, Live Photos will also be converted to static JPEG images. On Android has no effect as it always returns the original or integral file copy. iOS true
dialogTitle String? The title to be set on desktop platforms modal dialog. Hasn't any effect on Web or Mobile. Desktop File Picker
initialDirectory String? Can be optionally set to an absolute path to specify where the dialog should open. Only supported on Linux, macOS, and Windows. Desktop -
lockParentWindow bool If true, then the child window (file picker window) will stay in front of the Flutter window until it is closed (like a modal window). Desktop (only Windows) false
onFileLoading Function(FilePickerStatus)? When provided, will receive the processing status of picked files. This is particularly useful if you want to display a loading dialog or so when files are being downloaded/cached Mobile & Web -
type FileType Defines the type of the filtered files. All FileType.any
useFullScreenDialog bool Lets the developer set to use full screen dialog (UIModalPresentationFullScreen) or the platform default (typically UIModalPresentationFormSheet). iOS (13+) false
withData bool Sets if the file should be immediately loaded into memory and available as Uint8List on its PlatformFile instance. Mobile & Web true on Web, false everywhere else
withReadStream bool Allows the file to be read into a Stream<List<int>> instead of immediately loading it into memory, to prevent high usage, specially with bigger files. If you want an example on how to use it, check it here. Mobile & Web false

Methods

pickFiles()

This is the main method to pick files and provides all the properties mentioned before. Will return a FilePickerResult — containing the List<PlatformFile>> — or null if picker is aborted.

NOTE: You must use FileType.custom when providing allowedExtensions, else it will throw an exception.

NOTE 2: On web the path will always be null as web always use fake paths, you should use the bytes instead to retrieve the picked file data.

Usage example

// Lets the user pick one file; files with any file extension can be selected
FilePickerResult result = await FilePicker.platform.pickFiles(type: FileType.any);

// The result will be null, if the user aborted the dialog
if(result != null) {
 File file = File(result.files.first.path);
}

// Lets the user pick one file, but only files with the extensions `svg` and `pdf` can be selected
FilePickerResult result = await FilePicker.platform.pickFiles(type: FileType.custom, allowedExtensions: ['svg', 'pdf']);

// The result will be null, if the user aborted the dialog
if(result != null) {
 File file = File(result.files.first.path);
}

getDirectoryPath()

Opens a folder picker dialog which lets the user select a directory path. Returns the absolute path to the selected directory. Returns null, if the user canceled the dialog or if the folder path couldn't be resolved.

Optionally, you can set the title of the dialog via the parameter dialogTitle. The parameter initialDirectory can be optionally set to an absolute path to specify where the dialog should open. This parameter only works on Linux and macOS (Windows implementation is missing).

On Windows, you can also set lockParentWindow to true to make the dialog always stay in foreground like a modal.

Platform Info
iOS Requires iOS 11 or above
Android Requires SDK 21 or above
Desktop Supported
Web Not supported

clearTemporaryFiles()

An utility method that will explicitly prune cached files from the picker. This is not required as the system will take care on its own, however, sometimes you may want to remove them, specially if your app handles a lot of files.

Platform Info
iOS All picked files are cached, so this will immediately remove them.
Android Since 2.0.0, all picked files are cached, so this will immediately remove them.
Desktop & Web Not implemented as it won't have any effect. Paths are always referencing the original files.

saveFile()

Opens a save-file / save-as dialog which lets the user select a file path and a file name to save a file. This function does not actually save a file. It only opens the dialog to let the user choose a location and file name. This function only returns the path to this (non-existing) file as a String. Returns null, if the user canceled the dialog.

Optionally, you can set the title of the dialog via the parameter dialogTitle, a default file name via the parameter fileName, and the initial directory where the dialog should open via the parameter initialDirectory. On Windows, you can also set lockParentWindow to true to make the dialog always stay in foreground like a modal. The parameters type and allowedExtensions can be used to set a list of valid file types. Please note that both parameters are just a proposal to the user as the save-file / save-as dialog does not enforce these restrictions.

NOTE: You must use FileType.custom when providing allowedExtensions, else it will throw an exception.

Platform Info
iOS Not supported
Android Not supported
Desktop Supported
Web Not supported
Clone this wiki locally