Version: v7

@capacitor/file-transfer

The FileTransfer API provides mechanisms for downloading and uploading files.

Install

npm install @capacitor/file-transfer@latest-7
npx cap sync

Example

Download

import { FileTransfer } from '@capacitor/file-transfer';
import { Filesystem, Directory } from '@capacitor/filesystem';

// First get the full file path using Filesystem
const fileInfo = await Filesystem.getUri({
  directory: Directory.Data,
  path: 'downloaded-file.pdf'
});

try {
    // Then use the FileTransfer plugin to download
    await FileTransfer.downloadFile({
        url: 'https://example.com/file.pdf',
        path: fileInfo.uri,
        progress: true
    });
} catch(error) {
    if (error.code === 'OS-PLUG-FLTR-0010') {
      // HTTP error - see `FileTransferError` for details on fields available in `errorData`
      let errorData = error.data;
      this.showError('Upload failed: ' + errorData.httpStatus + '; ' + errorData.body);
    } else {
      // other errors - use `error.code` and `error.message` for more information.
      this.showError('Upload failed: ' + error.code + '; ' + error.message);
    }
}

// Progress events
FileTransfer.addListener('progress', (progress) => {
  console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
});

Upload

import { FileTransfer } from '@capacitor/file-transfer';
import { Filesystem, Directory } from '@capacitor/filesystem';

// First get the full file path using Filesystem
const fileInfo = await Filesystem.getUri({
  directory: Directory.Cache,
  path: 'image_upload.png'
});

try {
    // Then use the FileTransfer plugin to upload
    const result = await FileTransfer.uploadFile({
        url: 'https://example.com/upload_api',
        path: fileInfo.uri,
        chunkedMode: true,
        headers: {
            // Upload uses `multipart/form-data` by default.
            // If you want to avoid that, you can set the 'Content-Type' header explicitly.
            'Content-Type': 'application/octet-stream',
        },
        progress: false
    });
    // get server response and other info from result - see `UploadFileResult` interface
} catch(error) {
    if (error.code === 'OS-PLUG-FLTR-0010') {
      // HTTP error - see `FileTransferError` for details on fields available in `errorData`
      let errorData = error.data;
      this.showError('Upload failed: ' + errorData.httpStatus + '; ' + errorData.body);
    } else {
      // other errors - use `error.code` and `error.message` for more information.
      this.showError('Upload failed: ' + error.code + '; ' + error.message);
    }
}

API

downloadFile(...)
uploadFile(...)
addListener('progress', ...)
removeAllListeners()
Interfaces

Note: Some of the input options come from HttpOptions in @capacitor/core, but the plugin does not use all parameters from HttpOptions. The ones that are used are documented below.

For list of existing error codes, see Errors.

downloadFile(...)

downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>

Perform an HTTP request to a server and download the file to the specified destination.

If the server returns an HTTP error (e.g. 404, 500, etc.), the promise will be rejected. To get information about the HTTP error response when running on Android and iOS (not applicable to web), use the FileTransferError interface available at error.data attribute.

Param	Type
`options`	`DownloadFileOptions`

Returns:

Promise<DownloadFileResult>

Since: 1.0.0

uploadFile(...)

uploadFile(options: UploadFileOptions) => Promise<UploadFileResult>

Perform an HTTP request to upload a file to a server.

If the server returns an HTTP error (e.g. 404, 500, etc.), the promise will be rejected. To get information about the HTTP error response when running Android and iOS (not applicable to web), use the FileTransferError interface available at error.data attribute.

Param	Type
`options`	`UploadFileOptions`

Returns:

Promise<UploadFileResult>

Since: 1.0.0

addListener('progress', ...)

addListener(eventName: "progress", listenerFunc: (progress: ProgressStatus) => void) => Promise<PluginListenerHandle>

Add a listener to file transfer (download or upload) progress events.

Param	Type
`eventName`	`'progress'`
`listenerFunc`	`(progress: ProgressStatus) => void`

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 1.0.0

