@capgo/capacitor-file-picker
v8.1.2TypeScript
File picker Capacitor plugin - Pick files, images, videos, and directories
506/weekUpdated 3 days agoMPL-2.0Unpacked: 147.8 KB
Published by Martin Donadieu
npm install @capgo/capacitor-file-picker@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
``bash`
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.
$3
`typescript`
pickFiles(options?: PickFilesOptions | undefined) => Promise
Pick one or more files from the device.
| Param | Type | Description |
| ------------- | ------------------------------------------------------------- | --------------------------- |
| options | PickFilesOptions | - Options for picking files |
Returns: Promise<PickFilesResult>
Since: 8.0.0
--------------------
$3
`typescript`
pickImages(options?: PickMediaOptions | undefined) => Promise
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
--------------------
$3
`typescript`
pickVideos(options?: PickMediaOptions | undefined) => Promise
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
--------------------
$3
`typescript`
pickMedia(options?: PickMediaOptions | undefined) => Promise
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
--------------------
$3
`typescript`
pickDirectory() => Promise
Pick a directory from the device.
Android/iOS only.
Returns: Promise<PickDirectoryResult>
Since: 8.0.0
--------------------
$3
`typescript`
convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise
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
--------------------
$3
`typescript`
copyFile(options: CopyFileOptions) => Promise
Copy a file to a new location.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------- | ------------------------------ |
| options | CopyFileOptions | - Options for copying the file |
Since: 8.0.0
--------------------
$3
`typescript`
checkPermissions() => Promise
Check permissions for reading files.
Android only.
Returns: Promise<PermissionStatus>
Since: 8.0.0
--------------------
$3
`typescript`
requestPermissions() => Promise
Request permissions for reading files.
Android only.
Returns: Promise<PermissionStatus>
Since: 8.0.0
--------------------
$3
`typescript`
addListener(eventName: 'pickerDismissed', listenerFunc: PickerDismissedListener) => Promise
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
--------------------
$3
`typescript`
removeAllListeners() => Promise
Remove all listeners for this plugin.
Since: 8.0.0
--------------------
$3
`typescript`
getPluginVersion() => Promise<{ version: string; }>
Get the native Capacitor plugin version.
Returns: Promise<{ version: string; }>
Since: 8.0.0
--------------------
$3
#### 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> |
$3
#### PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
#### PickerDismissedListener
Listener callback for picker dismissed event.
(event: null): void