--- 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/plugins/file-picker.png --- [ Skip to content](#capawesomecapacitor-file-picker) [ πŸŽ‰ Introducing **Capawesome Platform** β€” one platform for Live Updates, Native Builds, App Store Publishing, and Insider SDKs.](https://capawesome.io) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Changelog ](#changelog) * [ License ](#license) * [ Credits ](#credits) * [ Firebase ](/docs/plugins/firebase/) * [ Formbricks ](/docs/plugins/formbricks/) * [ Geocoder ](/docs/plugins/geocoder/) * [ Google Sign-In ](/docs/plugins/google-sign-in/) * [ Grafana Faro ](/docs/plugins/grafana-faro/) * [ libSQL ](/docs/plugins/libsql/) * [ Live Update ](/docs/plugins/live-update/) * [ Managed Configurations ](/docs/plugins/managed-configurations/) * [ Media Session ](/docs/plugins/media-session/) * [ ML Kit ](/docs/plugins/mlkit/) * [ Navigation Bar ](/docs/plugins/navigation-bar/) * [ NFC ](/docs/plugins/nfc/) * [ OAuth ](/docs/plugins/oauth/) * [ Pedometer ](/docs/plugins/pedometer/) * [ Photo Editor ](/docs/plugins/photo-editor/) * [ PostHog ](/docs/plugins/posthog/) * [ Printer ](/docs/plugins/printer/) * [ Purchases ](/docs/plugins/purchases/) * [ RealtimeKit ](/docs/plugins/realtimekit/) * [ Screen Orientation ](/docs/plugins/screen-orientation/) * [ Screenshot ](/docs/plugins/screenshot/) * [ Secure Preferences ](/docs/plugins/secure-preferences/) * [ Speech Recognition ](/docs/plugins/speech-recognition/) * [ Speech Synthesis ](/docs/plugins/speech-synthesis/) * [ Share Target ](/docs/plugins/share-target/) * [ Square Mobile Payments ](/docs/plugins/square-mobile-payments/) * [ SQLite ](/docs/plugins/sqlite/) * [ Superwall ](/docs/plugins/superwall/) * [ Torch ](/docs/plugins/torch/) * [ Wifi ](/docs/plugins/wifi/) * [ Zip ](/docs/plugins/zip/) * [ Cloud ](/docs/cloud/) * [ Live Updates ](/docs/cloud/live-updates/) * Advanced * Integrations * [ Native Builds ](/docs/cloud/native-builds/) * [ Configuration ](/docs/cloud/native-builds/configuration/) * [ Environments ](/docs/cloud/native-builds/environments/) * Guides * [ Sample Projects ](/docs/cloud/native-builds/sample-projects/) * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ Automations ](/docs/cloud/automations/) * [ Assist ](/docs/cloud/assist/) * Account * Organizations * [ Organization and User Management ](/docs/cloud/organizations/memberships/) * [ Single Sign-On (SSO) ](/docs/cloud/organizations/sso/) * [ Teams ](/docs/cloud/organizations/teams/) * [ Two-Factor Authentication ](/docs/cloud/organizations/two-factor-authentication/) * [ Integrations ](/docs/cloud/integrations/) * [ License Keys ](/docs/cloud/license-keys/) * [ Webhooks ](/docs/cloud/webhooks/) * [ Pricing ](https://capawesome.io/pricing/) * [ FAQ ](/docs/cloud/faq/) * [ Support ](/docs/cloud/support/) * [ Contributing ](/docs/contributing/) * [ LLMs ](/docs/llms/) * [ Insiders ](/docs/insiders/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/insiders/support/) * [ FAQ ](/docs/insiders/faq/) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Changelog ](#changelog) * [ License ](#license) * [ Credits ](#credits) # @capawesome/capacitor-file-picker[ΒΆ](#capawesomecapacitor-file-picker "Permanent link") Capacitor plugin that allows the user to select a file, directory, image, or video from the device's file system or gallery. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") We are proud to offer one of the most complete and feature-rich Capacitor plugins for file picking. 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! ## 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/). ## 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 | ## 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") #### 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") `[](#%5F%5Fcodelineno-5-1)import { FilePicker } from '@capawesome/capacitor-file-picker'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const appendFileToFormData = async () => { [](#%5F%5Fcodelineno-5-4) const result = await FilePicker.pickFiles(); [](#%5F%5Fcodelineno-5-5) const file = result.files[0]; [](#%5F%5Fcodelineno-5-6) [](#%5F%5Fcodelineno-5-7) const formData = new FormData(); [](#%5F%5Fcodelineno-5-8) if (file.blob) { [](#%5F%5Fcodelineno-5-9) const rawFile = new File(file.blob, file.name, { [](#%5F%5Fcodelineno-5-10) type: file.mimeType, [](#%5F%5Fcodelineno-5-11) }); [](#%5F%5Fcodelineno-5-12) formData.append('file', rawFile, file.name); [](#%5F%5Fcodelineno-5-13) } [](#%5F%5Fcodelineno-5-14)}; [](#%5F%5Fcodelineno-5-15) [](#%5F%5Fcodelineno-5-16)const checkPermissions = async () => { [](#%5F%5Fcodelineno-5-17) const result = await FilePicker.checkPermissions(); [](#%5F%5Fcodelineno-5-18)}; [](#%5F%5Fcodelineno-5-19) [](#%5F%5Fcodelineno-5-20)const copyFile = async () => { [](#%5F%5Fcodelineno-5-21) const result = await FilePicker.copyFile({ [](#%5F%5Fcodelineno-5-22) from: 'path/to/file', [](#%5F%5Fcodelineno-5-23) to: 'path/to/destination', [](#%5F%5Fcodelineno-5-24) }); [](#%5F%5Fcodelineno-5-25)}; [](#%5F%5Fcodelineno-5-26) [](#%5F%5Fcodelineno-5-27)const pickFiles = async () => { [](#%5F%5Fcodelineno-5-28) const result = await FilePicker.pickFiles({ [](#%5F%5Fcodelineno-5-29) types: ['image/png'], [](#%5F%5Fcodelineno-5-30) }); [](#%5F%5Fcodelineno-5-31)}; [](#%5F%5Fcodelineno-5-32) [](#%5F%5Fcodelineno-5-33)const pickDirectory = async () => { [](#%5F%5Fcodelineno-5-34) const result = await FilePicker.pickDirectory(); [](#%5F%5Fcodelineno-5-35)}; [](#%5F%5Fcodelineno-5-36) [](#%5F%5Fcodelineno-5-37)const pickImages = async () => { [](#%5F%5Fcodelineno-5-38) const result = await FilePicker.pickImages(); [](#%5F%5Fcodelineno-5-39)}; [](#%5F%5Fcodelineno-5-40) [](#%5F%5Fcodelineno-5-41)const pickMedia = async () => { [](#%5F%5Fcodelineno-5-42) const result = await FilePicker.pickMedia(); [](#%5F%5Fcodelineno-5-43)}; [](#%5F%5Fcodelineno-5-44) [](#%5F%5Fcodelineno-5-45)const pickVideos = async () => { [](#%5F%5Fcodelineno-5-46) const result = await FilePicker.pickVideos(); [](#%5F%5Fcodelineno-5-47)}; [](#%5F%5Fcodelineno-5-48) [](#%5F%5Fcodelineno-5-49)const requestPermissions = async () => { [](#%5F%5Fcodelineno-5-50) const result = await FilePicker.requestPermissions(); [](#%5F%5Fcodelineno-5-51)}; ` ## 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-6-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-7-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-8-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-9-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-10-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-11-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-12-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-13-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-14-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-15-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-16-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'` ## 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! May 17, 2026 Back to top