Interfaces

DownloadFileResult

Prop	Type	Description	Since
`path`	`string`	The path the file was downloaded to.	1.0.0
`blob`	`Blob`	The blob data of the downloaded file. This is only available on web.	1.0.0

DownloadFileOptions

Prop	Type	Description	Since
`url`	`string`	The URL to download the file from.	1.0.0
`path`	`string`	The full file path the downloaded file should be moved to. You may use a plugin like `@capacitor/filesystem` to get a complete file path.	1.0.0
`progress`	`boolean`	If true, progress event will be dispatched on every chunk received. See addListener() for more information. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. Default is `false`.	1.0.0
`method`	`string`	The Http Request method to run. (Default is GET)	1.0.0
`params`	`HttpParams`	URL parameters to append to the request. This `HttpParams` interface comes from `@capacitor/core`.	1.0.0
`headers`	`HttpHeaders`	Http Request headers to send with the request. This `HttpHeaders` interface comes from `@capacitor/core`.	1.0.0
`readTimeout`	`number`	How long to wait to read additional data in milliseconds. Resets each time new data is received. Default is 60,000 milliseconds (1 minute). Not supported on web.	1.0.0
`connectTimeout`	`number`	How long to wait for the initial connection in milliseconds. Default is 60,000 milliseconds (1 minute). In iOS, there's no real distinction between `connectTimeout`and `readTimeout`. Plugin tries to use `connectTimeout`, if not uses `readTimeout`, if not uses default	1.0.0
`disableRedirects`	`boolean`	Sets whether automatic HTTP redirects should be disabled	1.0.0
`shouldEncodeUrlParams`	`boolean`	Use this option if you need to keep the URL unencoded in certain cases (already encoded, azure/firebase testing, etc.). The default is `true`. Not supported on web.	1.0.0

HttpParams

HttpHeaders

UploadFileResult

Prop	Type	Description	Since
`bytesSent`	`number`	Total number of bytes uploaded	1.0.0
`responseCode`	`string`	HTTP response code for the upload	1.0.0
`response`	`string`	HTTP response body from the upload (when available)	1.0.0
`headers`	`{ [key: string]: string; }`	HTTP headers from the upload response (when available)	1.0.0

UploadFileOptions

Prop	Type	Description	Since
`url`	`string`	The URL to upload the file to.	1.0.0
`path`	`string`	Full file path of the file to upload. You may use a plugin like `@capacitor/filesystem` to get a complete file path.	1.0.0
`blob`	`Blob`	Blob data to upload. Will use this instead of path if provided. This is only available on web.	1.0.0
`chunkedMode`	`boolean`	Whether to upload data in a chunked streaming mode. Not supported on web. Note: The upload uses `Content-Type: multipart/form-data`, when `chunkedMode` is `true`. Depending on your backend server, this can cause the upload to fail. If your server expects a raw stream (e.g. `application/octet-stream`), you must explicitly set the `Content-Type` header in `headers`.	1.0.0
`mimeType`	`string`	Mime type of the data to upload. Only used if "Content-Type" header was not provided.	1.0.0
`fileKey`	`string`	Type of form element. The default is set to "file". Only used if "Content-Type" header was not provided.	1.0.0
`progress`	`boolean`	If true, progress event will be dispatched on every chunk received. See addListener() for more information. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. Default is `false`.	1.0.0
`method`	`string`	The Http Request method to run. (Default is POST)	1.0.0
`params`	`HttpParams`	URL parameters to append to the request. This `HttpParams` interface comes from `@capacitor/core`.	1.0.0
`headers`	`HttpHeaders`	Http Request headers to send with the request. This `HttpHeaders` interface comes from `@capacitor/core`.	1.0.0
`readTimeout`	`number`	How long to wait to read additional data in milliseconds. Resets each time new data is received. Default is 60,000 milliseconds (1 minute). Not supported on web.	1.0.0
`connectTimeout`	`number`	How long to wait for the initial connection in milliseconds. Default is 60,000 milliseconds (1 minute). Not supported on web. In iOS, there's no real distinction between `connectTimeout`and `readTimeout`. Plugin tries to use `connectTimeout`, if not uses `readTimeout`, if not uses default	1.0.0
`disableRedirects`	`boolean`	Sets whether automatic HTTP redirects should be disabled. Not supported on web.	1.0.0
`shouldEncodeUrlParams`	`boolean`	Use this option if you need to keep the URL unencoded in certain cases (already encoded, azure/firebase testing, etc.). The default is `true`. Not supported on web.	1.0.0

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

