@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.
Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.
➡️ Get started for free
14-day unlimited free trial. No credit card required
🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use
@capgo/capacitor-file-pickerin your Capacitor app:npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-file-picker to my Capacitor app and wire it up." Agent setup guides · Hosted MCP
Key features
- Files:
pickFiles()picks one or more files of any type. - Media:
pickImages(),pickVideos()andpickMedia()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 andcopyFile()copies a picked file to a new location. - Picker events: a
pickerDismissedlistener plus storage permission helpers. - Platforms: iOS, Android and Web. Directory picking, HEIC conversion and file copy are native only.
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
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
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(...)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(...)
pickFiles(options?: PickFilesOptions | undefined) => Promise<PickFilesResult>
Pick one or more files from the device.
| Param | Type | Description |
|---|---|---|
options | PickFilesOptions | - Options for picking files |
Returns: Promise<PickFilesResult>
Since: 8.0.0
pickImages(...)
pickImages(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>
Pick one or more images from the gallery.
Android/iOS only.
On Android, limit is enforced by the system photo picker when available
(Android 13+, or Android 11-12 with the Google Play system photo picker extension).
Older Android versions may allow selecting more items than limit; results are
truncated to limit before they are returned.
| Param | Type | Description |
|---|---|---|
options | PickMediaOptions | - Options for picking images |
Returns: Promise<PickFilesResult>
Since: 8.0.0
pickVideos(...)
pickVideos(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>
Pick one or more videos from the gallery.
Android/iOS only.
On Android, limit is enforced by the system photo picker when available
(Android 13+, or Android 11-12 with the Google Play system photo picker extension).
Older Android versions may allow selecting more items than limit; results are
truncated to limit before they are returned.
| Param | Type | Description |
|---|---|---|
options | PickMediaOptions | - Options for picking videos |
Returns: Promise<PickFilesResult>
Since: 8.0.0
pickMedia(...)
pickMedia(options?: PickMediaOptions | undefined) => Promise<PickFilesResult>
Pick one or more images or videos from the gallery. Android/iOS only.
| Param | Type | Description |
|---|---|---|
options | PickMediaOptions | - Options for picking media |
Returns: Promise<PickFilesResult>
Since: 8.0.0
pickDirectory()
pickDirectory() => Promise<PickDirectoryResult>
Pick a directory from the device. Android/iOS only.
Returns: Promise<PickDirectoryResult>
Since: 8.0.0
convertHeicToJpeg(...)
convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise<ConvertHeicToJpegResult>
Convert a HEIC image to JPEG format. iOS only.
| Param | Type | Description |
|---|---|---|
options | ConvertHeicToJpegOptions | - Options for the conversion |
Returns: Promise<ConvertHeicToJpegResult>
Since: 8.0.0
copyFile(...)
copyFile(options: CopyFileOptions) => Promise<void>
Copy a file to a new location.
| Param | Type | Description |
|---|---|---|
options | CopyFileOptions | - Options for copying the file |
Since: 8.0.0
checkPermissions()
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()
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('pickerDismissed', ...)
addListener(eventName: 'pickerDismissed', listenerFunc: PickerDismissedListener) => Promise<PluginListenerHandle>
Add a listener for the picker dismissed event. iOS only.
| Param | Type | Description |
|---|---|---|
eventName | 'pickerDismissed' | - The event name |
listenerFunc | PickerDismissedListener | - The listener function |
Returns: Promise<PluginListenerHandle>
Since: 8.0.0
removeAllListeners()
removeAllListeners() => Promise<void>
Remove all listeners for this plugin.
Since: 8.0.0
getPluginVersion()
getPluginVersion() => Promise<{ version: string; }>
Get the native Capacitor plugin version.
Returns: Promise<{ version: string; }>
Since: 8.0.0
Interfaces
PickFilesResult
Result of picking files.
| Prop | Type | Description |
|---|---|---|
files | PickedFile[] | Array of picked files |
PickedFile
Represents a picked file.
| Prop | Type | Description |
|---|---|---|
name | string | The name of the file |
path | string | The path to the file |
mimeType | string | The MIME type of the file |
size | number | The size of the file in bytes |
data | string | The base64 encoded data of the file. Only present if readData was true. |
blob | Blob | The Blob instance of the file. Web only. |
width | number | Width in pixels (images/videos only) |
height | number | Height in pixels (images/videos only) |
duration | number | Duration in seconds (videos only) |
modifiedAt | number | Last modified timestamp in milliseconds |
PickFilesOptions
Options for picking files.
| Prop | Type | Description | Default |
|---|---|---|---|
types | string[] | List of accepted MIME types or file extensions. On iOS, only MIME types are supported. Examples: ['image/*'], ['application/pdf'], ['.pdf', '.doc'] | |
limit | number | Maximum number of files to pick. Set to 0 for unlimited (platform default). | 0 |
readData | boolean | Whether to read the file data as base64. Note: Reading large files may cause memory issues. | false |
PickMediaOptions
Options for picking media (images/videos).
| Prop | Type | Description | Default |
|---|---|---|---|
limit | number | Maximum number of files to pick. Set to 0 for unlimited (platform default). On Android, when the system photo picker is available, the platform enforces this limit (capped by the device maximum). On older Android versions the picker may not enforce the limit; the plugin truncates the returned list to this value when needed. | 0 |
readData | boolean | Whether to read the file data as base64. Note: Reading large files may cause memory issues. | false |
skipTranscoding | boolean | iOS only: Skip transcoding of videos. | false |
ordered | boolean | iOS 15+ only: Show ordered selection badges. | false |
PickDirectoryResult
Result of picking a directory.
| Prop | Type | Description |
|---|---|---|
path | string | The path to the selected directory |
ConvertHeicToJpegResult
Result of HEIC to JPEG conversion.
| Prop | Type | Description |
|---|---|---|
path | string | The path to the converted JPEG file |
ConvertHeicToJpegOptions
Options for converting HEIC to JPEG.
| Prop | Type | Description | Default |
|---|---|---|---|
path | string | The path to the HEIC file to convert | |
quality | number | The compression quality for JPEG (0.0 - 1.0). | 0.9 |
CopyFileOptions
Options for copying a file.
| Prop | Type | Description | Default |
|---|---|---|---|
from | string | Source file path | |
to | string | Destination file path | |
overwrite | boolean | Whether to overwrite if destination exists. | false |
PermissionStatus
Permission status for file access.
| Prop | Type | Description |
|---|---|---|
readExternalStorage | PermissionState | Whether broad external storage or media permission is granted. Picker APIs that return user-selected files usually do not require this on Android 13+. |
accessMediaLocation | PermissionState | Whether permission to access media location is granted |
PluginListenerHandle
| Prop | Type |
|---|---|
remove | () => Promise<void> |
Type Aliases
PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
PickerDismissedListener
Listener callback for picker dismissed event.
(event: null): void