@capacitor/file-transfer

The FileTransfer API provides mechanisms for downloading and uploading files.

Install

npm install @capacitor/file-transfer
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.

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.

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.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 1.0.0

Interfaces

DownloadFileResult

DownloadFileOptions

HttpParams

HttpHeaders

UploadFileResult

UploadFileOptions

PluginListenerHandle

ProgressStatus

FileTransferError

Errors

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

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)