@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

| 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

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.

| 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.

| 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). | 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