---
title: Tracking Upload Progress in Capacitor
description: Why onUploadProgress stays silent with the Capacitor HTTP plugin, and how to wire byte-accurate upload progress events to a progress bar in a Capacitor app.
date:
created: 2026-11-06
updated: 2026-11-06
authors:
- robingenz
categories:
- Capacitor
- Guides
- SDKs
links:
- Capacitor File Transfer: sdks/capacitor/file-transfer.md
faq: true
---
# Tracking Upload Progress in Capacitor
Upload progress in a Capacitor app stops working the moment the Capacitor HTTP plugin is enabled, and the cause is in the patched request object: it never touches the `upload` property of `XMLHttpRequest`, so the `onUploadProgress` callback of Axios and a plain `xhr.upload.onprogress` handler never fire. This guide explains that gap, compares the three ways to get a progress bar back, and wires the byte-accurate `transferProgress` events of the [Capacitor File Transfer plugin](../../sdks/capacitor/file-transfer.md) to a progress bar, including completion, failure and what the bar shows after the app was relaunched. The plugin is part of [Capawesome Insiders](../../insiders/index.md).
**Key takeaways:**
- With `CapacitorHttp` enabled, Capacitor patches `XMLHttpRequest` but never dispatches events on `xhr.upload`, so upload progress handlers stay silent; issue #8241 about it has been open since November 2025.
- The patched `fetch` and `XMLHttpRequest` base64-encode every `File` in a `FormData` before handing the body to native code, so a large upload also costs WebView memory.
- Without `CapacitorHttp`, `xhr.upload.onprogress` works, but the body must be a `Blob` in JavaScript and the upload ends when the operating system suspends the app.
- `startUpload(...)` of the Capacitor File Transfer plugin streams the file from its path in a background `URLSession` on iOS and a foreground service on Android, and `transferProgress` reports `bytes`, `totalBytes` and `progress` about every 100 milliseconds.
- `transferCompleted` carries the `responseCode` and `responseBody` of an upload, and events that fire while no listener is attached are retained until one is added.
## Why handlers stay silent
The Capacitor HTTP plugin replaces `window.fetch` and `XMLHttpRequest` with versions that route requests through native code once `CapacitorHttp.enabled` is `true` in `capacitor.config`. The replacement is a reimplementation, not a proxy, and it leaves parts of the `XMLHttpRequest` contract out. Capacitor's `native-bridge.ts` never references `xhr.upload`, so no `progress`, `load` or `loadend` event is ever dispatched on it. Axios registers its `onUploadProgress` callback on exactly that object, and so does every hand-written `xhr.upload.addEventListener('progress', ...)`. The handlers are attached to an object nobody writes to.
The download side is not better. The patched `send()` dispatches one `progress` event on the request itself, after the whole response has arrived, with `loaded` and `total` both set to the length of the response data. A progress bar fed by that event jumps from zero to 100 percent at the end. [Issue #8241](https://github.com/ionic-team/capacitor/issues/8241){:target="_blank"} in the Capacitor repository describes the upload gap and names the cause: iOS uses a shared `URLSession` without a delegate, and Android wraps the body in a `RequestBody` that reports nothing. The issue was opened on November 14, 2025, closed and reopened on March 5, 2026, and received a reproduction repository on September 10, 2026; a fix has not been published.
A second effect of the patch matters for large files. When the body is a `FormData`, the patched request base64-encodes every `File` entry in JavaScript before the body crosses the bridge, so a 200 MB video becomes a 267 MB string in the WebView before the first byte leaves the device. The Capacitor HTTP documentation itself points at `@capacitor/file-transfer` for uploads and notes that "parsing and transferring large amount of data from native to the web can cause issues".
## Three ways to progress
A Capacitor app has three ways to show upload progress, and they differ in where the bytes come from and what happens when the app leaves the foreground:
| Approach | Progress source | Body | Background | Notes |
| --- | --- | --- | --- | --- |
| `XMLHttpRequest` without `CapacitorHttp` | `xhr.upload.onprogress`, `loaded` and `total` | `Blob` or `FormData` in WebView memory | Ends when iOS suspends the app | Free; `fetch` has no upload progress at all |
| `@capacitor/file-transfer` | `progress` event with `type: 'upload'`, `bytes` and `contentLength`, throttled to 100 ms | File path | Not documented | Official plugin, `uploadFile(...)` with `progress: true` |
| Capacitor File Transfer plugin | `transferProgress` with `bytes`, `totalBytes` and `progress`, about every 100 ms per transfer | File path, multipart or raw binary | Background `URLSession` on iOS, `dataSync` foreground service on Android | Insiders; retries, task store, S3 presigned URLs |
The first row is the one most apps start with, and it works until the file is large or the user switches apps. The WebView keeps the whole body, and iOS suspends the WebView's network activity together with the app. The second row is the Capacitor team's own plugin, whose [documentation](https://capacitorjs.com/docs/apis/file-transfer){:target="_blank"} describes a `progress` option that dispatches events "on every chunk received", throttled to 100 milliseconds on Android and iOS; it says nothing about background execution. The rest of this guide uses the third row, because a progress bar that keeps moving after the user opens another app is the point of the exercise.
## Start the upload
[`startUpload(...)`](../../sdks/capacitor/file-transfer.md#startupload) of the Capacitor File Transfer plugin takes the file's `path` on the device and resolves at once with the `id` of the transfer, while the upload runs natively. By default the plugin sends a `multipart/form-data` request with the file in a field named `file`:
```typescript
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';
const startVideoUpload = async (path: string, albumId: string) => {
const { id } = await FileTransfer.startUpload({
url: 'https://api.example.com/videos',
path,
title: 'Holiday video',
mimeType: 'video/mp4',
fileField: 'video',
formFields: { albumId },
headers: { Authorization: 'Bearer ' },
maxRetries: 3,
});
return id;
};
```
The `path` is a native path, for example the `path` of a photo from `@capacitor/camera` or a file picked with the [Capacitor File Picker plugin](../../sdks/capacitor/file-picker.md), and the plugin streams it straight into the request body. No `Blob`, no base64 and no copy in JavaScript. `title` names the transfer in the Android notification, `maxRetries` retries after network errors with backoff, and `network: 'unmetered'` would hold the upload until the device is on Wi-Fi.
For an S3 presigned URL, switch to the raw body with `uploadType: 'binary'` and `method: 'PUT'`, since presigned URLs expect the file as the request body rather than a form. On Android, call [`setConfig(...)`](../../sdks/capacitor/file-transfer.md#setconfig) once at app start to name the notification and its channel in the user's language. On Android 13 and later, request the notification permission with [`requestPermissions()`](../../sdks/capacitor/file-transfer.md#requestpermissions) if the notification should appear; uploads run either way.
## Wire the progress bar
The [`transferProgress`](../../sdks/capacitor/file-transfer.md#addlistenertransferprogress-) event is where the progress bar gets its numbers. The plugin emits it about every 100 milliseconds per running transfer with `bytes` sent so far, `totalBytes`, and `progress` as a value from `0` to `1`. Both `totalBytes` and `progress` are `null` while the total is unknown. One listener serves every upload in the app when the UI keeps its elements in a map keyed by transfer `id`:
```typescript
import { FileTransfer } from '@capawesome-team/capacitor-file-transfer';
const progressBars = new Map();
const trackUpload = (id: string, bar: HTMLProgressElement) => {
progressBars.set(id, bar);
};
const listenForProgress = async () => {
await FileTransfer.addListener('transferProgress', event => {
const bar = progressBars.get(event.id);
if (!bar) {
return;
}
if (event.progress === null) {
bar.removeAttribute('value');
} else {
bar.value = event.progress;
bar.max = 1;
}
});
};
```
Removing the `value` attribute puts a native `