@capgo/capacitor-file-picker

Let users pick files, images, videos and folders with the native pickers on iOS and Android, with a web fallback for files and media. Convert HEIC photos on iOS and copy picked files where you need them.

• Files: pickFiles() picks one or more files of any type.
• Media: pickImages(), pickVideos() and pickMedia() open the photo library picker on iOS and Android. On web they open the browser file picker filtered by type.
• Folders: pickDirectory() returns a directory on iOS and Android.
• HEIC and copy: convertHeicToJpeg() converts photos on iOS and copyFile() copies a picked file to a new location.
• Picker events: a pickerDismissed listener plus storage permission helpers.
• Platforms: iOS, Android and Web. Directory picking, HEIC conversion and file copy are native only.

A comprehensive file picker plugin with full native support for iOS and Android:

• Pick Files - Select any file type with MIME type filtering
• Pick Images - Native photo library picker with multi-select
• Pick Videos - Native video picker with duration and dimensions
• Pick Media - Combined image and video picker
• Pick Directory - Select folders (Android/iOS)
• HEIC to JPEG - Convert HEIC images to JPEG (iOS only)
• Copy Files - Copy files to new locations
• File Metadata - Get size, dimensions, duration, and more

The most complete doc is available here: https://capgo.app/docs/plugins/file-picker/

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-file-picker` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-file-picker
npx cap sync

• iOS: iOS 15.0+
• Android: API 24+ (Android 7.0+)
• Web: Modern browsers with File API support

This plugin is designed around user-selected picker flows such as pickFiles(), pickImages(), pickVideos(), pickMedia(), and pickDirectory(). For one-time or infrequent file, image, or video selection, use these picker methods and avoid adding broad media permissions to your app manifest.

Google Play only allows READ_MEDIA_IMAGES and READ_MEDIA_VIDEO when photo or video access is directly related to your app's core purpose and picker alternatives are not sufficient. Do not request or retain these permissions only to let a user choose files, images, or videos.

Before publishing an app that declares these permissions:

• Make sure broad photo or video library access is required for the app's core functionality.
• Be ready to justify why Android Photo Picker or this plugin's picker methods are not sufficient.
• Remove broad media permissions if the app can work with user-selected files only.

If Google Play review rejects the app with a message like Photo and Video Permissions policy: Permission use is not directly related to your app's core purpose, remove the broad media permissions and rely on this plugin's picker APIs instead.

For apps coming from @capgo/capacitor-file, a custom media browser, or another broad-storage flow, the recommended alternative is @capgo/capacitor-file-picker with pickImages(), pickVideos(), pickMedia(), or pickFiles().

See Google's Photo and Video Permissions policy for the current review requirements.

• pickFiles(...)
• pickImages(...)
• pickVideos(...)
• pickMedia(...)
• pickDirectory()
• convertHeicToJpeg(...)
• copyFile(...)
• checkPermissions()
• requestPermissions()
• addListener('pickerDismissed', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor File Picker Plugin interface for selecting files, images, videos, and directories.

pickFiles(options?: PickFilesOptions | undefined) => Promise<PickFilesResult>

Pick one or more files from the device.

Returns: Promise<PickFilesResult>

Since: 8.0.0

pickImages(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>

Pick one or more images from the gallery. Android/iOS only.

Returns: Promise<PickFilesResult>

Since: 8.0.0

pickVideos(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>

Pick one or more videos from the gallery. Android/iOS only.

Returns: Promise<PickFilesResult>

Since: 8.0.0

pickMedia(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>

Pick one or more images or videos from the gallery. Android/iOS only.

Returns: Promise<PickFilesResult>

Since: 8.0.0

pickDirectory() => Promise<PickDirectoryResult>

Pick a directory from the device. Android/iOS only.

Returns: Promise<PickDirectoryResult>

Since: 8.0.0

convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise<ConvertHeicToJpegResult>

Convert a HEIC image to JPEG format. iOS only.

Returns: Promise<ConvertHeicToJpegResult>

Since: 8.0.0

copyFile(options: CopyFileOptions) => Promise<void>

Copy a file to a new location.

Since: 8.0.0

checkPermissions() => Promise<PermissionStatus>

Check broad storage or media permission state. Picker-only flows should not gate pickFiles(), pickImages(), pickVideos(), or pickMedia() on this permission on Android 13+. Android only.

Returns: Promise<PermissionStatus>

Since: 8.0.0

requestPermissions() => Promise<PermissionStatus>

Request broad storage or media permissions. Do not request or declare READ_MEDIA_IMAGES or READ_MEDIA_VIDEO only to use picker APIs. Google Play allows these permissions only when picker alternatives are not sufficient for core app functionality. Use @capgo/capacitor-file-picker picker methods instead for user-selected file, image, or video access. Android only.

Returns: Promise<PermissionStatus>

Since: 8.0.0

addListener(eventName: 'pickerDismissed', listenerFunc: PickerDismissedListener) => Promise<PluginListenerHandle>

Add a listener for the picker dismissed event. iOS only.

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 8.0.0

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 8.0.0

Result of picking files.

Represents a picked file.

Options for picking files.

Options for picking media (images/videos).

Result of picking a directory.

Result of HEIC to JPEG conversion.

Options for converting HEIC to JPEG.

Options for copying a file.

Permission status for file access.

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Listener callback for picker dismissed event.

(event: null): void