API

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