---
description: Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system. Available for Android, iOS, and Web.
title: Capacitor File Picker Plugin for Android, iOS & Web - Capawesome
image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/file-picker.png
---
[Skip to content ](#capacitor-file-picker-plugin)
[π Introducing the **Capacitor Vault** plugin β store secrets behind biometrics or a device passcode. ](/blog/announcing-the-capacitor-vault-plugin/)
* [ SDKs ](/docs/sdks/)
* [ iOS ](#ios)
* [ Configuration ](#configuration)
* [ Usage ](#usage)
* [ API ](#api)
* [ Type Aliases ](#type-aliases)
* [ FAQ ](#faq)
* [ Related Plugins ](#related-plugins)
* [ Newsletter ](#newsletter)
* [ Changelog ](#changelog)
* [ License ](#license)
* [ Credits ](#credits)
* [ Firebase ](/docs/sdks/capacitor/firebase/)
* [ Formbricks ](/docs/sdks/capacitor/formbricks/)
* [ Geocoder ](/docs/sdks/capacitor/geocoder/)
* [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/)
* [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/)
* [ Gyroscope ](/docs/sdks/capacitor/gyroscope/)
* [ Haptics ](/docs/sdks/capacitor/haptics/)
* [ Home Indicator ](/docs/sdks/capacitor/home-indicator/)
* [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/)
* [ Install Referrer ](/docs/sdks/capacitor/install-referrer/)
* [ Keep Awake ](/docs/sdks/capacitor/keep-awake/)
* [ libSQL ](/docs/sdks/capacitor/libsql/)
* [ Light Sensor ](/docs/sdks/capacitor/light-sensor/)
* [ Live Update ](/docs/sdks/capacitor/live-update/)
* [ Localization ](/docs/sdks/capacitor/localization/)
* [ Mail Composer ](/docs/sdks/capacitor/mail-composer/)
* [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/)
* [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/)
* [ Media Session ](/docs/sdks/capacitor/media-session/)
* [ ML Kit ](/docs/sdks/capacitor/mlkit/)
* [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/)
* [ Network ](/docs/sdks/capacitor/network/)
* [ NFC ](/docs/sdks/capacitor/nfc/)
* [ Node.js ](/docs/sdks/capacitor/nodejs/)
* [ OAuth ](/docs/sdks/capacitor/oauth/)
* [ Passkeys ](/docs/sdks/capacitor/passkeys/)
* [ Password Autofill ](/docs/sdks/capacitor/password-autofill/)
* [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/)
* [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/)
* [ Pedometer ](/docs/sdks/capacitor/pedometer/)
* [ Permissions ](/docs/sdks/capacitor/permissions/)
* [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/)
* [ Photo Editor ](/docs/sdks/capacitor/photo-editor/)
* [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/)
* [ PixLive ](/docs/sdks/capacitor/pixlive/)
* [ PostHog ](/docs/sdks/capacitor/posthog/)
* [ Printer ](/docs/sdks/capacitor/printer/)
* [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/)
* [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/)
* [ Purchases ](/docs/sdks/capacitor/purchases/)
* [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/)
* [ Root Detection ](/docs/sdks/capacitor/root-detection/)
* [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/)
* [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/)
* [ Screen Reader ](/docs/sdks/capacitor/screen-reader/)
* [ Screenshot ](/docs/sdks/capacitor/screenshot/)
* [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/)
* [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/)
* [ Shake ](/docs/sdks/capacitor/shake/)
* [ Silent Mode ](/docs/sdks/capacitor/silent-mode/)
* [ SIM ](/docs/sdks/capacitor/sim/)
* [ SMS Composer ](/docs/sdks/capacitor/sms-composer/)
* [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/)
* [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/)
* [ Share Target ](/docs/sdks/capacitor/share-target/)
* [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/)
* [ SQLite ](/docs/sdks/capacitor/sqlite/)
* [ Superwall ](/docs/sdks/capacitor/superwall/)
* [ System WebView ](/docs/sdks/capacitor/system-webview/)
* [ Text Interaction ](/docs/sdks/capacitor/text-interaction/)
* [ Text Zoom ](/docs/sdks/capacitor/text-zoom/)
* [ Thermal State ](/docs/sdks/capacitor/thermal-state/)
* [ Toast ](/docs/sdks/capacitor/toast/)
* [ Torch ](/docs/sdks/capacitor/torch/)
* [ Vault ](/docs/sdks/capacitor/vault/)
* [ Volume ](/docs/sdks/capacitor/volume/)
* [ Wallet ](/docs/sdks/capacitor/wallet/)
* [ Wifi ](/docs/sdks/capacitor/wifi/)
* [ Zip ](/docs/sdks/capacitor/zip/)
* [ Cordova ](/docs/sdks/cordova/)
* [ Cloud ](/docs/cloud/)
* [ Integrations ](/docs/cloud/live-updates/integrations/)
* Concepts
* Reference
* [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/)
* [ FAQ ](/docs/cloud/live-updates/faq/)
* [ Native Builds ](/docs/cloud/native-builds/)
* [ Set Up Environments ](/docs/cloud/native-builds/environments/)
* [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/)
* [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/)
* [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/)
* [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/)
* [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/)
* [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/)
* [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/)
* [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/)
* [ Build without Git ](/docs/cloud/native-builds/build-without-git/)
* [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/)
* [ Integrations ](/docs/cloud/native-builds/integrations/)
* Reference
* [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/)
* [ FAQ ](/docs/cloud/native-builds/faq/)
* [ App Store Publishing ](/docs/cloud/app-store-publishing/)
* [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/)
* [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/)
* [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/)
* [ FAQ ](/docs/cloud/app-store-publishing/faq/)
* [ Automations ](/docs/cloud/automations/)
* [ Reference ](/docs/cloud/automations/reference/)
* [ Troubleshooting ](/docs/cloud/automations/troubleshooting/)
* [ FAQ ](/docs/cloud/automations/faq/)
* [ Assist ](/docs/cloud/assist/)
* [ CLI ](/docs/cloud/cli/)
* APIs and SDKs
* [ Webhooks ](/docs/cloud/webhooks/)
* [ Integrations ](/docs/cloud/integrations/)
* Account
* [ Organization ](/docs/cloud/organizations/)
* [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/)
* [ Audit Logs ](/docs/cloud/organizations/audit-logs/)
* [ Billing ](/docs/cloud/organizations/billing/)
* [ License Keys ](/docs/cloud/license-keys/)
* [ AI ](/docs/ai/)
* [ Insiders ](/docs/insiders/)
* [ Billing & Plans ](/docs/insiders/billing-and-plans/)
* [ FAQ ](/docs/insiders/faq/)
* [ License ](https://capawesome.io/legal/eula/)
* [ Support ](/docs/support/)
* [ Contributing ](/docs/contributing/)
* Contributing code
* [ Code of Conduct ](/docs/contributing/code-of-conduct/)
* [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion)
* [ Blog ](/blog/)
* Categories
* [ iOS ](#ios)
* [ Configuration ](#configuration)
* [ Usage ](#usage)
* [ API ](#api)
* [ Type Aliases ](#type-aliases)
* [ FAQ ](#faq)
* [ Related Plugins ](#related-plugins)
* [ Newsletter ](#newsletter)
* [ Changelog ](#changelog)
* [ License ](#license)
* [ Credits ](#credits)
# Capacitor File Picker Plugin[ΒΆ](#capacitor-file-picker-plugin "Permanent link")
Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system or gallery.
[  ](https://cloud.capawesome.io/)
## Features[ΒΆ](#features "Permanent link")
The Capacitor File Picker plugin is one of the most complete file selection solutions for Capacitor apps. Here are some of the key features:
* π₯οΈ **Cross-platform**: Supports Android, iOS and Web.
* π **Directory picking**: Allows users to select a directory to retrieve all files.
* πΌοΈ **Image picking**: Lets users select one or more images from the gallery.
* π₯ **Video picking**: Lets users select one or more videos from the gallery.
* π **File picking**: Lets users select one or more miscellaneous files from the file system.
* πΈ **HEIC to JPEG conversion**: Converts HEIC images to JPEG format on iOS.
* π **File metadata**: Retrieves metadata such as file size, name, mime type, and last modified timestamp.
* π¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
* π **Up-to-date**: Always supports the latest Capacitor version.
Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
## Use Cases[ΒΆ](#use-cases "Permanent link")
The File Picker plugin is typically used whenever an app needs the user to hand over a file, for example:
* **File uploads**: Let users attach documents such as PDFs or spreadsheets to a form and upload them to a server.
* **Profile and cover pictures**: Let users choose an existing photo from their gallery.
* **Media attachments**: Add images and videos to chat messages, posts, or support tickets.
* **Data imports**: Import CSV, JSON, or backup files into your app.
## Compatibility[ΒΆ](#compatibility "Permanent link")
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | \>=8.x.x | Active support |
| 6.x.x | 6.x.x | Deprecated |
| 5.x.x | 5.x.x | Deprecated |
## Guides[ΒΆ](#guides "Permanent link")
* [The File Handling Guide for Capacitor](https://capawesome.io/blog/the-file-handling-guide-for-capacitor/)
## Installation[ΒΆ](#installation "Permanent link")
You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:
`[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins
`
Then use the following prompt:
`` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-file-picker` plugin in my project.
``
If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:
`[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-file-picker
[](#%5F%5Fcodelineno-2-2)npx cap sync
`
### Android[ΒΆ](#android "Permanent link")
#### Variables[ΒΆ](#variables "Permanent link")
This plugin will use the following project variables (defined in your appβs `variables.gradle` file):
* `$androidxActivityVersion` version of `androidx.activity:activity` (default: `1.13.0`)
#### Permissions[ΒΆ](#permissions "Permanent link")
This API requires the following permissions be added to your `AndroidManifest.xml` before or after the `application` tag:
`[](#%5F%5Fcodelineno-3-1)
[](#%5F%5Fcodelineno-3-2)
[](#%5F%5Fcodelineno-3-3)
[](#%5F%5Fcodelineno-3-4)
`
### iOS[ΒΆ](#ios "Permanent link")
#### Entitlements[ΒΆ](#entitlements "Permanent link")
To use this plugin with Mac Catalyst, your app must have the `com.apple.security.files.user-selected.read-only` entitlement enabled. This allows the app to read files selected by the user. Check out the [Apple documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.security.files.user-selected.read-only) for more information.
`[](#%5F%5Fcodelineno-4-1)com.apple.security.files.user-selected.read-only
[](#%5F%5Fcodelineno-4-2)
`
If you don't want to use the plugin with Mac Catalyst, you can skip this step.
## Configuration[ΒΆ](#configuration "Permanent link")
No configuration required for this plugin.
## Usage[ΒΆ](#usage "Permanent link")
The following examples show how to pick files, images, videos, and directories, and how to process the selected files.
### Pick one or more files[ΒΆ](#pick-one-or-more-files "Permanent link")
Open the system file picker and let the user select one or more files of any type. The result contains the metadata (name, size, mime type, last modified timestamp) and, on Android and iOS, the path of each selected file:
`[](#%5F%5Fcodelineno-5-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-5-2)
[](#%5F%5Fcodelineno-5-3)const pickFiles = async () => {
[](#%5F%5Fcodelineno-5-4) const result = await FilePicker.pickFiles();
[](#%5F%5Fcodelineno-5-5) const file = result.files[0];
[](#%5F%5Fcodelineno-5-6)};
`
### Restrict the picker to specific file types[ΒΆ](#restrict-the-picker-to-specific-file-types "Permanent link")
Use the `types` option to only accept certain [IANA media types](https://www.iana.org/assignments/media-types/media-types.xhtml), for example PDF documents:
`[](#%5F%5Fcodelineno-6-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-6-2)
[](#%5F%5Fcodelineno-6-3)const pickPdfFiles = async () => {
[](#%5F%5Fcodelineno-6-4) const result = await FilePicker.pickFiles({
[](#%5F%5Fcodelineno-6-5) types: ['application/pdf'],
[](#%5F%5Fcodelineno-6-6) });
[](#%5F%5Fcodelineno-6-7)};
`
### Pick images or videos from the gallery[ΒΆ](#pick-images-or-videos-from-the-gallery "Permanent link")
Use `pickImages(...)`, `pickVideos(...)` or `pickMedia(...)` to open the photo gallery instead of the file picker. These methods are only available on Android and iOS:
`[](#%5F%5Fcodelineno-7-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-7-2)
[](#%5F%5Fcodelineno-7-3)const pickImages = async () => {
[](#%5F%5Fcodelineno-7-4) const result = await FilePicker.pickImages();
[](#%5F%5Fcodelineno-7-5)};
[](#%5F%5Fcodelineno-7-6)
[](#%5F%5Fcodelineno-7-7)const pickVideos = async () => {
[](#%5F%5Fcodelineno-7-8) const result = await FilePicker.pickVideos();
[](#%5F%5Fcodelineno-7-9)};
[](#%5F%5Fcodelineno-7-10)
[](#%5F%5Fcodelineno-7-11)const pickMedia = async () => {
[](#%5F%5Fcodelineno-7-12) // Pick both images and videos
[](#%5F%5Fcodelineno-7-13) const result = await FilePicker.pickMedia({ limit: 3 });
[](#%5F%5Fcodelineno-7-14)};
`
### Pick a directory[ΒΆ](#pick-a-directory "Permanent link")
Let the user select a directory, for example to import all files it contains. Only available on Android and iOS:
`[](#%5F%5Fcodelineno-8-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-8-2)
[](#%5F%5Fcodelineno-8-3)const pickDirectory = async () => {
[](#%5F%5Fcodelineno-8-4) const { path } = await FilePicker.pickDirectory();
[](#%5F%5Fcodelineno-8-5)};
`
### Upload a picked file to a server[ΒΆ](#upload-a-picked-file-to-a-server "Permanent link")
On the Web, the picked file contains a `Blob` instance. On Android and iOS, load the file as a blob using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch%5FAPI/Using%5FFetch) and the file's path. You can then append the blob to a `FormData` object and upload it:
`[](#%5F%5Fcodelineno-9-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-9-2)import { Capacitor } from '@capacitor/core';
[](#%5F%5Fcodelineno-9-3)
[](#%5F%5Fcodelineno-9-4)const uploadFile = async () => {
[](#%5F%5Fcodelineno-9-5) const result = await FilePicker.pickFiles({ limit: 1 });
[](#%5F%5Fcodelineno-9-6) const file = result.files[0];
[](#%5F%5Fcodelineno-9-7)
[](#%5F%5Fcodelineno-9-8) let blob: Blob;
[](#%5F%5Fcodelineno-9-9) if (file.blob) {
[](#%5F%5Fcodelineno-9-10) // Web
[](#%5F%5Fcodelineno-9-11) blob = file.blob;
[](#%5F%5Fcodelineno-9-12) } else {
[](#%5F%5Fcodelineno-9-13) // Android and iOS
[](#%5F%5Fcodelineno-9-14) const response = await fetch(Capacitor.convertFileSrc(file.path!));
[](#%5F%5Fcodelineno-9-15) blob = await response.blob();
[](#%5F%5Fcodelineno-9-16) }
[](#%5F%5Fcodelineno-9-17)
[](#%5F%5Fcodelineno-9-18) const formData = new FormData();
[](#%5F%5Fcodelineno-9-19) formData.append('file', blob, file.name);
[](#%5F%5Fcodelineno-9-20) await fetch('https://example.com/upload', {
[](#%5F%5Fcodelineno-9-21) method: 'POST',
[](#%5F%5Fcodelineno-9-22) body: formData,
[](#%5F%5Fcodelineno-9-23) });
[](#%5F%5Fcodelineno-9-24)};
`
**Attention**: Avoid the `readData` option for large files. It loads the entire file into memory as a Base64 string, which can crash your app. The fetch-based approach above streams the file instead.
### Convert a HEIC image to JPEG[ΒΆ](#convert-a-heic-image-to-jpeg "Permanent link")
On iOS, photos are often stored in the HEIC format, which many servers and browsers cannot display. Use `convertHeicToJpeg(...)` to convert them. Only available on iOS:
`[](#%5F%5Fcodelineno-10-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-10-2)
[](#%5F%5Fcodelineno-10-3)const convertHeicToJpeg = async () => {
[](#%5F%5Fcodelineno-10-4) const { path } = await FilePicker.convertHeicToJpeg({
[](#%5F%5Fcodelineno-10-5) path: 'path/to/image.heic',
[](#%5F%5Fcodelineno-10-6) });
[](#%5F%5Fcodelineno-10-7)};
`
### Check and request permissions[ΒΆ](#check-and-request-permissions "Permanent link")
Picking files does not require any permissions since the operating system presents the picker. However, if you need the `ACCESS_MEDIA_LOCATION` or `READ_EXTERNAL_STORAGE` permission on Android (see [Installation](#installation)), you can check and request them:
`[](#%5F%5Fcodelineno-11-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-11-2)
[](#%5F%5Fcodelineno-11-3)const checkPermissions = async () => {
[](#%5F%5Fcodelineno-11-4) const result = await FilePicker.checkPermissions();
[](#%5F%5Fcodelineno-11-5)};
[](#%5F%5Fcodelineno-11-6)
[](#%5F%5Fcodelineno-11-7)const requestPermissions = async () => {
[](#%5F%5Fcodelineno-11-8) const result = await FilePicker.requestPermissions();
[](#%5F%5Fcodelineno-11-9)};
`
### Listen for the picker being dismissed[ΒΆ](#listen-for-the-picker-being-dismissed "Permanent link")
On iOS, you can be notified when the user closes the picker without selecting anything:
`[](#%5F%5Fcodelineno-12-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-12-2)
[](#%5F%5Fcodelineno-12-3)const addPickerDismissedListener = async () => {
[](#%5F%5Fcodelineno-12-4) await FilePicker.addListener('pickerDismissed', () => {
[](#%5F%5Fcodelineno-12-5) console.log('Picker was dismissed');
[](#%5F%5Fcodelineno-12-6) });
[](#%5F%5Fcodelineno-12-7)};
`
### Copy a file[ΒΆ](#copy-a-file "Permanent link")
Copy a picked file to a new location, for example into your app's data directory:
`[](#%5F%5Fcodelineno-13-1)import { FilePicker } from '@capawesome/capacitor-file-picker';
[](#%5F%5Fcodelineno-13-2)
[](#%5F%5Fcodelineno-13-3)const copyFile = async () => {
[](#%5F%5Fcodelineno-13-4) await FilePicker.copyFile({
[](#%5F%5Fcodelineno-13-5) from: 'path/to/file',
[](#%5F%5Fcodelineno-13-6) to: 'path/to/destination',
[](#%5F%5Fcodelineno-13-7) });
[](#%5F%5Fcodelineno-13-8)};
`
## API[ΒΆ](#api "Permanent link")
* [checkPermissions()](#checkpermissions)
* [convertHeicToJpeg(...)](#convertheictojpeg)
* [copyFile(...)](#copyfile)
* [pickFiles(...)](#pickfiles)
* [pickDirectory()](#pickdirectory)
* [pickImages(...)](#pickimages)
* [pickMedia(...)](#pickmedia)
* [pickVideos(...)](#pickvideos)
* [requestPermissions(...)](#requestpermissions)
* [addListener('pickerDismissed', ...)](#addlistenerpickerdismissed-)
* [removeAllListeners()](#removealllisteners)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
### checkPermissions()[ΒΆ](#checkpermissions "Permanent link")
`[](#%5F%5Fcodelineno-14-1)checkPermissions() => Promise
`
Check permissions to access files.
Only available on Android.
**Returns:** `Promise<[PermissionStatus](#permissionstatus)>`
**Since:** 6.1.0
---
### convertHeicToJpeg(...)[ΒΆ](#convertheictojpeg "Permanent link")
`[](#%5F%5Fcodelineno-15-1)convertHeicToJpeg(options: ConvertHeicToJpegOptions) => Promise
`
Convert a HEIC image to JPEG.
Only available on iOS.
| Param | Type |
| ----------- | ----------------------------------------------------- |
| **options** | [ConvertHeicToJpegOptions](#convertheictojpegoptions) |
**Returns:** `Promise<[ConvertHeicToJpegResult](#convertheictojpegresult)>`
**Since:** 0.6.0
---
### copyFile(...)[ΒΆ](#copyfile "Permanent link")
`[](#%5F%5Fcodelineno-16-1)copyFile(options: CopyFileOptions) => Promise
`
Copy a file to a new location.
| Param | Type |
| ----------- | ----------------------------------- |
| **options** | [CopyFileOptions](#copyfileoptions) |
**Since:** 7.1.0
---
### pickFiles(...)[ΒΆ](#pickfiles "Permanent link")
`[](#%5F%5Fcodelineno-17-1)pickFiles(options?: PickFilesOptions | undefined) => Promise
`
Open the file picker that allows the user to select one or more files.
| Param | Type |
| ----------- | ------------------------------------- |
| **options** | [PickFilesOptions](#pickfilesoptions) |
**Returns:** `Promise<[PickFilesResult](#pickfilesresult)>`
---
### pickDirectory()[ΒΆ](#pickdirectory "Permanent link")
`[](#%5F%5Fcodelineno-18-1)pickDirectory() => Promise
`
Open a picker dialog that allows the user to select a directory.
Only available on Android and iOS.
**Returns:** `Promise<[PickDirectoryResult](#pickdirectoryresult)>`
**Since:** 6.2.0
---
### pickImages(...)[ΒΆ](#pickimages "Permanent link")
`[](#%5F%5Fcodelineno-19-1)pickImages(options?: PickMediaOptions | undefined) => Promise
`
Pick one or more images from the gallery.
On iOS 13 and older it only allows to pick one image.
Only available on Android and iOS.
| Param | Type |
| ----------- | ------------------------------------- |
| **options** | [PickMediaOptions](#pickmediaoptions) |
**Returns:** `Promise<[PickFilesResult](#pickfilesresult)>`
**Since:** 0.5.3
---
### pickMedia(...)[ΒΆ](#pickmedia "Permanent link")
`[](#%5F%5Fcodelineno-20-1)pickMedia(options?: PickMediaOptions | undefined) => Promise
`
Pick one or more images or videos from the gallery.
On iOS 13 and older it only allows to pick one image or video.
Only available on Android and iOS.
| Param | Type |
| ----------- | ------------------------------------- |
| **options** | [PickMediaOptions](#pickmediaoptions) |
**Returns:** `Promise<[PickFilesResult](#pickfilesresult)>`
**Since:** 0.5.3
---
### pickVideos(...)[ΒΆ](#pickvideos "Permanent link")
`[](#%5F%5Fcodelineno-21-1)pickVideos(options?: PickMediaOptions | undefined) => Promise
`
Pick one or more videos from the gallery.
On iOS 13 and older it only allows to pick one video.
Only available on Android and iOS.
| Param | Type |
| ----------- | ------------------------------------- |
| **options** | [PickMediaOptions](#pickmediaoptions) |
**Returns:** `Promise<[PickFilesResult](#pickfilesresult)>`
**Since:** 0.5.3
---
### requestPermissions(...)[ΒΆ](#requestpermissions "Permanent link")
`[](#%5F%5Fcodelineno-22-1)requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise
`
Request permissions to access files.
Only available on Android.
| Param | Type |
| ----------- | ------------------------------------------------------- |
| **options** | [RequestPermissionsOptions](#requestpermissionsoptions) |
**Returns:** `Promise<[PermissionStatus](#permissionstatus)>`
**Since:** 6.1.0
---
### addListener('pickerDismissed', ...)[ΒΆ](#addlistenerpickerdismissed "Permanent link")
`[](#%5F%5Fcodelineno-23-1)addListener(eventName: 'pickerDismissed', listenerFunc: () => void) => Promise
`
Called when the file picker is dismissed.
Only available on iOS.
| Param | Type |
| ---------------- | ----------------- |
| **eventName** | 'pickerDismissed' |
| **listenerFunc** | () => void |
**Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>`
**Since:** 0.6.2
---
### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link")
`[](#%5F%5Fcodelineno-24-1)removeAllListeners() => Promise
`
Remove all listeners for this plugin.
**Since:** 0.6.2
---
### Interfaces[ΒΆ](#interfaces "Permanent link")
#### PermissionStatus[ΒΆ](#permissionstatus "Permanent link")
| Prop | Type | Description | Since |
| ----------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----- |
| **accessMediaLocation** | [PermissionState](#permissionstate) | Permission state for accessing media location. On Android, this requests/checks the ACCESS\_MEDIA\_LOCATION permission. | 6.1.0 |
| **readExternalStorage** | [PermissionState](#permissionstate) | Permission state for reading external storage. On Android, this requests/checks the READ\_EXTERNAL\_STORAGE permission. | 6.1.0 |
#### ConvertHeicToJpegResult[ΒΆ](#convertheictojpegresult "Permanent link")
| Prop | Type | Description | Since |
| -------- | ------ | ------------------------------------- | ----- |
| **path** | string | The path of the converted JPEG image. | 0.6.0 |
#### ConvertHeicToJpegOptions[ΒΆ](#convertheictojpegoptions "Permanent link")
| Prop | Type | Description | Since |
| -------- | ------ | --------------------------- | ----- |
| **path** | string | The path of the HEIC image. | 0.6.0 |
#### CopyFileOptions[ΒΆ](#copyfileoptions "Permanent link")
| Prop | Type | Description | Default | Since |
| ------------- | ------- | --------------------------------------------------------------- | ------- | ----- |
| **from** | string | The path of the file to copy. | | 7.1.0 |
| **overwrite** | boolean | Whether to overwrite if the file at destination already exists. | true | 7.2.0 |
| **to** | string | The path to copy the file to. | | 7.1.0 |
#### PickFilesResult[ΒΆ](#pickfilesresult "Permanent link")
| Prop | Type |
| --------- | -------------- |
| **files** | PickedFile\[\] |
#### PickedFile[ΒΆ](#pickedfile "Permanent link")
| Prop | Type | Description | Since |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ----- |
| **blob** | Blob | The Blob instance of the file. Only available on Web. | |
| **data** | string | The Base64 string representation of the data contained in the file. Is only provided if readData is set to true. | |
| **duration** | number | The duration of the video in seconds. Only available on Android and iOS. | 0.5.3 |
| **height** | number | The height of the image or video in pixels. Only available on Android and iOS. | 0.5.3 |
| **mimeType** | string | The mime type of the file. | |
| **modifiedAt** | number | The last modified timestamp of the file in milliseconds. | 0.5.9 |
| **name** | string | The name of the file. | |
| **path** | string | The path of the file. Only available on Android and iOS. | |
| **size** | number | The size of the file in bytes. | |
| **width** | number | The width of the image or video in pixels. Only available on Android and iOS. | 0.5.3 |
#### PickFilesOptions[ΒΆ](#pickfilesoptions "Permanent link")
| Prop | Type | Description | Default | Since |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **types** | string\[\] | List of accepted file types. Look at [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml) for a complete list of standard media types. This option is ignored if limit is set. | | |
| **limit** | number | The maximum number of files that the user can select. Setting this to 0 sets the selection limit to unlimited. Currently, only 0 and 1 are supported. | 0 | 6.0.0 |
| **readData** | boolean | Whether to read the file data. **Attention**: Reading large files can lead to app crashes. It's therefore not recommended to use this option. Instead, use the [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch%5FAPI/Using%5FFetch) to load the file as a blob, see [this example](https://capawesome.io/blog/the-file-handling-guide-for-capacitor/#read-a-file). | false | |
#### PickDirectoryResult[ΒΆ](#pickdirectoryresult "Permanent link")
| Prop | Type | Description | Since |
| -------- | ------ | ----------------------------------- | ----- |
| **path** | string | The path to the selected directory. | 6.2.0 |
#### PickMediaOptions[ΒΆ](#pickmediaoptions "Permanent link")
| Prop | Type | Description | Default | Since |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **readData** | boolean | Whether to read the file data. | false | |
| **skipTranscoding** | boolean | Whether to avoid transcoding, if possible. On iOS, for example, HEIC images are automatically transcoded to JPEG. Only available on iOS. | true | |
| **limit** | number | The maximum number of files that the user can select. Setting this to 0 sets the selection limit to unlimited. On Android and Web, only 0 and 1 are supported. | 0 | 5.2.0 |
| **ordered** | boolean | Whether an ordered number is displayed instead of a check mark in the selection badge. Only available on iOS (15+). | false | 5.3.0 |
#### RequestPermissionsOptions[ΒΆ](#requestpermissionsoptions "Permanent link")
| Prop | Type | Description | Default | Since |
| --------------- | ------------------ | --------------------------- | ------------------------------------------------ | ----- |
| **permissions** | PermissionType\[\] | The permissions to request. | \["accessMediaLocation", "readExternalStorage"\] | 6.1.0 |
#### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link")
| Prop | Type |
| ---------- | ------------------- |
| **remove** | () => Promise |
### Type Aliases[ΒΆ](#type-aliases "Permanent link")
#### PermissionState[ΒΆ](#permissionstate "Permanent link")
`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`
#### PickImagesOptions[ΒΆ](#pickimagesoptions "Permanent link")
`[PickMediaOptions](#pickmediaoptions)`
#### PickImagesResult[ΒΆ](#pickimagesresult "Permanent link")
`[PickMediaResult](#pickmediaresult)`
#### PickMediaResult[ΒΆ](#pickmediaresult "Permanent link")
`[PickFilesResult](#pickfilesresult)`
#### PickVideosOptions[ΒΆ](#pickvideosoptions "Permanent link")
`[PickMediaOptions](#pickmediaoptions)`
#### PickVideosResult[ΒΆ](#pickvideosresult "Permanent link")
`[PickMediaResult](#pickmediaresult)`
#### PermissionType[ΒΆ](#permissiontype "Permanent link")
`'accessMediaLocation' | 'readExternalStorage'`
## FAQ[ΒΆ](#faq "Permanent link")
### How do I upload a picked file to a server?[ΒΆ](#how-do-i-upload-a-picked-file-to-a-server "Permanent link")
On the Web, the picked file already contains a `Blob` instance that you can append to a `FormData` object. On Android and iOS, load the file as a blob using the Fetch API and the file's path, then upload it the same way. See the [usage example](#upload-a-picked-file-to-a-server) above and [The File Handling Guide for Capacitor](https://capawesome.io/blog/the-file-handling-guide-for-capacitor/) for a complete walkthrough.
### Why does my app crash when picking large files?[ΒΆ](#why-does-my-app-crash-when-picking-large-files "Permanent link")
This usually happens when the `readData` option is enabled. It reads the entire file into memory as a Base64 string, which can exceed the available memory for large files. Keep `readData` disabled (the default) and load the file as a blob using the Fetch API instead, as shown in the [usage example](#upload-a-picked-file-to-a-server) above.
### What is the difference between `pickFiles`, `pickImages`, `pickMedia` and `pickVideos`?[ΒΆ](#what-is-the-difference-between-pickfiles-pickimages-pickmedia-and-pickvideos "Permanent link")
The `pickFiles(...)` method opens the system file picker and supports any file type on Android, iOS and Web. The `pickImages(...)`, `pickVideos(...)` and `pickMedia(...)` methods open the photo gallery instead, which provides a more familiar experience for selecting photos and videos, and are only available on Android and iOS.
### Do I need any runtime permissions to pick files?[ΒΆ](#do-i-need-any-runtime-permissions-to-pick-files "Permanent link")
No, picking files itself does not require any runtime permissions because the operating system presents the picker on behalf of your app. On Android, the `ACCESS_MEDIA_LOCATION` permission is only needed to retrieve unredacted EXIF metadata from photos, and `READ_EXTERNAL_STORAGE` is only needed to read files from external storage. On iOS, no privacy descriptions are required.
### How is this plugin different from the Capacitor Camera and Filesystem plugins?[ΒΆ](#how-is-this-plugin-different-from-the-capacitor-camera-and-filesystem-plugins "Permanent link")
The Capacitor Camera plugin takes a photo with the camera or picks images from the gallery, but it does not support other file types. The Capacitor Filesystem plugin reads and writes files at known paths, but it does not provide any user interface for selecting them. The File Picker plugin fills this gap: it lets the user select any file, directory, image, or video and returns its path and metadata, which you can then process with other plugins.
### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link")
Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
## Related Plugins[ΒΆ](#related-plugins "Permanent link")
* [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open a picked file with the default application.
* [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress images before uploading them.
* [Zip](https://capawesome.io/docs/sdks/capacitor/zip/): Zip and unzip files and directories.
* [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/): Receive files shared from other apps.
## Newsletter[ΒΆ](#newsletter "Permanent link")
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
## Changelog[ΒΆ](#changelog "Permanent link")
See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-picker/CHANGELOG.md).
## License[ΒΆ](#license "Permanent link")
See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-picker/LICENSE).
## Credits[ΒΆ](#credits "Permanent link")
This plugin is based on the [Capacitor File Picker](https://github.com/capawesome-team/capacitor-file-picker) plugin. Thanks to everyone who contributed to the project!
July 8, 2026
Back to top
```json
{"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/file-picker/#article", "headline": "Capacitor File Picker Plugin for Android, iOS & Web", "name": "Capacitor File Picker Plugin for Android, iOS & Web", "description": "Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system. Available for Android, iOS, and Web.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/file-picker/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/file-picker/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/file-picker/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/file-picker/#software", "name": "Capacitor File Picker Plugin for Android, iOS & Web", "description": "Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system. Available for Android, iOS, and Web.", "url": "https://capawesome.io/docs/sdks/capacitor/file-picker/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]}
{"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How do I upload a picked file to a server?", "acceptedAnswer": {"@type": "Answer", "text": "On the Web, the picked file already contains a Blob instance that you can append to a FormData object. On Android and iOS, load the file as a blob using the Fetch API and the file's path, then upload it the same way. See the usage example above and The File Handling Guide for Capacitor for a complete walkthrough."}}, {"@type": "Question", "name": "Why does my app crash when picking large files?", "acceptedAnswer": {"@type": "Answer", "text": "This usually happens when the readData option is enabled. It reads the entire file into memory as a Base64 string, which can exceed the available memory for large files. Keep readData disabled (the default) and load the file as a blob using the Fetch API instead, as shown in the usage example above."}}, {"@type": "Question", "name": "What is the difference between pickFiles, pickImages, pickMedia and pickVideos?", "acceptedAnswer": {"@type": "Answer", "text": "The pickFiles(...) method opens the system file picker and supports any file type on Android, iOS and Web. The pickImages(...), pickVideos(...) and pickMedia(...) methods open the photo gallery instead, which provides a more familiar experience for selecting photos and videos, and are only available on Android and iOS."}}, {"@type": "Question", "name": "Do I need any runtime permissions to pick files?", "acceptedAnswer": {"@type": "Answer", "text": "No, picking files itself does not require any runtime permissions because the operating system presents the picker on behalf of your app. On Android, the ACCESS_MEDIA_LOCATION permission is only needed to retrieve unredacted EXIF metadata from photos, and READ_EXTERNAL_STORAGE is only needed to read files from external storage. On iOS, no privacy descriptions are required."}}, {"@type": "Question", "name": "How is this plugin different from the Capacitor Camera and Filesystem plugins?", "acceptedAnswer": {"@type": "Answer", "text": "The Capacitor Camera plugin takes a photo with the camera or picks images from the gallery, but it does not support other file types. The Capacitor Filesystem plugin reads and writes files at known paths, but it does not provide any user interface for selecting them. The File Picker plugin fills this gap: it lets the user select any file, directory, image, or video and returns its path and metadata, which you can then process with other plugins."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/file-picker/"}
```