@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/

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