ProgressStatus

Prop	Type	Description	Since
`type`	`'download' \| 'upload'`	The type of transfer operation (download or upload).	1.0.0
`url`	`string`	The url of the file associated with the transfer (download or upload).	1.0.0
`bytes`	`number`	The number of bytes transferred so far.	1.0.0
`contentLength`	`number`	The total number of bytes associated with the file transfer.	1.0.0
`lengthComputable`	`boolean`	Whether or not the contentLength value is relevant. In some situations, the total number of bytes may not be possible to determine.	1.0.0

FileTransferError

Prop	Type	Description	Since
`code`	`string`	Code identifying the error: OS-PLUG-FLTR-XXXX	1.0.0
`message`	`string`	Message informing of what went wrong	1.0.0
`source`	`string`	The source for the file transfer operation (a url for download, a file path for upload)	1.0.0
`target`	`string`	The target of the file transfer operation (a file path for download, a url for upload)	1.0.0
`httpStatus`	`number`	HTTP status code of the server response (if available)	1.0.0
`headers`	`{ [key: string]: string; }`	HTTP headers from the server response (if available)	1.0.0
`body`	`string`	HTTP error response body from the server (if available)	1.0.0
`exception`	`string`	Exception message thrown on native side (if available)	1.0.0

Errors

The plugin returns the following errors with specific codes on iOS, Android, and Web:

Error code	Platform(s)	Description
OS-PLUG-FLTR-0004	Android, iOS	The method's input parameters aren't valid.
OS-PLUG-FLTR-0005	Android, iOS	Invalid server URL was provided or URL is empty.
OS-PLUG-FLTR-0006	Android, iOS	Unable to perform operation, user denied permission request.
OS-PLUG-FLTR-0007	Android, iOS	Operation failed because file does not exist.
OS-PLUG-FLTR-0008	Android, iOS, Web	Failed to connect to server.
OS-PLUG-FLTR-0009	Android, iOS	The server responded with HTTP 304 – Not Modified. If you want to avoid this, check your headers related to HTTP caching.
OS-PLUG-FLTR-0010	Android, iOS	The server responded with an HTTP error status code.
OS-PLUG-FLTR-0011	Android, iOS, Web	The operation failed with an error (generic error).

When handling errors in your application, you can check the error code to determine the specific issue. The error object typically contains additional information such as:

code: The error code (as shown in the table above)
message: A human-readable description of the error
source: The source of the transfer (file path or URL)
target: The target of the transfer (file path or URL)
httpStatus: The HTTP status code (for HTTP errors)
body: The response body (for HTTP errors)
headers: The response headers (for HTTP errors)

Install​

Example​

Download​

Upload​

API​

downloadFile(...)​

uploadFile(...)​

addListener('progress', ...)​

removeAllListeners()​

Interfaces​

DownloadFileResult​

DownloadFileOptions​

HttpParams​

HttpHeaders​

UploadFileResult​

UploadFileOptions​

PluginListenerHandle​

ProgressStatus​

FileTransferError​

Errors​

Contents

Install

Example

Download

Upload

API

downloadFile(...)

uploadFile(...)

addListener('progress', ...)

removeAllListeners()

Interfaces

DownloadFileResult

DownloadFileOptions

HttpParams

HttpHeaders

UploadFileResult

UploadFileOptions

PluginListenerHandle

ProgressStatus

FileTransferError

Errors