--- description: Capacitor File Transfer plugin to download and upload files on Android and iOS with progress events, pause and resume, and background support. title: Capacitor File Transfer Plugin - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/file-transfer.png --- [Skip to content ](#capacitor-file-transfer-plugin) [πŸ“² Introducing **Build Sharing** β€” get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Migration from @capacitor/file-transfer ](#migration-from-capacitorfile-transfer) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Geofences ](/docs/sdks/capacitor/geofences/) * [ 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/) * [ Health ](/docs/sdks/capacitor/health/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ 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/) * [ LLM ](/docs/sdks/capacitor/llm/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ MapLibre ](/docs/sdks/capacitor/maplibre/) * [ 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/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ 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/) * [ Watch ](/docs/sdks/capacitor/watch/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ 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/) * [ Set Up 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/) * Notifications * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Network Restrictions ](/docs/cloud/organizations/network-restrictions/) * [ 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) * [ Migration from @capacitor/file-transfer ](#migration-from-capacitorfile-transfer) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) Build and Ship Mobile Apps Faster Cloud builds, OTA live updates, and automated store releases β€” everything your mobile team needs in one platform. [Start for free ](https://console.cloud.capawesome.io/?utm%5Fsource=docs&utm%5Fmedium=sidebar%5Fcta&utm%5Fcampaign=docs%5Fcta) [See our plans ](https://capawesome.io/pricing/?utm%5Fsource=docs&utm%5Fmedium=sidebar%5Fcta&utm%5Fcampaign=docs%5Fcta) # Capacitor File Transfer Plugin[ΒΆ](#capacitor-file-transfer-plugin "Permanent link") Capacitor plugin for reliable background file uploads and downloads that survive the app being backgrounded. Task-based transfers with pause/resume, progress events, retries, and a persisted task store. [ ![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") The Capacitor File Transfer plugin brings robust, task-based file transfers to your Capacitor app. Here are some of the key features: * ⬆️ **Uploads**: Binary (raw body, e.g. S3 presigned URLs) and `multipart/form-data` uploads. * ⬇️ **Downloads**: Streamed downloads directly to a file on the device. * πŸ”‹ **Background Continuation**: Transfers keep running while the app is in the background β€” a background `URLSession` on iOS and a `dataSync` foreground service driven by our own OkHttp engine on Android. * ⏯️ **Pause & Resume**: Downloads can be paused and resumed, even after the process was killed (via resume data on iOS and HTTP `Range` requests on Android). * πŸ“Š **Progress Events**: Throttled progress events with transferred and total bytes. * πŸ’Ύ **Persisted Tasks**: Transfers are persisted and can be queried after an app restart. * πŸ” **Retries**: Automatic retries with backoff on network errors. * πŸ”’ **Honest Semantics**: No fake pause and no hidden private APIs β€” documented behavior across foreground, background, and force-quit. * 🀝 **Compatibility**: Works hand in hand with the [File Manager](https://capawesome.io/docs/sdks/capacitor/file-manager/), [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugins. * πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * πŸ” **Up-to-date**: Always supports the latest Capacitor version. * ⭐️ **Support**: Priority support from the Capawesome Team. * ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. 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 Transfer plugin is typically used whenever an app needs to move large files between the device and a server, for example: * **Offline-first content**: Download large assets such as videos, maps, or course material for offline use and let the transfer continue while the user leaves the app. * **Media uploads**: Upload photos and videos captured in your app to your own backend or directly to an S3 presigned URL, without blocking the user interface. * **Resumable downloads**: Let users pause and resume large downloads, even after the app process was killed, and retry automatically after network errors. * **Transfer manager UI**: Build a download or upload manager with live progress bars, using the throttled progress events and the persisted task store. * **Wi-Fi-only transfers**: Restrict large transfers to unmetered networks so that users don't consume their mobile data plan. * **Document synchronization**: Keep documents in sync with your backend in the background, then open or compress them with the [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/) and [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/) plugins. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | \>=8.x.x | Active support | ## Demo[ΒΆ](#demo "Permanent link") | Android | iOS | | ------- | --- | ## Installation[ΒΆ](#installation "Permanent link") This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)npm config set //npm.registry.capawesome.io/:_authToken ` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, 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-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-file-transfer` 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-3-1)npm install @capawesome-team/capacitor-file-transfer [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") The plugin declares the `INTERNET`, `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_DATA_SYNC` and `POST_NOTIFICATIONS` permissions and the `dataSync` foreground service in its own manifest, so no manifest changes are required. On Android 13 (API level 33) and higher, the progress notification is only shown if the user has granted the `POST_NOTIFICATIONS` runtime permission. Transfers still run without it β€” only the notification is hidden. Call `requestPermissions()` before starting a transfer if you want the notification to appear: `[](#%5F%5Fcodelineno-4-1)const { notifications } = await FileTransfer.requestPermissions(); [](#%5F%5Fcodelineno-4-2)if (notifications !== 'granted') { [](#%5F%5Fcodelineno-4-3) // The transfer will run, but no progress notification is shown. [](#%5F%5Fcodelineno-4-4)} ` The foreground service notification itself is always shown while a transfer runs β€” Android requires a foreground service to have one. The per-transfer progress notification is opt-in and off by default: `[](#%5F%5Fcodelineno-5-1)await FileTransfer.startDownload({ [](#%5F%5Fcodelineno-5-2) url, [](#%5F%5Fcodelineno-5-3) path, [](#%5F%5Fcodelineno-5-4) androidNotification: { title: 'Downloading', progress: true }, [](#%5F%5Fcodelineno-5-5)}); ` #### Proguard[ΒΆ](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-6-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } [](#%5F%5Fcodelineno-6-2)-keep class okhttp3.** { *; } [](#%5F%5Fcodelineno-6-3)-keep class okio.** { *; } ` #### Variables[ΒΆ](#variables "Permanent link") If needed, you can define the following project variable in your app’s `variables.gradle` file to change the default version of the dependency: * `$okhttpVersion` version of `com.squareup.okhttp3:okhttp` (default: `4.12.0`) This can be useful if you encounter dependency conflicts with other plugins in your project. ### iOS[ΒΆ](#ios "Permanent link") The plugin uses a background `URLSession` so that transfers continue while your app is suspended. When a transfer finishes while the app is not running, iOS relaunches the app in the background and needs the transfer's completion handler to be forwarded to the plugin. Add the following method to your app's `AppDelegate.swift` to forward the handler: `[](#%5F%5Fcodelineno-7-1)import Foundation [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)extension AppDelegate { [](#%5F%5Fcodelineno-7-4) func application( [](#%5F%5Fcodelineno-7-5) _ application: UIApplication, [](#%5F%5Fcodelineno-7-6) handleEventsForBackgroundURLSession identifier: String, [](#%5F%5Fcodelineno-7-7) completionHandler: @escaping () -> Void [](#%5F%5Fcodelineno-7-8) ) { [](#%5F%5Fcodelineno-7-9) NotificationCenter.default.post( [](#%5F%5Fcodelineno-7-10) name: Notification.Name("io.capawesome.capacitorjs.plugins.filetransfer.handleEventsForBackgroundURLSession"), [](#%5F%5Fcodelineno-7-11) object: completionHandler [](#%5F%5Fcodelineno-7-12) ) [](#%5F%5Fcodelineno-7-13) } [](#%5F%5Fcodelineno-7-14)} ` Without this hook, background transfers still complete, but iOS may not be able to wake your app to deliver the final events promptly. ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to download and upload files, listen for transfer events, pause, resume, and cancel transfers, and retrieve known transfers. ### Download a file[ΒΆ](#download-a-file "Permanent link") Start a background download with `startDownload(...)`. The method resolves immediately with the identifier of the transfer, while the download itself continues in the background: `[](#%5F%5Fcodelineno-8-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const startDownload = async () => { [](#%5F%5Fcodelineno-8-4) const { id } = await FileTransfer.startDownload({ [](#%5F%5Fcodelineno-8-5) url: 'https://example.com/file.zip', [](#%5F%5Fcodelineno-8-6) path: '/path/to/destination/file.zip', [](#%5F%5Fcodelineno-8-7) headers: { [](#%5F%5Fcodelineno-8-8) Authorization: 'Bearer ', [](#%5F%5Fcodelineno-8-9) }, [](#%5F%5Fcodelineno-8-10) network: 'unmetered', [](#%5F%5Fcodelineno-8-11) maxRetries: 3, [](#%5F%5Fcodelineno-8-12) androidNotification: { [](#%5F%5Fcodelineno-8-13) title: 'Downloading file', [](#%5F%5Fcodelineno-8-14) text: 'The file is being downloaded.', [](#%5F%5Fcodelineno-8-15) }, [](#%5F%5Fcodelineno-8-16) }); [](#%5F%5Fcodelineno-8-17) return id; [](#%5F%5Fcodelineno-8-18)}; ` ### Upload a file[ΒΆ](#upload-a-file "Permanent link") Upload a file from the device with `startUpload(...)`. By default, the file is sent as a `multipart/form-data` request, where `fileField` defines the name of the form field that contains the file and `formFields` adds further fields to the request: `[](#%5F%5Fcodelineno-9-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const startUpload = async () => { [](#%5F%5Fcodelineno-9-4) const { id } = await FileTransfer.startUpload({ [](#%5F%5Fcodelineno-9-5) url: 'https://example.com/upload', [](#%5F%5Fcodelineno-9-6) path: '/path/to/source/file.jpg', [](#%5F%5Fcodelineno-9-7) uploadType: 'multipart', [](#%5F%5Fcodelineno-9-8) fileField: 'file', [](#%5F%5Fcodelineno-9-9) mimeType: 'image/jpeg', [](#%5F%5Fcodelineno-9-10) formFields: { [](#%5F%5Fcodelineno-9-11) albumId: '42', [](#%5F%5Fcodelineno-9-12) }, [](#%5F%5Fcodelineno-9-13) }); [](#%5F%5Fcodelineno-9-14) return id; [](#%5F%5Fcodelineno-9-15)}; ` ### Upload to an S3 presigned URL[ΒΆ](#upload-to-an-s3-presigned-url "Permanent link") Presigned URLs expect the raw file as the request body. Use `uploadType: 'binary'` and the `PUT` method: `[](#%5F%5Fcodelineno-10-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const uploadToPresignedUrl = async () => { [](#%5F%5Fcodelineno-10-4) const { id } = await FileTransfer.startUpload({ [](#%5F%5Fcodelineno-10-5) url: 'https://example.com/presigned-url', [](#%5F%5Fcodelineno-10-6) path: '/path/to/source/file.jpg', [](#%5F%5Fcodelineno-10-7) method: 'PUT', [](#%5F%5Fcodelineno-10-8) uploadType: 'binary', [](#%5F%5Fcodelineno-10-9) mimeType: 'image/jpeg', [](#%5F%5Fcodelineno-10-10) }); [](#%5F%5Fcodelineno-10-11) return id; [](#%5F%5Fcodelineno-10-12)}; ` ### Listen for transfer events[ΒΆ](#listen-for-transfer-events "Permanent link") Transfers report their state through events: `transferProgress` is emitted repeatedly while a transfer is running, `transferCompleted` when it succeeds, and `transferFailed` when it fails. Completed and failed events that occur while no listener is registered are retained and delivered as soon as a listener is added: `` [](#%5F%5Fcodelineno-11-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-11-2) [](#%5F%5Fcodelineno-11-3)const addTransferListeners = async () => { [](#%5F%5Fcodelineno-11-4) await FileTransfer.addListener('transferProgress', event => { [](#%5F%5Fcodelineno-11-5) console.log(`Transfer ${event.id}: ${event.bytes}/${event.totalBytes}`); [](#%5F%5Fcodelineno-11-6) }); [](#%5F%5Fcodelineno-11-7) await FileTransfer.addListener('transferCompleted', event => { [](#%5F%5Fcodelineno-11-8) console.log(`Transfer ${event.id} completed: `, event.path); [](#%5F%5Fcodelineno-11-9) }); [](#%5F%5Fcodelineno-11-10) await FileTransfer.addListener('transferFailed', event => { [](#%5F%5Fcodelineno-11-11) console.error(`Transfer ${event.id} failed: `, event.errorCode, event.message); [](#%5F%5Fcodelineno-11-12) }); [](#%5F%5Fcodelineno-11-13)}; `` ### Pause and resume a transfer[ΒΆ](#pause-and-resume-a-transfer "Permanent link") Pause a running download with `pauseTransferById(...)` and continue it later with `resumeTransferById(...)`, using the identifier returned by `startDownload(...)`. Paused downloads survive process death and can therefore also be resumed after an app restart. Uploads cannot be paused in this version: `[](#%5F%5Fcodelineno-12-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-12-2) [](#%5F%5Fcodelineno-12-3)const pauseTransferById = async (id: string) => { [](#%5F%5Fcodelineno-12-4) await FileTransfer.pauseTransferById({ id }); [](#%5F%5Fcodelineno-12-5)}; [](#%5F%5Fcodelineno-12-6) [](#%5F%5Fcodelineno-12-7)const resumeTransferById = async (id: string) => { [](#%5F%5Fcodelineno-12-8) await FileTransfer.resumeTransferById({ id }); [](#%5F%5Fcodelineno-12-9)}; ` ### Cancel a transfer[ΒΆ](#cancel-a-transfer "Permanent link") Cancel a running or paused transfer with `cancelTransferById(...)`. Any partially transferred data is deleted, so the transfer cannot be resumed afterwards: `[](#%5F%5Fcodelineno-13-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-13-2) [](#%5F%5Fcodelineno-13-3)const cancelTransferById = async (id: string) => { [](#%5F%5Fcodelineno-13-4) await FileTransfer.cancelTransferById({ id }); [](#%5F%5Fcodelineno-13-5)}; ` ### Retrieve transfers[ΒΆ](#retrieve-transfers "Permanent link") Get a single transfer with `getTransferById(...)` or all known transfers with `getTransfers()`. Transfers are persisted, so both methods also return transfers that were restored after an app restart, for example to rebuild a transfer list on app start: `[](#%5F%5Fcodelineno-14-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-14-2) [](#%5F%5Fcodelineno-14-3)const getTransferById = async (id: string) => { [](#%5F%5Fcodelineno-14-4) const { transfer } = await FileTransfer.getTransferById({ id }); [](#%5F%5Fcodelineno-14-5) return transfer; [](#%5F%5Fcodelineno-14-6)}; [](#%5F%5Fcodelineno-14-7) [](#%5F%5Fcodelineno-14-8)const getRunningTransfers = async () => { [](#%5F%5Fcodelineno-14-9) const { transfers } = await FileTransfer.getTransfers(); [](#%5F%5Fcodelineno-14-10) return transfers.filter(transfer => transfer.state === 'running'); [](#%5F%5Fcodelineno-14-11)}; ` ### Remove all listeners[ΒΆ](#remove-all-listeners "Permanent link") Remove all listeners that your app has registered, for example when a view is destroyed: `[](#%5F%5Fcodelineno-15-1)import { FileTransfer } from '@capawesome-team/capacitor-file-transfer'; [](#%5F%5Fcodelineno-15-2) [](#%5F%5Fcodelineno-15-3)const removeAllListeners = async () => { [](#%5F%5Fcodelineno-15-4) await FileTransfer.removeAllListeners(); [](#%5F%5Fcodelineno-15-5)}; ` ## API[ΒΆ](#api "Permanent link") * [cancelTransferById(...)](#canceltransferbyid) * [checkPermissions()](#checkpermissions) * [getTransferById(...)](#gettransferbyid) * [getTransfers()](#gettransfers) * [pauseTransferById(...)](#pausetransferbyid) * [requestPermissions()](#requestpermissions) * [resumeTransferById(...)](#resumetransferbyid) * [startDownload(...)](#startdownload) * [startUpload(...)](#startupload) * [addListener('transferCompleted', ...)](#addlistenertransfercompleted-) * [addListener('transferFailed', ...)](#addlistenertransferfailed-) * [addListener('transferProgress', ...)](#addlistenertransferprogress-) * [removeAllListeners()](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### cancelTransferById(...)[ΒΆ](#canceltransferbyid "Permanent link") `[](#%5F%5Fcodelineno-16-1)cancelTransferById(options: CancelTransferByIdOptions) => Promise ` Cancel a running or paused transfer and delete any partially transferred data. | Param | Type | | ----------- | ------------------------------------------------------- | | **options** | [CancelTransferByIdOptions](#canceltransferbyidoptions) | **Since:** 0.0.1 --- ### checkPermissions()[ΒΆ](#checkpermissions "Permanent link") `[](#%5F%5Fcodelineno-17-1)checkPermissions() => Promise ` Check the current permission status. **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 0.0.1 --- ### getTransferById(...)[ΒΆ](#gettransferbyid "Permanent link") `[](#%5F%5Fcodelineno-18-1)getTransferById(options: GetTransferByIdOptions) => Promise ` Get a single transfer by its identifier. | Param | Type | | ----------- | ------------------------------------------------- | | **options** | [GetTransferByIdOptions](#gettransferbyidoptions) | **Returns:** `Promise<[GetTransferByIdResult](#gettransferbyidresult)>` **Since:** 0.0.1 --- ### getTransfers()[ΒΆ](#gettransfers "Permanent link") `[](#%5F%5Fcodelineno-19-1)getTransfers() => Promise ` Get all known transfers, including transfers that were restored after an app restart. **Returns:** `Promise<[GetTransfersResult](#gettransfersresult)>` **Since:** 0.0.1 --- ### pauseTransferById(...)[ΒΆ](#pausetransferbyid "Permanent link") `[](#%5F%5Fcodelineno-20-1)pauseTransferById(options: PauseTransferByIdOptions) => Promise ` Pause a running transfer. Downloads are paused so that they survive process death and can be resumed later. Uploads and downloads that are not resumable cannot be paused and are rejected with the `TRANSFER_NOT_PAUSABLE` error code. | Param | Type | | ----------- | ----------------------------------------------------- | | **options** | [PauseTransferByIdOptions](#pausetransferbyidoptions) | **Since:** 0.0.1 --- ### requestPermissions()[ΒΆ](#requestpermissions "Permanent link") `[](#%5F%5Fcodelineno-21-1)requestPermissions() => Promise ` Request permission to post the progress notification. On **Android 12 and older**, on **iOS** and on the **web**, this resolves without prompting since no notification permission is required. **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 0.0.1 --- ### resumeTransferById(...)[ΒΆ](#resumetransferbyid "Permanent link") `[](#%5F%5Fcodelineno-22-1)resumeTransferById(options: ResumeTransferByIdOptions) => Promise ` Resume a paused transfer. | Param | Type | | ----------- | ------------------------------------------------------- | | **options** | [ResumeTransferByIdOptions](#resumetransferbyidoptions) | **Since:** 0.0.1 --- ### startDownload(...)[ΒΆ](#startdownload "Permanent link") `[](#%5F%5Fcodelineno-23-1)startDownload(options: StartDownloadOptions) => Promise ` Start a background download and immediately return its identifier. The download continues while the app is in the background. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------- | | **options** | [StartDownloadOptions](#startdownloadoptions) | **Returns:** `Promise<[StartDownloadResult](#startdownloadresult)>` **Since:** 0.0.1 --- ### startUpload(...)[ΒΆ](#startupload "Permanent link") `[](#%5F%5Fcodelineno-24-1)startUpload(options: StartUploadOptions) => Promise ` Start a background upload and immediately return its identifier. The upload continues while the app is in the background. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [StartUploadOptions](#startuploadoptions) | **Returns:** `Promise<[StartUploadResult](#startuploadresult)>` **Since:** 0.0.1 --- ### addListener('transferCompleted', ...)[ΒΆ](#addlistenertransfercompleted "Permanent link") `[](#%5F%5Fcodelineno-25-1)addListener(eventName: 'transferCompleted', listenerFunc: (event: TransferCompletedEvent) => void) => Promise ` Called when a transfer completes successfully. Completed events that occur while no listener is registered are retained and delivered once a listener is added. | Param | Type | | ---------------- | ------------------------------------------------------------------ | | **eventName** | 'transferCompleted' | | **listenerFunc** | (event: [TransferCompletedEvent](#transfercompletedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.0.1 --- ### addListener('transferFailed', ...)[ΒΆ](#addlistenertransferfailed "Permanent link") `[](#%5F%5Fcodelineno-26-1)addListener(eventName: 'transferFailed', listenerFunc: (event: TransferFailedEvent) => void) => Promise ` Called when a transfer fails. Failed events that occur while no listener is registered are retained and delivered once a listener is added. | Param | Type | | ---------------- | ------------------------------------------------------------ | | **eventName** | 'transferFailed' | | **listenerFunc** | (event: [TransferFailedEvent](#transferfailedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.0.1 --- ### addListener('transferProgress', ...)[ΒΆ](#addlistenertransferprogress "Permanent link") `[](#%5F%5Fcodelineno-27-1)addListener(eventName: 'transferProgress', listenerFunc: (event: TransferProgressEvent) => void) => Promise ` Called repeatedly while a transfer is running to report its progress. The event is throttled to roughly one emission every 100 milliseconds per transfer. | Param | Type | | ---------------- | ---------------------------------------------------------------- | | **eventName** | 'transferProgress' | | **listenerFunc** | (event: [TransferProgressEvent](#transferprogressevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.0.1 --- ### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link") `[](#%5F%5Fcodelineno-28-1)removeAllListeners() => Promise ` Remove all listeners for this plugin. **Since:** 0.0.1 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### CancelTransferByIdOptions[ΒΆ](#canceltransferbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ----------------------------------------- | ----- | | **id** | string | The identifier of the transfer to cancel. | 0.0.1 | #### PermissionStatus[ΒΆ](#permissionstatus "Permanent link") | Prop | Type | Description | Since | | ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **notifications** | [PermissionState](#permissionstate) | Permission state for posting notifications. The progress notification is only shown if this is granted. Transfers still run without it. On **Android 12 and older**, on **iOS** and on the **web**, this is always granted since no notification permission is required. | 0.0.1 | #### GetTransferByIdResult[ΒΆ](#gettransferbyidresult "Permanent link") | Prop | Type | Description | Since | | ------------ | --------------------- | --------------------------------------- | ----- | | **transfer** | [Transfer](#transfer) | The transfer with the given identifier. | 0.0.1 | #### Transfer[ΒΆ](#transfer "Permanent link") | Prop | Type | Description | Since | | -------------- | ------------------------------- | ---------------------------------------------------------- | ----- | | **id** | string | The identifier of the transfer. | 0.0.1 | | **type** | [TransferType](#transfertype) | The direction of the transfer. | 0.0.1 | | **state** | [TransferState](#transferstate) | The current state of the transfer. | 0.0.1 | | **url** | string | The URL of the transfer. | 0.0.1 | | **path** | string | The path on the device of the transfer. | 0.0.1 | | **bytes** | number | The number of bytes that have been transferred so far. | 0.0.1 | | **totalBytes** | number \| null | The total number of bytes to transfer, or null if unknown. | 0.0.1 | #### GetTransferByIdOptions[ΒΆ](#gettransferbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | -------------------------------------- | ----- | | **id** | string | The identifier of the transfer to get. | 0.0.1 | #### GetTransfersResult[ΒΆ](#gettransfersresult "Permanent link") | Prop | Type | Description | Since | | ------------- | ------------ | -------------------------------- | ----- | | **transfers** | Transfer\[\] | The list of all known transfers. | 0.0.1 | #### PauseTransferByIdOptions[ΒΆ](#pausetransferbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ---------------------------------------- | ----- | | **id** | string | The identifier of the transfer to pause. | 0.0.1 | #### ResumeTransferByIdOptions[ΒΆ](#resumetransferbyidoptions "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | ----------------------------------------- | ----- | | **id** | string | The identifier of the transfer to resume. | 0.0.1 | #### StartDownloadResult[ΒΆ](#startdownloadresult "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | --------------------------------------- | ----- | | **id** | string | The identifier of the started transfer. | 0.0.1 | #### StartDownloadOptions[ΒΆ](#startdownloadoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **androidNotification** | [TransferNotificationOptions](#transfernotificationoptions) | The configuration of the foreground service notification. Only available on Android. | | 0.0.1 | | **url** | string | The URL to download the file from. | | 0.0.1 | | **path** | string | The path on the device where the downloaded file should be stored. | | 0.0.1 | | **headers** | Record | The HTTP headers to send with the request. | | 0.0.1 | | **method** | 'GET' \| 'POST' | The HTTP method to use for the request. | 'GET' | 0.0.1 | | **network** | [TransferNetwork](#transfernetwork) | The network type that is required for the transfer to run. Use 'unmetered' to only run the transfer on unmetered networks (e.g. Wi-Fi). The transfer waits until such a network is available. On **Android**, it stays in the pending state while waiting. | 'any' | 0.0.1 | | **resumable** | boolean | Whether the download may be resumed after a pause or an interruption. Requires the server to support the HTTP Range header. | true | 0.0.1 | | **maxRetries** | number | The maximum number of times the transfer is retried after a network error. | 0 | 0.0.1 | #### TransferNotificationOptions[ΒΆ](#transfernotificationoptions "Permanent link") The configuration of the Android foreground service notification. Only available on Android. | Prop | Type | Description | Default | Since | | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----- | | **title** | string | The title of the notification. | | 0.0.1 | | **progress** | boolean | Whether to show a separate notification with a progress bar for this transfer. The foreground service notification is always shown while a transfer runs, because Android requires it. This option only adds the per-transfer progress notification. | false | 0.0.1 | | **text** | string | The text of the notification. | | 0.0.1 | | **channelName** | string | The name of the notification channel. | 'File Transfer' | 0.0.1 | #### StartUploadResult[ΒΆ](#startuploadresult "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | --------------------------------------- | ----- | | **id** | string | The identifier of the started transfer. | 0.0.1 | #### StartUploadOptions[ΒΆ](#startuploadoptions "Permanent link") | Prop | Type | Description | Default | Since | | ----------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----- | | **androidNotification** | [TransferNotificationOptions](#transfernotificationoptions) | The configuration of the foreground service notification. Only available on Android. | | 0.0.1 | | **url** | string | The URL to upload the file to. | | 0.0.1 | | **path** | string | The path on the device of the file to upload. | | 0.0.1 | | **method** | 'POST' \| 'PUT' | The HTTP method to use for the request. | 'POST' | 0.0.1 | | **uploadType** | [TransferUploadType](#transferuploadtype) | The type of upload to perform. Use 'binary' to send the raw file as the request body (e.g. for S3 presigned URLs) or 'multipart' to send a multipart/form-data request. | 'multipart' | 0.0.1 | | **fileField** | string | The name of the form field that contains the file. Only used when uploadType is 'multipart'. | 'file' | 0.0.1 | | **mimeType** | string | The MIME type of the file to upload. | | 0.0.1 | | **formFields** | Record | The additional form fields to send with the request. Only used when uploadType is 'multipart'. | | 0.0.1 | | **headers** | Record | The HTTP headers to send with the request. | | 0.0.1 | | **network** | [TransferNetwork](#transfernetwork) | The network type that is required for the transfer to run. Use 'unmetered' to only run the transfer on unmetered networks (e.g. Wi-Fi). The transfer waits until such a network is available. On **Android**, it stays in the pending state while waiting. | 'any' | 0.0.1 | | **maxRetries** | number | The maximum number of times the transfer is retried after a network error. | 0 | 0.0.1 | #### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link") | Prop | Type | | ---------- | ------------------- | | **remove** | () => Promise | #### TransferCompletedEvent[ΒΆ](#transfercompletedevent "Permanent link") | Prop | Type | Description | Since | | ---------------- | -------------- | ------------------------------------------------------------------------------- | ----- | | **id** | string | The identifier of the transfer. | 0.0.1 | | **path** | string \| null | The path on the device of the transferred file, or null for uploads. | 0.0.1 | | **responseCode** | number \| null | The HTTP status code of the response, or null if not available. | 0.0.1 | | **responseBody** | string \| null | The body of the response, or null if not available. Only available for uploads. | 0.0.1 | #### TransferFailedEvent[ΒΆ](#transferfailedevent "Permanent link") | Prop | Type | Description | Since | | ---------------- | -------------- | --------------------------------------------------------------- | ----- | | **id** | string | The identifier of the transfer. | 0.0.1 | | **errorCode** | string | The error code of the failure. | 0.0.1 | | **message** | string | The error message of the failure. | 0.0.1 | | **responseCode** | number \| null | The HTTP status code of the response, or null if not available. | 0.0.1 | #### TransferProgressEvent[ΒΆ](#transferprogressevent "Permanent link") | Prop | Type | Description | Since | | -------------- | -------------- | ---------------------------------------------------------------------------- | ----- | | **id** | string | The identifier of the transfer. | 0.0.1 | | **bytes** | number | The number of bytes that have been transferred so far. | 0.0.1 | | **totalBytes** | number \| null | The total number of bytes to transfer, or null if unknown. | 0.0.1 | | **progress** | number \| null | The progress of the transfer as a value between 0 and 1, or null if unknown. | 0.0.1 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### PermissionState[ΒΆ](#permissionstate "Permanent link") `'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'` #### TransferType[ΒΆ](#transfertype "Permanent link") The direction of a transfer. `'download' | 'upload'` #### TransferState[ΒΆ](#transferstate "Permanent link") The current state of a transfer. `'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'canceled'` #### TransferNetwork[ΒΆ](#transfernetwork "Permanent link") The network type that is required for a transfer to run. `'any' | 'unmetered'` #### TransferUploadType[ΒΆ](#transferuploadtype "Permanent link") The type of upload to perform. `'binary' | 'multipart'` ## Migration from `@capacitor/file-transfer`[ΒΆ](#migration-from-capacitorfile-transfer "Permanent link") | @capacitor/file-transfer | @capawesome-team/capacitor-file-transfer | | ---------------------------- | ---------------------------------------------------------------------------------------- | | downloadFile({ url, path }) | startDownload({ url, path }) β†’ returns { id } and continues in the background | | uploadFile({ url, path }) | startUpload({ url, path }) β†’ returns { id } and continues in the background | | addListener('progress', ...) | addListener('transferProgress', ...) | | _No equivalent_ | pauseTransferById, resumeTransferById, cancelTransferById, getTransferById, getTransfers | | _No equivalent_ | transferCompleted and transferFailed events | Transfers are asynchronous: `startDownload(...)` and `startUpload(...)` resolve immediately with a transfer `id`, and you observe completion through the `transferCompleted` and `transferFailed` events. ## FAQ[ΒΆ](#faq "Permanent link") ### Do transfers continue when the app is in the background?[ΒΆ](#do-transfers-continue-when-the-app-is-in-the-background "Permanent link") Yes. On Android, transfers keep running in a `dataSync` foreground service, and on iOS, in a background `URLSession`. The following table summarizes what happens to a transfer in each app state: | App State | Android | iOS | | ----------------------------- | ----------------------------------------------------- | ---------------------------------------------- | | Foreground | Runs. | Runs. | | Backgrounded | Runs (via the dataSync foreground service). | Runs (via the background URLSession). | | Killed by the OS (low memory) | Interrupted; restored as failed, downloads resumable. | Continued by the OS and delivered on relaunch. | | Force-quit by the user | Interrupted; restored as failed, downloads resumable. | Canceled by the OS (documented OS behavior). | Resuming an interrupted download requires the server to support the HTTP `Range` header. ### Can I pause an upload?[ΒΆ](#can-i-pause-an-upload "Permanent link") Not in this version. Plain HTTP uploads have no standard resume mechanism, so `pauseTransferById(...)` rejects for uploads instead of faking it with a suspend. Downloads, on the other hand, can be paused and resumed at any time, even after the app process was killed. ### Is this available on the web?[ΒΆ](#is-this-available-on-the-web "Permanent link") No. Transfers require a native background API, so `startDownload(...)` and `startUpload(...)` reject as unavailable on the web, as do `pauseTransferById(...)` and `resumeTransferById(...)`. The remaining methods are implemented and simply report that no transfer exists. ### How is this plugin different from the `@capacitor/file-transfer` plugin?[ΒΆ](#how-is-this-plugin-different-from-the-capacitorfile-transfer-plugin "Permanent link") This plugin offers advanced features such as background continuation on Android and iOS, pause and resume that survives process death, a task-based API with a persisted task store, throttled progress events, automatic retries, and network constraints, and comes with priority support from the Capawesome Team. See the [Migration from @capacitor/file-transfer](#migration-from-capacitorfile-transfer) section for a side-by-side overview of both APIs. ### 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 Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress files before uploading them. * [File Manager](https://capawesome.io/docs/sdks/capacitor/file-manager/): Access and manage the user's storage natively. * [File Opener](https://capawesome.io/docs/sdks/capacitor/file-opener/): Open the transferred files in another app. ## 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-transfer/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-transfer/BREAKING.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/file-transfer/LICENSE). August 15, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/file-transfer/#article", "headline": "Capacitor File Transfer Plugin", "name": "Capacitor File Transfer Plugin", "description": "Capacitor File Transfer plugin to download and upload files on Android and iOS with progress events, pause and resume, and background support.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/file-transfer/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/file-transfer/", "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-transfer/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/file-transfer/#software", "name": "Capacitor File Transfer Plugin", "description": "Capacitor File Transfer plugin to download and upload files on Android and iOS with progress events, pause and resume, and background support.", "url": "https://capawesome.io/docs/sdks/capacitor/file-transfer/", "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": "Do transfers continue when the app is in the background?", "acceptedAnswer": {"@type": "Answer", "text": "Yes. On Android, transfers keep running in a dataSync foreground service, and on iOS, in a background URLSession. The following table summarizes what happens to a transfer in each app state: App State Android iOS Foreground Runs. Runs. Backgrounded Runs (via the dataSync foreground service). Runs (via the background URLSession). Killed by the OS (low memory) Interrupted; restored as failed, downloads resumable. Continued by the OS and delivered on relaunch. Force-quit by the user Interrupted; restored as failed, downloads resumable. Canceled by the OS (documented OS behavior). Resuming an interrupted download requires the server to support the HTTP Range header."}}, {"@type": "Question", "name": "Can I pause an upload?", "acceptedAnswer": {"@type": "Answer", "text": "Not in this version. Plain HTTP uploads have no standard resume mechanism, so pauseTransferById(...) rejects for uploads instead of faking it with a suspend. Downloads, on the other hand, can be paused and resumed at any time, even after the app process was killed."}}, {"@type": "Question", "name": "Is this available on the web?", "acceptedAnswer": {"@type": "Answer", "text": "No. Transfers require a native background API, so startDownload(...) and startUpload(...) reject as unavailable on the web, as do pauseTransferById(...) and resumeTransferById(...). The remaining methods are implemented and simply report that no transfer exists."}}, {"@type": "Question", "name": "How is this plugin different from the @capacitor/file-transfer plugin?", "acceptedAnswer": {"@type": "Answer", "text": "This plugin offers advanced features such as background continuation on Android and iOS, pause and resume that survives process death, a task-based API with a persisted task store, throttled progress events, automatic retries, and network constraints, and comes with priority support from the Capawesome Team. See the Migration from @capacitor/file-transfer section for a side-by-side overview of both APIs."}}, {"@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-transfer/"} ```