https://github.com/Cap-go/capacitor-file-picker
Capacitor plugin File picker - Pick files, images, videos, and directories
https://github.com/Cap-go/capacitor-file-picker
capacitor-plugin capacitorjs
Last synced: about 1 month ago
JSON representation
Capacitor plugin File picker - Pick files, images, videos, and directories
- Host: GitHub
- URL: https://github.com/Cap-go/capacitor-file-picker
- Owner: Cap-go
- Created: 2025-12-16T03:27:43.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-31T22:48:37.000Z (about 1 month ago)
- Last Synced: 2026-02-01T10:27:33.322Z (about 1 month ago)
- Topics: capacitor-plugin, capacitorjs
- Language: Java
- Homepage: https://capgo.app
- Size: 112 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
- awesome-capacitor - File Picker - Pick files, images, videos, and directories. ([Capgo plugins](https://capgo.app/) / Storage & Files)
README
# @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(...)`](#pickfiles)
* [`pickImages(...)`](#pickimages)
* [`pickVideos(...)`](#pickvideos)
* [`pickMedia(...)`](#pickmedia)
* [`pickDirectory()`](#pickdirectory)
* [`convertHeicToJpeg(...)`](#convertheictojpeg)
* [`copyFile(...)`](#copyfile)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`addListener('pickerDismissed', ...)`](#addlistenerpickerdismissed-)
* [`removeAllListeners()`](#removealllisteners)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
Capacitor File Picker Plugin interface for selecting files, images, videos, and directories.
### pickFiles(...)
```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
--------------------
### pickImages(...)
```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
--------------------
### pickVideos(...)
```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
--------------------
### pickMedia(...)
```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
--------------------
### pickDirectory()
```typescript
pickDirectory() => Promise
```
Pick a directory from the device.
Android/iOS only.
**Returns:** Promise<PickDirectoryResult>
**Since:** 8.0.0
--------------------
### convertHeicToJpeg(...)
```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
--------------------
### copyFile(...)
```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
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise
```
Check permissions for reading files.
Android only.
**Returns:** Promise<PermissionStatus>
**Since:** 8.0.0
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise
```
Request permissions for reading files.
Android only.
**Returns:** Promise<PermissionStatus>
**Since:** 8.0.0
--------------------
### addListener('pickerDismissed', ...)
```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
--------------------
### removeAllListeners()
```typescript
removeAllListeners() => Promise
```
Remove all listeners for this plugin.
**Since:** 8.0.0
--------------------
### getPluginVersion()
```typescript
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