@capgo/capacitor-file-picker

➡️ Get Instant updates for your App with Capgo

Missing a feature? We'll build the plugin for you 💪

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