@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

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 permissions for reading files. Android only.

Returns: Promise<PermissionStatus>

Since: 8.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permissions for reading files. 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 permission to read media files is granted | | 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