@capgo/capacitor-file-picker

File picker Capacitor plugin - Pick files, images, videos, and directories

Why Capacitor File Picker?

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

Documentation

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

Compatibility

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.

Install

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

Requirements

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

Android media permissions and Google Play review

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.

API

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

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

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

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

pickDirectory() => Promise<PickDirectoryResult>

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

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

checkPermissions() => Promise<PermissionStatus>

requestPermissions() => Promise<PermissionStatus>

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

removeAllListeners() => Promise<void>

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