@capgo/capacitor-downloader

Download large files in the background or foreground from your Capacitor app, with pause, resume and progress events. Downloads keep going when users leave the screen.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-downloader in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-downloader to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Downloads: download() starts a task with optional HTTP headers and a wifi-only or cellular network rule.
• Control: pause(), resume() and stop() for each download ID.
• Progress events: downloadProgress, downloadCompleted and downloadFailed listeners.
• Status and files: checkStatus() for a task and getFileInfo() for a downloaded file.
• Platforms: iOS and Android. iOS uses a background URLSession, Android uses DownloadManager. Not available on web.

Why Capacitor Downloader?

A reliable native file downloader built for Capacitor apps that continues downloads even when your app is backgrounded or closed:

• Background downloads - Downloads continue even when app is minimized, backgrounded, or closed (main advantage)
• Progress tracking - Real-time progress updates during downloads
• Network control - Choose between WiFi-only or cellular network downloads
• Custom headers - Add authentication tokens and custom HTTP headers
• Resumable downloads - Pause and resume downloads (platform dependent)
• Event listeners - Monitor download progress, completion, and failures
• Large file support - Handle multi-gigabyte files without memory issues
• Free and open source - No paid services required

Perfect for downloading large media files, offline content, app updates, and any scenario where downloads need to survive app lifecycle events.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/downloader/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-downloader` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-downloader
npx cap sync

API

• download(...)
• pause(...)
• resume(...)
• stop(...)
• checkStatus(...)
• getFileInfo(...)
• addListener('downloadProgress', ...)
• addListener('downloadCompleted', ...)
• addListener('downloadFailed', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces

Capacitor plugin for downloading files with background support. Provides resumable downloads with progress tracking.

download(...)

download(options: DownloadOptions) => Promise<DownloadTask>

Start a new download task.

Returns: Promise<DownloadTask>

pause(...)

pause(options: { id: string; }) => Promise<void>

Pause an active download. Download can be resumed later from the same position.

resume(...)

resume(options: { id: string; }) => Promise<void>

Resume a paused download. Continues from where it was paused.

stop(...)

stop(options: { id: string; }) => Promise<void>

Stop and cancel a download permanently. Downloaded data will be deleted.

checkStatus(...)

checkStatus(options: { id: string; }) => Promise<DownloadTask>

Check the current status of a download.

Returns: Promise<DownloadTask>

getFileInfo(...)

getFileInfo(options: { path: string; }) => Promise<{ size: number; type: string; }>

Get information about a downloaded file.

Returns: Promise<{ size: number; type: string; }>

addListener('downloadProgress', ...)

addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; }) => void) => Promise<PluginListenerHandle>

Listen for download progress updates. Fired periodically as download progresses.

Returns: Promise<PluginListenerHandle>

addListener('downloadCompleted', ...)

addListener(eventName: 'downloadCompleted', listenerFunc: (result: { id: string; }) => void) => Promise<PluginListenerHandle>

Listen for download completion. Fired when a download finishes successfully.

Returns: Promise<PluginListenerHandle>

addListener('downloadFailed', ...)

addListener(eventName: 'downloadFailed', listenerFunc: (error: { id: string; error: string; }) => void) => Promise<PluginListenerHandle>

Listen for download failures. Fired when a download encounters an error.

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all event listeners. Cleanup method to prevent memory leaks.

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the plugin version number.

Returns: Promise<{ version: string; }>

Interfaces

DownloadTask

Represents the current state and progress of a download task.

DownloadOptions

Configuration options for starting a download.

PluginListenerHandle

Credit

This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader